heymoney is a conversational money platform. Skills are the modular capabilities that power it — each one a discrete financial action triggered by natural language. This portal is where you build them.
skill catalogue
Every use case below is a skill waiting to be built. Filter by category or search to find your area.
platform overview
Skills are stateless, single-purpose modules. heymoney's intent router matches a user utterance to a skill, executes it, and returns a structured response to the conversation.
Natural language from the user is parsed and matched to a registered skill using semantic similarity and slot extraction. Ambiguous inputs trigger a clarification turn before dispatch.
A skill is a function that receives a structured intent payload, calls external APIs or data sources, and returns a conversation-ready response object. Skills are stateless and independently deployable.
heymoney's conversation engine maintains session context, orchestrates multi-turn flows, and formats skill responses into natural language that feels like a knowledgeable friend — not a bot.
All skills operate within heymoney's regulatory sandbox. Payments, lending, and insurance skills require partner licensing. The platform handles KYC, AML and CBK compliance at the platform layer.
Skills run in isolated serverless containers with a 5-second SLA. Long-running operations (e.g. tax filing, mortgage applications) are handled via async job patterns with conversational status updates.
Skills earn revenue on every successful execution — transaction fees, referral commissions, and SaaS licensing. heymoney handles billing, settlements and partner reconciliation automatically.
developer guide
A complete walkthrough from idea to deployed skill, accessible to both engineers and product builders.
heymoney skills are the atoms of the platform. Each skill does exactly one thing — it maps a user's financial intent to a real-world action and returns a result to the conversation.
Think of them like financial API wrappers with a natural language interface. A user says "hey money, pay my rent" and the Rent Payment skill handles everything from contact lookup to M-Pesa disbursement to receipt generation.
Every skill is a folder with three files:
my-skill/ ├── skill.json # intent definition, slots, metadata ├── handler.js # execution logic └── responses.json # response templates
Skills are packaged as .hskill archives and submitted via the developer portal or CLI.
Requires Node.js 18+. The CLI scaffolds, tests and deploys your skill.
Choose a use case from the catalogue or define your own. The scaffold generates all three required files.
Describe the phrases your skill responds to and the parameters it needs to extract.
Implement the execute() function. Call your external APIs and return a structured result.
Use the built-in simulator to test against real conversation flows, then submit for review.
# install npm install -g @heymoney/cli # scaffold hm skill create rent-payment # test hm skill test --utterance "pay my rent" # deploy hm skill deploy
The skill.json file is the contract between your skill and the heymoney platform. It defines identity, intents, required slots, and metadata.
{
"id": "rent-payment",
"version": "1.0.0",
"name": "Rent Payment",
"description": "Schedules and executes rental payments to a landlord",
"category": "payments",
"author": "your-dev-id",
"intents": [
{
"phrase": "pay my rent",
"variations": [
"send rent",
"pay landlord",
"rent is due"
]
}
],
"slots": [
{
"name": "amount",
"type": "currency_kes",
"required": false,
"source": "user_profile.rent_amount",
"prompt": "How much is your rent?"
},
{
"name": "landlord",
"type": "contact",
"required": true,
"source": "user_profile.landlord",
"prompt": "Who should I send rent to?"
}
],
"permissions": ["payments.send", "contacts.read"],
"requires_confirmation": true
}
| field | type | description |
|---|---|---|
| id | string | Unique slug, kebab-case. Permanent once published. |
| version | semver | Semantic version. Increment on every change. |
| category | enum | payments · savings · investments · insurance · lending · taxes · lifestyle |
| intents | array | Phrase objects the router uses to match this skill. Include 3–8 variations. |
| slots | array | Parameters the skill needs. Can be pre-filled from user profile. |
| permissions | array | Platform capabilities required. User must consent on first use. |
| requires_confirmation | boolean | Whether platform prompts user to confirm before executing. |
The handler exports a single async execute() function. It receives a context object and must return a result within 5 seconds.
const { mpesa, contacts, receipts } = require('@heymoney/sdk'); module.exports.execute = async (ctx) => { const { user, slots } = ctx; // Resolve landlord contact const landlord = await contacts.resolve(slots.landlord); const amount = slots.amount ?? user.profile.rent_amount; // Execute M-Pesa payment const tx = await mpesa.send({ to: landlord.phone, amount: amount, reference: `Rent – ${user.name}`, narrative: "Monthly rent payment" }); // Generate receipt const receipt = await receipts.generate(tx); return { status: "success", summary: `KES ${amount.toLocaleString()} sent to ${landlord.name}`, data: { transaction_id: tx.id, receipt_url: receipt.url, landlord: landlord.name, amount: amount } }; };
The heymoney SDK provides pre-built connectors for M-Pesa, KRA, NHIF, NSSF, NSE, CBK and 40+ Kenyan financial institutions. You never handle payment credentials directly.
Your handler must return a result object. heymoney's conversation layer translates this into natural language for the user.
{
"status": "success" | "pending" | "error",
"summary": "KES 25,000 sent to James Kamau", // shown to user
"data": {
// structured payload — skill-specific
},
"follow_ups": [
"Check your balance",
"Set a reminder for next month"
] // optional: suggested next actions
}
For async skills (e.g. tax filing), return status: "pending" with a job_id. The platform will poll and update the user when complete.
Slots are the parameters your skill needs to execute. heymoney extracts them from the user's utterance automatically, falling back to profile data, then prompting the user for anything still missing.
| slot type | example | extraction behaviour |
|---|---|---|
| currency_kes | "5,000", "5k", "five thousand" | Normalised to integer KES value |
| contact | "James", "my landlord", "Mum" | Resolved via contacts graph |
| date | "Friday", "end of month", "25th" | Resolved to ISO date relative to today |
| duration | "3 months", "a year" | Resolved to days |
| institution | "Equity", "KCB", "NHIF" | Matched to registered institution ID |
| string | Any free-text value | Passed through as-is |
| boolean | "yes", "no", "nope", "sure" | Normalised to true/false |
| enum | One of a defined set | Fuzzy matched to enum values |
Some skills require multiple exchanges — a loan application, for example, may need income verification, amount negotiation, and term selection before execution.
Declare a flow in your skill.json to define a sequence of turns:
"flow": [ { "step": "collect_amount", "prompt": "How much would you like to borrow?", "slot": "amount" }, { "step": "confirm_term", "prompt": "Over how many months?", "slot": "term_months" }, { "step": "confirm", "type": "confirmation", "message": "Borrow KES {{amount}} over {{term_months}} months at 12% p.a. Proceed?" } ]
The platform manages turn state. Your execute() function is only called after all required slots are resolved and any confirmation is approved.
Use the CLI simulator to run your skill against real conversation scenarios before submission.
# run the interactive simulator hm skill test --interactive # test a specific utterance hm skill test --utterance "pay my landlord 25000" # run the full test suite hm skill test --suite # output ✓ intent matched: rent-payment (confidence: 0.97) ✓ slot extracted: amount = 25000 ✓ slot resolved: landlord = James Kamau (+254712345678) ✓ confirmation prompt rendered ✓ execute() returned in 342ms ✓ response: "KES 25,000 sent to James Kamau"
Skills go through a two-stage review before going live on the platform:
# package and submit hm skill deploy # check status hm skill status rent-payment # output rent-payment@1.0.0 → under review (submitted 2h ago)
Skills earn revenue automatically. heymoney handles all billing, collection and reconciliation.
| model | how it works | typical rate |
|---|---|---|
| transaction fee | % of payment value processed through the skill | 0.1–0.5% |
| referral commission | Fixed fee per successful product sale (insurance, loans) | KES 200–2,000 |
| subscription share | % of monthly platform revenue attributed to your skill's usage | Variable |
| per-execution | Fixed fee per skill invocation (information and utility skills) | KES 2–50 |
Revenue is settled monthly to your registered M-Pesa or bank account. A detailed earnings dashboard is available in the developer portal.
Skills in the government & compliance and health categories are zero-fee to end users. Developers in these categories earn through the per-execution model, funded by heymoney's social impact budget.