Nyaraka za API

Connect your application to the account you use in Momo Business. Start by identifying the account, send to a number you control, then read the saved result. The endpoint reference below provides the exact request fields, response schemas and language examples; this handbook explains how to combine them into a working integration.

Choose the interface

The two credential kinds are deliberately different. An API key cannot authenticate an MCP connection, and an MCP connection token cannot authenticate REST requests. The public OpenAPI document describes HTTP endpoints; the MCP manifest describes tools available through JSON-RPC.

1. Prepare your account

Open API credentials, create an API key and save its value in your server's secret store. You need permission to manage API keys. Confirm your SMS sending identity or WhatsApp business number is configured before attempting a send. A valid credential alone does not establish a usable sending route.

Use the service origin https://business.momo.tz. All examples use illustrative customer data; replace recipients, IDs and URLs with values from your own account. There is no sandbox flag in the send payload. A successful provider call can send a real message.

2. Identify the account

Set MOMO_API_KEY in your development environment without committing it, then run:

curl --silent --show-error \
  'https://business.momo.tz/api/v3/me' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json'

Check data.id and data.name against the account you intended to connect. The tenant comes from the key; sending a tenant_id in the request is not a way to select another account. GET /api/v3/balance returns wallet balance, currency and billing mode for that same account.

3. Send a controlled SMS

curl --silent --show-error \
  'https://business.momo.tz/api/v3/sms/send' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"recipient":"255712345678","sender_id":"MyBrand","message":"Your integration is connected."}'

Replace MyBrand with an approved sender belonging to your account, or omit sender_id to use configured defaults. Keep the returned message uid, numeric id, recipient and status in your application. HTTP 201 means a message record was created. A provider refusal can still produce HTTP 201 with the message's status set to failed.

4. Read the outcome

Call GET /api/v3/sms/{uid} using the saved UID. sent means the provider accepted the message; delivered means a delivery receipt arrived. Some channels do not expose every receipt state. Future scheduled messages return queued until their send attempt.

Add delivery handling before retrying automatically, and use webhooks with polling reconciliation when you need later status changes. Finish by handling 401, 403, 422 and 429 explicitly. The HTTP contracts chapter explains which response envelope applies to each interface.

An API key identifies one account. Keep it on a server you control: a browser bundle, mobile application package or public repository cannot keep an embedded key secret. Your integration should store the plaintext value securely and omit it from request logs, exception reports and copied support examples.

Creating and replacing REST keys

Use Settings → API credentials. Viewing the page requires api-keys.view; creating and revoking keys requires api-keys.manage. Give each integration a recognizable name, up to 160 characters. The create response reveals the plaintext once; subsequent listings do not recover it.

The platform stores a hash of the complete credential. A REST key is generated as a random 64-character string. Do not derive meaning from its contents or build your own key from an account ID. The creation screen does not currently accept a REST expiry setting; if an expiry has been set on a credential, the authentication guard enforces it.

For a planned replacement, create the new key, verify /api/v3/me, update the integration and revoke the old key. Revocation takes effect for subsequent requests. If a key is exposed, revoke it and replace it in every environment that used it. A revoked credential is not restored by sending it again.

Request headers

Authorization: Bearer YOUR_REST_API_KEY
Accept: application/json
Content-Type: application/json

Content-Type describes a request body and is needed when sending JSON. Read-only requests need no body. The REST guard reads the Bearer header, not an API key query parameter. Avoid putting secrets into URLs, where browsers and intermediaries often record them.

Tenant boundaries and permission ceilings

All customer REST endpoints derive their tenant from the key. Resource lookups and mutations stay within that account; changing a resource ID does not change the tenant. A missing foreign record can return 404, while catalogue and order ownership checks can return 403.

Permission checks vary by family:

Data, group, payment and automation endpoints reject a key whose issuer cannot be established or whose issuing user is deactivated. Their permission checks use the issuer's current permissions, so a later role change can remove access. Treat REST keys as powerful account credentials; they do not expose a per-endpoint scope picker.

Authentication failures

Missing, unknown, revoked and expired REST keys return HTTP 401. An MCP credential sent to REST also returns 401. A suspended or inactive account returns 403. Read the response message to distinguish credential failure from account suspension or an endpoint permission refusal.

{"status":"error","message":"API token has been revoked."}

Do not retry these failures in a tight loop. Correct the credential, account state or permission first. MCP has a different authorization model with selected servers and OAuth capabilities; follow MCP connections when connecting an assistant.

Use the documented HTTP method and path exactly. Several compatibility contact operations use POST for reads; a GET to the same URL is not an equivalent request. Send JSON objects for documented JSON bodies and preserve numeric IDs, UUIDs and opaque provider IDs in their original roles.

Response envelopes

Most /api/v3 endpoints wrap successful data:

{"status":"success","data":{"id":42,"name":"Example account"}}

Their errors generally use:

{"status":"error","message":"Validation failed.","errors":{"recipient":["Provide recipient or recipients."]}}

errors is optional. Framework failures on v3, such as unsupported methods and rate limiting, are normalized to this error envelope. Do not require an errors map to recognize an error.

Data endpoints use native objects: {tables:[...]}, {record:{...}}, {records:[...],next_cursor:...} and {ok:true,deleted:1}. Their expected domain refusals carry {error:{code,message,retryable,...},message,code}. Authentication and request-envelope validation may still return the standard v3 error shape. Check for both when building a shared data client.

Payment lists return {data:[...],meta:{current_page,per_page,total,last_page}} and details return {data:{...}}. Automation reads return {events,...}, {subscriptions:[...]} or {schedules:[...]}. These native envelopes do not add a success status.

Agent tasks use their own run status objects, while MCP uses JSON-RPC responses. Do not apply a single response.data accessor across these interfaces.

Identifiers

Public UID examples illustrate the prefix only; do not validate them as a fixed ULID format. A provider catalogue ID, product retailer ID and local product ID also name different things.

Standard page-number pagination

Message, contact and group lists default to 20 rows. Catalogue, product and order lists default to 25. Use limit or per_page, capped at 100; if both appear, limit wins. A nonpositive value uses the endpoint default. Set page=2 for the next page.

{"status":"success","data":{"items":[],"pagination":{"current_page":1,"per_page":20,"last_page":1,"total":0,"has_more_pages":false}}}

Read has_more_pages and increment page until false. These lists can change while you read them; deduplicate by stable resource ID when building a local index. Data records instead use cursor pagination, and history uses a timestamp cursor. Payments use their own meta pagination shape. Automation events use before; subscription and schedule lists have fixed caps and no pagination.

Status handling and rate limits

The v3 limit is 120 requests per minute per Bearer token across its endpoints. Throttled requests return 429; rate headers include X-RateLimit-Limit, X-RateLimit-Remaining and, when throttled, Retry-After and X-RateLimit-Reset. Authentication happens first, so unauthenticated responses may not carry these headers. Provider throughput limits are separate and can defer a message after the HTTP request was accepted.

A send request creates a record and attempts to hand it to the selected provider. Track the record's lifecycle separately from the HTTP request that created it. This distinction prevents both false delivery claims and accidental duplicate messages.

What a send response means

POST /api/v3/sms/send and POST /api/v3/whatsapp/send normally attempt delivery inside the request. Each normalized recipient produces its own message record and its own outcome. A multi-recipient request is processed sequentially; it is not an atomic delivery transaction.

{"status":"success","data":{"messages":[{"id":101,"uid":"msg_example_a","recipient":"255712345678","status":"sent","gateway_message_id":"provider-id-a","error_message":null},{"id":102,"uid":"msg_example_b","recipient":"255754000111","status":"failed","gateway_message_id":null,"error_message":"Recipient rejected by provider"}]}}

This abbreviated example is a successful HTTP 201 response with a mixed delivery result. Save every returned message, including failed ones. A future schedule_time queues the message. Throughput admission can defer an immediate send, and an unexpected inline failure can cause a queue fallback, so an unscheduled request can also return queued.

Status progression

Not every channel provides delivered/read receipts. A sent result is not proof that the person read the message. A missing later receipt is also not enough evidence to resend.

Use GET /api/v3/sms/{uid} or GET /api/v3/whatsapp/{uid} for current state. Lists accept status and direction filters and newest-first pagination. Keep numeric IDs as well as UIDs because message callbacks identify records by numeric message_id.

Retry deliberately

The messaging send endpoints do not implement a request idempotency key. Adding an Idempotency-Key header does not suppress a duplicate send here. Each repeated POST may create a new message, even if your request body is identical.

Maintain an integration-side dispatch ledger keyed by your business event, such as an invoice reminder ID. Record the attempt before sending, then attach returned message IDs. If a connection times out without a response, mark the attempt as uncertain and reconcile against message history and your business records before sending again. Use a recognizable business reference in the message where appropriate; arbitrary metadata is not a supported send input.

The internal message job declares a three-attempt budget, but ordinary provider refusals and most send exceptions mark the record failed. Those are not a promise of three automatic provider retries. Correct invalid numbers, sender configuration, templates or provider account problems before initiating a new send.

Reconcile asynchronous updates

Receive supported message webhooks for timely changes, and poll saved IDs when a callback is missing. Callback delivery is currently best effort with no automatic delivery retry. Spread polling across your rate budget and reduce its frequency after terminal outcomes. Treat each recipient independently; never retry the whole batch because one recipient failed.

Agent tasks do support an idempotency header. That is a different contract and should be implemented separately in your client.

Use the SMS API for a transactional message or a small set of explicit recipients. Use a campaign when the audience comes from stored contact groups. Sending identities and account defaults determine the route; callers do not select a provider channel ID.

Sending identity selection

sender_id is optional. When provided, it must unambiguously match one of:

An identity-specific route is used when configured. Otherwise, the platform uses the account's default SMS channel, or the system default when the account has none. Unknown, ambiguous, inactive or invalid configurations return a validation-style error. An API key cannot make an unapproved sender usable.

GET /api/v3/sms/senders lists every identity this workspace may use, with value being exactly what to pass:

{"status":"success","data":{"items":[{"type":"sender_id","value":"AMINA","label":"AMINA","status":"approved"},{"type":"phone_number","value":"+255700000001","label":"Main line","status":"active"},{"type":"short_code","value":"15551","label":"Promotions","status":"active"}]}}

Only usable identities are listed — a sender ID still under review is not. If you omit sender_id, the configured provider/default determines the sender. Test that configuration with a controlled recipient. The request field tenant_channel_id is not supported as a route override and is ignored; the resolved channel fields in a response are for observation.

Recipient and message fields

{"recipients":["255712345678","255754000111"],"sender_id":"MyBrand","message":"Your order is ready for collection.","message_type":"plain"}

recipient accepts a string separated by commas, semicolons or whitespace. recipients accepts an array whose entries can contain the same separators. Both inputs are merged and exact duplicates removed. Send fully qualified numbers with country calling codes to avoid provider-specific assumptions about national numbers. Recipient formatting is not a number-validity guarantee.

plain, text and sms select ordinary SMS. A compatibility request to /sms/send with message_type:"whatsapp" routes to WhatsApp; new integrations should use the explicit WhatsApp endpoint.

Always supply a meaningful nonempty message. The current SMS controller substitutes a generic body for an empty input; this is not a useful validation mechanism for a business integration.

Length, encoding and cost

The 4,096-character API ceiling is not a promise that the message fits one SMS. A common text encoding uses 160 characters for one segment and 153 per part for multipart SMS; Unicode estimates use 70 and 67. Character encoding, extension characters and provider behavior affect the actual count. Some drivers return a provider segment count; others estimate or use a fallback.

Keep verification codes and notifications concise, and test the exact text you intend to send, especially punctuation, non-Latin text and emoji. A long message can produce multiple billable segments even though it creates one API message record.

Media and results

A media_url can request an MMS-style send on a gateway that supports media. The URL is limited to 2,048 characters; media_type to 32. Supplying media does not guarantee that the chosen SMS provider supports it. For predictable rich media delivery, use an appropriately configured WhatsApp account and its documented payload.

Read every returned status and store its UID. See delivery and duplicate prevention before implementing retries.

POST /api/v3/whatsapp/send supports text, approved templates, media links, interactive messages and reactions. Configure a WhatsApp Cloud connection first. sender_id selects the business number to send from; omitting it uses the workspace default.

Which number: the accounts list

GET /api/v3/whatsapp/accounts is where every WhatsApp identifier in this API comes from:

{"status":"success","data":{"default_phone_number_id":"104512345678901","items":[{"waba_id":"102290129340398","name":"Duka la Amina","is_active":true,"is_default":true,"phone_numbers":[{"id":"104512345678901","phone_number":"+255700000001","display":"+255 700 000 001","is_default":true}],"quality_rating":"GREEN","messaging_tier":"TIER_1K","templates_count":12,"catalogues_count":1,"last_synced_at":"2026-09-13T09:14:02+00:00"}]}}

phone_numbers[].id (Meta's phone_number_id) is what sender_id takes here and on the group endpoints, and what from takes on the catalogue sends and flow sessions — the number itself, as phone_number or display, is accepted in the same places. waba_id is what the template endpoints take. default_phone_number_id is the number a send without sender_id goes out from; when it is null there is no usable default and every send must name one. Never pass a local database channel ID. The SMS equivalent is GET /api/v3/sms/senders, described under SMS.

Text and the conversation window

{"recipient":"255712345678","message":"Hello Asha. Your collection is ready.","message_type":"text"}

Text/body is limited to 4,096 characters. For ordinary customer conversations, plan free-form replies within the supported customer-service window and use approved templates for initiating or reopening conversations. The generic REST send route passes the request to the provider; a provider window-policy refusal can appear as HTTP 201 with status:"failed". It is not always an HTTP validation error.

To reply to a particular message, include in_reply_to_gateway_id with its provider message ID. The application's msg_… UID is not a valid substitute. Link previews may be enabled by the driver when a text body contains an HTTP(S) URL.

Templates

{"recipient":"255712345678","message_type":"template","template":{"name":"collection_ready","language":"en","components":[{"type":"body","parameters":[{"type":"text","text":"Asha"},{"type":"text","text":"ORD-1042"}]}]}}

template.name identifies a template on the sending WhatsApp account. The name is at most 191 characters; language is at most 20 and defaults to en. Supply the language code of an approved translation and the exact component/parameter structure required by that template. Creating or approving a provider template is not part of this REST send request.

The controller accepts a components array and forwards it. Provider validation still decides whether the template exists, is approved and has the correct parameters. A top-level message with a template serves as local preview text; it does not replace the approved template body sent by the provider. A template cannot be combined with top-level media or an interactive payload.

Media links

{"recipient":"255712345678","message_type":"image","media_type":"image","media_url":"https://assets.example.com/orders/1042.jpg","message":"Your packed order"}

Use image, video, audio, document or sticker as appropriate. The corresponding media message type requires media_url, a URL up to 2,048 characters. Set media_type explicitly to avoid relying on type inference. The remote content must remain accessible when the provider fetches it, particularly for scheduled delivery.

This REST route takes a link; it does not accept a multipart upload. File size, MIME type and caption support are ultimately provider constraints. The link-send implementation forwards the message body as a caption, including its generated preview fallback when no body was supplied. Test audio and sticker behavior against your connection rather than assuming captions are ignored.

Interactive replies

{"recipient":"255712345678","message_type":"interactive","interactive":{"type":"button","body":{"text":"How would you like to receive your order?"},"action":{"buttons":[{"type":"reply","reply":{"id":"collect","title":"Collect"}},{"type":"reply","reply":{"id":"deliver","title":"Delivery"}}]}}}

Buttons need a body and usable reply IDs/titles. The driver normalizes a maximum of three buttons, with titles capped at 20 characters and IDs at 200. Interactive body text is capped at 1,024. Lists use action.button and sections of rows; row titles are capped at 24 and descriptions at 72. Supply concise valid payloads instead of relying on truncation.

The driver also recognizes cta_url, flow, product, product_list, catalog_message and location_request_message interactive types, passing their supported structure through for provider validation. Interactive and top-level media payloads cannot be combined.

Reactions

{"recipient":"255712345678","message_type":"reaction","reaction":{"message_id":"wamid.EXAMPLE_PROVIDER_ID","emoji":"👍"}}

The target is a provider message ID, up to 191 characters; emoji is required and limited to 16. in_reply_to_gateway_id can supply the target when reaction.message_id is omitted. Reactions cannot include text, media, templates or interactive content in the same request. Empty-emoji reaction removal is not exposed by this route.

All variants return message records. Preserve their local UID for tracking and provider ID for future context. For group conversations, use the separate group message endpoint.

WhatsApp lets a business start a conversation — a delivery notice, a payment reminder, an offer — only with a message template Meta has approved first. /api/v3/whatsapp/templates is the lifecycle of those templates over an API key: create one from your own system, it is submitted to Meta for review, and you read the verdict back three ways. Once approved, POST /api/v3/whatsapp/send sends it by template.name as described in WhatsApp messages.

Reads need a key whose issuer holds communications.templates.view; writes need communications.templates.manage. Every response is the v3 envelope: {"status":"success","data":…} or {"status":"error","message":…,"errors":…}.

One template is one name, one language, one account

A template is identified by three things: its name (order_shipped), its language (sw), and the WhatsApp Business Account (waba_id) it lives on. order_shipped in Swahili and order_shipped in English are two templates, each reviewed on its own. The same template on a second business account is a deployment, reviewed separately there too.

Start by reading the accounts, because waba_id is what everything else takes: GET /api/v3/whatsapp/accounts (described in WhatsApp messages) lists every connected business account with its waba_id and numbers. A workspace with one account may omit waba_id everywhere; with several, name one or the request answers 422 with the list.

Create, and let Meta answer in the same request

POST /api/v3/whatsapp/templates creates the template and submits it to Meta inside the request. The common case needs only the flat fields:

{"name":"order_shipped","language":"sw","category":"utility","body":"Habari {{1}}, oda yako {{2}} imetumwa leo.","header_text":"Oda {{1}}","footer":"Duka la Amina","buttons":[{"type":"url","text":"Fuatilia","url":"https://amina.co.tz/track/{{1}}","example":"ORD-1042"}],"variable_samples":{"1":"Asha","2":"ORD-1042"}}

Three rules Meta enforces, so this API enforces them before the call: name is lowercase letters, digits and underscores (it is not slugged for you — you get back the name you sent); every placeholder needs a sample value, which is what variable_samples is for; and a url button whose link ends in {{1}} needs an example too. category is utility for transactional notices, marketing for promotions, authentication for one-time codes; Meta may reclassify it during review.

The answer is 201 either way. What Meta said is in whatsapp_status:

{"status":"success","data":{"id":418,"name":"order_shipped","language":"sw","category":"utility","status":"active","whatsapp_status":"in_review","approved":false,"sendable":false,"rejection_reason":null,"whatsapp_business_account_id":"102290129340398","whatsapp_template_id":"1189456212345678","variables":["1","2"],"components":[{"type":"HEADER","format":"TEXT","text":"Oda {{1}}","example":{"header_text":["ORD-1042"]}},{"type":"BODY","text":"Habari {{1}}, oda yako {{2}} imetumwa leo.","example":{"body_text":[["Asha","ORD-1042"]]}},{"type":"FOOTER","text":"Duka la Amina"},{"type":"BUTTONS","buttons":[{"type":"URL","text":"Fuatilia","url":"https://amina.co.tz/track/{{1}}","example":["ORD-1042"]}]}],"deployments":[],"submission":{"submitted":true,"queued":false,"message":null}}}

in_review with a whatsapp_template_id means Meta has it; review takes minutes to a day. rejected means Meta would not take the payload, and rejection_reason is Meta's own words — a body that starts with a variable, a name already in use, a token without the permission — so fix it and POST /api/v3/whatsapp/templates/{id}/submit. pending with submission.queued: true means Meta could not be reached; the submission is queued and retried, and the status moves on its own.

Send "submit": false to save without submitting — a draft you will finish, or a batch you want to review before it goes to Meta.

Everything Meta supports: post components

The flat fields cover text headers, bodies, footers and the three plain button types. For a media header (Meta wants the sample handle its upload API issues, under example.header_handle), a carousel, a limited-time offer, copy-code, flow or catalogue buttons, or named parameters, describe the template in WhatsApp's own components[] shape — exactly what Meta's Business Management API takes, so a system that already speaks to Meta posts the same payload here:

{"name":"ofa_ijumaa","language":"sw","category":"marketing","waba_id":"102290129340398","components":[{"type":"HEADER","format":"IMAGE","example":{"header_handle":["4::aW1hZ2UvcG5n:ARZ…"]}},{"type":"BODY","text":"Ofa ya {{1}}: punguzo la {{2}} hadi {{3}}.","example":{"body_text":[["Ijumaa","20%","30 Sept"]]}},{"type":"FOOTER","text":"Jibu STOP kuacha"},{"type":"BUTTONS","buttons":[{"type":"QUICK_REPLY","text":"Nataka"},{"type":"COPY_CODE","example":"OFA20"}]}]}

components wins when both descriptions are sent. Whichever way a template was created, the read returns it as components — what was (or would be) submitted — so you can copy one to a new name, or edit and PATCH it back.

Reading the verdict

There are three ways, and they are not alternatives — use the one that fits the moment.

Read the row. GET /api/v3/whatsapp/templates/{id} and GET /api/v3/whatsapp/templates return the status this platform holds, which Meta's own status webhook and a fifteen-minute poll keep current. updated_since on the list makes an incremental mirror cheap: every status move changes the row.

Ask Meta now. POST /api/v3/whatsapp/templates/{id}/refresh reads the template from Meta in the request — status, rejection reason, quality score — and writes it on the row. This is for the moment you need the answer, such as right after a submission, and it needs only the view permission. data.refresh.found_on_whatsapp is false when Meta has no such template on the account.

Be told. Subscribe a webhook to template.status_changed and every move — by Meta's webhook, by the poll, by a refresh — arrives with the previous and new status, the business account, and the reason when rejected:

{"event":"template.status_changed","template_id":418,"name":"order_shipped","language":"sw","category":"utility","whatsapp_business_account_id":"102290129340398","whatsapp_template_id":"1189456212345678","previous_status":"in_review","whatsapp_status":"approved","rejection_reason":null,"timestamp":"2026-09-13T09:14:02+00:00"}

sendable on the template is the one bit that matters at send time: the row is active here and approved by Meta. paused and disabled are Meta stopping a template for quality; they come back the same way.

Pull what the account already has

Templates created in Meta Business Manager, or by another tool, are not here until you ask. POST /api/v3/whatsapp/templates/sync (optionally {"waba_id":…}) imports every approved template on the account as a local row — name, language, category and full components — refreshes the ones already here from Meta's copy, and re-reads the review status of everything already submitted:

{"status":"success","data":{"imported":3,"updated":9,"statuses_updated":1,"errors":[]}}

It runs against Meta's paginated list inside the request, so on an account with hundreds of templates allow a few seconds. Templates still in review on Meta's side that were not submitted through this platform appear once approved.

Changing, deploying, deleting

PATCH /api/v3/whatsapp/templates/{id} takes any subset of the create fields. A content change — body, header_text, footer, buttons, components or category — is re-submitted to Meta as an edit of the template it already holds, which puts it back in review; display_name and status changes never touch Meta. A template Meta is still reviewing cannot be edited on Meta's side: the change is saved here and goes out on the next …/submit once the review is over. name, language and waba_id cannot change, because Meta knows the template by them. A template described by components may hold parts the flat fields cannot express, so to change part of it send the edited components; sending a flat body re-describes the whole content.

POST /api/v3/whatsapp/templates/{id}/deployments with {"waba_ids":[…]} (from GET /api/v3/whatsapp/accounts) puts an authored template on other business accounts of the workspace. Each gets its own review, its own Meta id and its own row under deployments on the template; each outcome is announced by template.status_changed with that account's id.

DELETE /api/v3/whatsapp/templates/{id} removes this language of the template from the business account (Meta keeps other languages of the same name) and archives the row, so campaign history that pointed at it still reads. Add ?permanent=true to delete the row as well.

Templates are per business account, so a template only sends from that account's numbers: the sender_id on a send must be a phone number of the account the template is on.

A WhatsApp form is several questions a customer answers inside WhatsApp in one go — a booking, a sign-up, a quote request, a KYC upload. It opens as a sheet over the chat, the customer taps Send, and the answers come back as one message. Meta calls these WhatsApp Flows; /api/v3/whatsapp/forms is their whole life over an API key: build one from a definition, publish it to WhatsApp, send it, and read the answers.

Reads need a key whose issuer holds forms.view; building needs forms.create / forms.edit; going live needs forms.publish; sending needs forms.send; answers need forms.answers.view (and forms.answers.export to see questions marked sensitive). The Forms module must be switched on for the workspace. Every response is the v3 envelope.

A form is pages of questions

The definition is what the builder in the dashboard edits, as JSON:

{"pages":[{"title":"Taarifa zako","questions":[{"key":"jina_kamili","type":"short_text","label":"Jina kamili","required":true},{"key":"huduma","type":"dropdown","label":"Huduma","required":true,"options":[{"key":"dental","label":"Kliniki ya meno"},{"key":"lab","label":"Maabara"}]}]},{"title":"Muda","questions":[{"key":"tarehe","type":"date","label":"Tarehe","required":true},{"key":"kadi","type":"photo","label":"Kadi ya bima","max_files":2}]}],"submit_label":"Tuma"}

Each page is one WhatsApp screen; every page but the last has a continue button, the last one sends. A question's key is its saved-as name: it is the field in every answer, the flow variable a flow step fills, and the Daftari column the answer saves to. Once a version is published, a key keeps its type — add a new question rather than turning a text question into a number.

GET /api/v3/whatsapp/forms/question-types lists the thirteen types with the WhatsApp component each becomes, the Daftari column its answers fit, and WhatsApp's own limits. The ones that bite: a text, number, email, phone or dropdown question shows at most 20 characters of label (put the rest in help); choices hold at most 20 options (a dropdown 200); a form holds one photo or document question, on its last page, which can take up to 10 files. A number's min and max are checked when the answer arrives, because WhatsApp cannot check them while the form is open.

Create, then publish

POST /api/v3/whatsapp/forms with name, the definition (or build it up later with PATCH), and waba_id when the workspace has more than one WhatsApp business account. The answer is the form with issues: what would stop a publish, each with the page and question it is about and a sentence saying what to change.

Nothing goes to WhatsApp until POST /api/v3/whatsapp/forms/{form}/publish. That uploads the definition, reads back WhatsApp's own checks, and — when both are clean — publishes it as the next version. A 422 carries issues (ours or WhatsApp's); a 502 means WhatsApp refused or could not be reached.

WhatsApp never lets a published version change, so an edit is always the working copy, and publishing makes it the next version. Flow steps switch to the new version at once. The previous version keeps opening for customers who already have it (three days by default), then retires. GET /api/v3/whatsapp/forms/{form} shows every version with its WhatsApp status: PUBLISHED, or THROTTLED (WhatsApp is limiting it to 10 sends an hour) and BLOCKED when WhatsApp stops it on its own — the form's status is then attention, and the form.status_changed webhook says so.

Send

POST /api/v3/whatsapp/forms/{form}/send with to (a phone number with its country code) or conversation_id:

{"to":"255754118210","body":"Karibu Amina! Jaza fomu hii fupi.","cta":"Weka miadi","reference":"booking-8841"}

Inside the customer's 24-hour window the form goes out as a message with an Open form button. Outside it, WhatsApp only allows a template: name an approved template with an Open form button for this form in template_id, or the send answers 409. A template opens the version it was created with; after publishing a new version, create or edit the template for it (WhatsApp reviews that change).

The answer is 202 with the send's token — the same token the answer will carry — and the message id. Each send is billed as a WhatsApp message.

One form on several WhatsApp accounts

A form lives on one WhatsApp business account, its home: the account you name when you create it. WhatsApp will not send it from a number on another account; the send is refused with #131009 flow_id is invalid. When your numbers sit on more than one account, put the form on each of them.

Send accounts (a list of waba_ids) when you create the form, or call POST /api/v3/whatsapp/forms/{form}/deployments with waba_ids later. Each account gets its own copy of every version you publish; a live form is published on a newly added account straight away. A send goes out as the copy for the account the customer's number is on, so you never choose.

GET /api/v3/whatsapp/forms/{form} lists every account in accounts, with a role of home, added or available, WhatsApp's live_status there and an error when WhatsApp did not accept the form on that account. If one account refuses, the others still get the form. DELETE /api/v3/whatsapp/forms/{form}/deployments/{waba} takes it off an account; its copies there are retired, and a form a customer has already opened still answers.

A send to a number on an account the form is not on is refused with other_account before WhatsApp is called. In a flow, the form step then leaves by failed, where you can ask the question as text instead.

Answers

Answers arrive two ways. By webhook: subscribe to form.submitted (see Webhooks); the payload names the form, the version, what sent it (source: flow, template, api, mcp, ai, manual), the conversation, and answers keyed by question key — choices by their keys, several choices as a list, numbers as numbers, dates as YYYY-MM-DD, agreements as booleans, uploads as file names. By polling: GET /api/v3/whatsapp/forms/{form}/answers, newest first, paged with before (pass next_before from the last page) or narrowed with since.

When the form saves to a Daftari table, each answer is also a row (record.id). WhatsApp cannot bounce a bad answer back once the customer tapped Send, so an answer the table refuses — a number over its maximum, say — is kept on the form with record.status: "failed" and the reason in record.error; nothing is lost. Photos and documents are kept on the form and named in files.

Answers can hold personal data — ID numbers, health details. Questions marked sensitive are hidden from the summary WhatsApp shows the customer, and from API keys whose issuer may not export answers (lines shows ••••, answers is null).

Menus: a shop inside WhatsApp

A form can also be a shop's menu. POST /api/v3/whatsapp/forms with name and menu_shop_id instead of a definition (and menu_language, sw or en, for the menu's own buttons). The menu has three fixed screens — the dishes, one dish with its sizes and add-ons and a quantity, and the basket — and nothing to build: the dishes are the shop's published products (up to 20), and the sizes and add-ons are the options set on each product. Change a price or sell out of an add-on in the catalogue, and the next customer who opens the menu sees it.

While the customer moves through it, WhatsApp asks Momo what to show — an encrypted request to the account's own endpoint, which publishing sets up for you (a key is registered on each of the account's numbers). Every price is Momo's: the phone only ever sends which dish and which options. When the customer taps Send order, the answer is the order it became, built and priced once:

{"order_reference":"#1042","order_total":16500,"currency":"TZS","items":"1× Wali nyama (Kubwa, Kachumbari)\n2× Chai","note":"bila pilipili","order_id":1042}

The order lands on the orders desk with the conversation, and — unless a flow sent the menu and speaks for itself — the customer gets its summary in the chat. form.submitted carries the same answers; order.received fires as for any order. A menu's definition cannot be changed (PATCH with a definition answers 409); its name and settings can.

WhatsApp groups have their own lifecycle: create the group, wait for provider confirmation, distribute invitations, manage join requests, then send into the active conversation. The group API uses numeric local group IDs in its URLs; a provider group ID is a separate opaque value and may be absent during creation.

Eligibility and permissions

The connected business number must be eligible for the provider's Groups API. The implementation recognizes provider error 131215 as an eligibility refusal and describes the requirement as an Official Business Account. Use the actual connection's eligibility result instead of assuming all WhatsApp numbers can create groups.

Read operations require communications.groups.view. Changes require communications.groups.manage. Sending a group message also requires communications.send. These permissions are evaluated against the current user who issued the API key. An old key with no attributable issuer is refused.

Create, then inspect

{"sender_id":"123456789012345","subject":"Order coordination","description":"Collection arrangements for this order.","join_approval_mode":"approval_required","invite_template":"group_invitation","invitees":["255712345678"]}

POST this to /api/v3/whatsapp/groups. Subject is required, maximum 128 characters; description maximum 2,048. join_approval_mode is auto_approve or approval_required, defaulting to auto approval. invite_template names a stored WhatsApp template. The provider limit represented by this implementation is eight participants including the business, so at most seven initial invitees may be supplied.

A 201 response creates the local group; it does not prove that the group is already active. Read GET /api/v3/whatsapp/groups/{id} until provider confirmation arrives or a failure is recorded. States are creating, active, suspended, deleted and failed.

List with GET /api/v3/whatsapp/groups. By default deleted groups are excluded. status=all includes all states; a specific status filters them. The list's sender_id filter matches the stored provider phone-number ID. Pagination follows the ordinary 20-row default and 100-row cap.

Invitations and membership

Keep invitation sending distinct from joining: recipients decide whether to join, and approval may be required. Inspect per-recipient successes and failures in invitation and membership results instead of treating a batch response as universal success.

Sending and pinning

POST {id}/messages with message/body, media_url plus media_type, or a stored template name with language/components. Text is limited to 4,096 characters. If no participant has written in the local 24-hour window, a free-form send is refused with 422 and an approved template is required. Group sends return the application's group-message presentation; consult this endpoint's response schema rather than assuming it matches /whatsapp/send exactly.

POST {id}/pin accepts message_uid, required Boolean pin, and optional expiration_days from 1 to 30. Here message_uid is the local public message UID. It is not the provider ID used for reactions.

Subscribe to group lifecycle callbacks where configured, then reconcile important operations by reading the group. Webhook delivery is best effort, and local group state may lag the initial provider request.

Use POST /api/v3/sms/campaign to dispatch an SMS audience stored in contact groups. This endpoint creates one-time SMS campaigns. Recurrence, campaign editing and scheduled-message cancellation are not exposed as fields or operations in this REST family.

Create a campaign

{"contact_list_id":"12,19","sender_id":"MyBrand","name":"Collection reminders","message":"Hello {{name}}, order {{cf:order_ref}} is ready.","schedule_time":"2030-10-12T09:00:00+03:00"}

Commas, semicolons and whitespace separate group identifiers. Duplicate identifiers resolving to the same group are collapsed. One campaign is created for each group found, and the response is data.campaigns, even for one group. If no group resolves, the endpoint returns 404. If some resolve and others do not, it creates the campaigns for those found. Verify the returned group references against your intended audience.

Sending identity resolution happens before campaigns are created. The same SMS ownership and default-route rules apply as for individual sends. An omitted name becomes an API campaign name derived from the contact group.

Scheduling

Use an explicit ISO8601 offset, such as 2030-10-12T09:00:00+03:00, or UTC ending in Z. Replace the illustrative future date with your intended delivery date. A malformed schedule returns 422. A past date does not establish a future delay; it becomes eligible to run immediately.

A scheduled campaign starts as scheduled; an immediate campaign starts as draft and is dispatched for processing. Queue availability and provider throughput determine when individual sends happen, so the schedule is a due time rather than a guaranteed arrival time for every recipient.

For an explicit individual recipient, /sms/send and /whatsapp/send also accept schedule_time. Those requests queue future messages and return their UIDs. There is no customer REST operation here to cancel or reschedule the saved message later.

Audience and personalization

The campaign reads its group's contacts when it executes. If you edit that group after scheduling, the eventual audience may differ. The current dispatch loop skips missing phone numbers and numbers matching the account/channel blacklist. It does not filter on the contact's is_subscribed flag; your integration must prepare the intended subscribed audience rather than assuming that flag suppresses dispatch.

Template variables are {{name}}, {{phone}}, {{phone_number}}, {{country_code}} and {{cf:your_custom_key}}. Unknown or missing variables become empty text. Preview representative contacts before scheduling, especially when custom values make messages longer or change encoding. An individual send does not perform contact-group template expansion.

Track progress correctly

Use GET /api/v3/campaign/{uid}/view; numeric campaign ID is also accepted. The response includes group reference, schedule, message, sender, status, total recipients, sent_count and failed_count.

completed means the campaign finished dispatching its recipient jobs. Delivery can still be in progress, and counts can continue to change. An unaffordable prepaid campaign can pause; inspect account balance and campaign state before assuming the scheduler failed. Campaigns without a usable route can be cancelled.

Poll campaign state and message results for reconciliation. Although the dashboard contains campaign event labels, this campaign path does not currently emit the corresponding completion/failure callbacks. Repeating campaign creation is not idempotent: record the returned campaign IDs against your own campaign request.

The contact directory is two things: groups, and the people in them. Every contact belongs to exactly one group, and a group also declares the extra fields its contacts may carry. Reading needs the key issuer's contacts.view; writing needs contacts.create / contacts.edit; deleting needs contacts.delete; the bulk import needs contacts.import.

Start with the groups

GET /api/v3/contact-groups is where the {group_id} every contact path takes comes from:

{"status":"success","data":{"items":[{"id":42,"uid":"9f3a1c20-5d6e-4a71-9c3b-2f1a0e7b8c44","name":"Wateja wa Dar","status":"active","contacts_count":1180,"subscribed_count":1094,"custom_fields":[{"key":"order_ref","label":"Order reference","type":"text"}],"created_at":"2026-09-14T09:14:02+00:00","updated_at":"2026-09-14T09:14:02+00:00"}],"pagination":{"current_page":1,"per_page":25,"last_page":1,"total":1,"has_more_pages":false}}}

subscribed_count is the number a campaign would actually reach; contacts_count includes the people who have opted out. Either the numeric id or the uid works anywhere a group is named — store the uid, it is stable.

POST /api/v3/contact-groups creates one. custom_fields declares the extra fields its contacts may carry: a contact can still be given an undeclared key, but a declared one is what the dashboard shows a column for and what a campaign addresses as {{cf:order_ref}}. Keys are letters, digits, _, . and -; duplicates are refused; label defaults to the key and type to text.

{"name":"Wateja wa Dar","custom_fields":[{"key":"order_ref","label":"Order reference","type":"text"},{"key":"branch","type":"select"}]}

PATCH /api/v3/contact-groups/{group} renames it, retires it with "status":"inactive", or changes the declaration. custom_fields replaces the declaration rather than merging into it — a schema is not a meaningful thing to half-send — and removing a field does not touch values already stored on contacts; they are simply no longer declared.

DELETE /api/v3/contact-groups/{group} deletes the group and every contact in it. A group that still holds people answers 409 with the count; repeat with ?force=true if you mean it. There is no undo and the contacts do not move anywhere.

Two paths to the same contacts

Both columns reach the same records with the same behaviour. The original paths are not deprecated; the REST ones exist because that is the shape the rest of this API uses and what a generated client expects. A contact is named by its uid or its numeric id, and only within its own group.

Creating a contact

{"PHONE":"0712345678","country_code":"255","name":"Asha Mwinyi","is_subscribed":true,"order_ref":"ORD-1042","branch":"Mlimani"}

PHONE is required (phone_number is an alias; PHONE wins if both are sent). Send country_code explicitly when you want the split stored — a +255… prefix alone is not inferred. With the example above the stored country code is 255 and the national number 712345678; full_phone_number comes back as 255712345678.

The name comes from name, or NAME, or FIRST_NAME + LAST_NAME. A contact created with no name at all is named after their number. is_subscribed defaults to true.

Custom fields go at the top level, as order_ref and branch do above. Every field that is not one of the reserved names — PHONE, phone_number, country_code, name, NAME, FIRST_NAME, LAST_NAME, is_subscribed, _token — is stored as a custom field. Wrapping them in a custom_field_values object would store that wrapper as a key called custom_field_values.

PATCH changes what you send, and nothing else

{"is_subscribed":false}

That call unsubscribes the person and touches nothing else. Custom fields merge into what is already stored; send a key as null to remove it. The name, the number and the subscription each keep their current value when the payload is silent about them, and PHONE is required only when the number itself is changing.

This changed on 14 September 2026. Until then a PATCH replaced the entire custom-field map and renamed the contact after their own phone number whenever name was absent — so the call above would have wiped every custom field and renamed Asha to 255712345678. If you followed the old advice and read-merge-send the whole record, nothing changes for you. If you built around the replacement behaviour, send null for the keys you want gone.

Importing in bulk

POST /api/v3/contact-groups/{group}/contacts/batch takes up to 500 rows, each shaped exactly like a single create:

{"contacts":[{"PHONE":"0712345678","country_code":"255","name":"Asha Mwinyi","order_ref":"ORD-1042"},{"PHONE":"0754000111","country_code":"255","name":"Juma Ally"}],"skip_existing":false}

A number already in the group is updated — its custom fields merge, and a row with no name does not rename anybody. A new number is created. skip_existing: true leaves the ones already there completely untouched.

Rows are judged one at a time. A row that fails validation lands in problems with its index and the others still apply, so the answer is 207 when anything was rejected and 200 when nothing was:

{"status":"success","data":{"group_id":42,"received":3,"created":1,"updated":1,"skipped":0,"rejected":1,"results":[{"index":0,"uid":"ctc_7f2ab1c93de04a6b8f10","outcome":"updated"}],"problems":[{"index":2,"errors":{"PHONE":["The PHONE field is required."]}}]}}

results names what happened to each row that landed, so you know what you changed without diffing anything afterwards.

Finding people

Within a group, GET /contact-groups/{group}/contacts?search=… matches the name, the national number, and the full number with punctuation stripped — a number pasted as +255 712 345 678 finds them. subscribed=true|false narrows to who still accepts messages.

Across groups, GET /api/v3/contacts?q=… answers "who is this number?" when you do not know which group holds them; group_id narrows it back to one. Both are paginated with limit and page, default 20, maximum 100.

Keys issued before 14 September 2026

Reading and writing contacts now requires the permissions above, held by the person whose account issued the key. One exception is deliberate: a key created before 7 September 2026 is not linked to an issuer at all — the platform did not record one — and those keys keep the five original /contacts/{group_id}/… paths they were issued under, because integrations were written against a contract that had no per-key permissions. They are refused on everything added since: the groups, the REST paths, the bulk import and the cross-group search.

Rotate such a key from Settings → API credentials to bring it under the permission model. Check which permissions its issuer holds first, or the rotated key will lose access the old one had.

Using them

Campaigns address these records as {{name}} and {{cf:order_ref}} — see campaigns. The subscription flag records your intent; it is not applied automatically by the campaign dispatch loop, so maintain your audience and your blacklist deliberately. Repeated POSTs of the same number create duplicate rows: use the batch endpoint, which matches on the number, when you mean "make sure these people are in this group".

A lead is one person's sales record, at any stage — new, contacted, qualified, opportunity, won, lost or unqualified — attached to the calls, chats, comments and form answers it came through. The AI agent writes leads while it talks to customers and after calls, staff work them in Leads in the dashboard, and this API is the same door for your CRM or ERP. Reading needs the key issuer's leads.view; writing needs leads.edit; assigning needs leads.assign; deleting needs leads.delete; managing labels needs leads.settings.

One lead per person

POST /api/v3/leads is an upsert, never a blind create. The person is found through the workspace's identity layer: a phone number in any common form (0712 345 678, 712345678, +255 712 345 678), a WhatsApp id and an email all resolve to the same person, whichever channel they used first. If they already have a lead it is updated and you get 200; if not, one is created and you get 201. There is no way to make a second lead for the same person, so you can push every enquiry your system sees without checking first.

{"name":"Grace Mushi","phone":"0754 221 908","company":"Mushi Hotels","interest":"IVR + 3 numbers","estimated_value":6000000,"labels":["hot"],"note":"Met at the Mlimani City fair."}

{"status":"success","data":{"lead":{"id":"0199a2c4-6f1e-7c1a-9d2b-3c5e8f7a1b20","name":"Grace Mushi","title":"Grace Mushi","company":"Mushi Hotels","phone":"+255754221908","email":null,"stage":"new","stage_label":"New","closed":false,"archived":false,"labels":[{"id":1,"name":"hot","color":"#e11d48"}],"interest":"IVR + 3 numbers","estimated_value":6000000,"currency":"TZS","score":null,"source_channel":"api","assigned_to":null,"next_action":null,"next_action_at":null,"overdue":false,"created_by":{"kind":"api","id":7},"last_activity_at":"2026-09-26T09:14:02+03:00","created_at":"2026-09-26T09:14:02+03:00","sources":[]},"created":true,"was_closed":false,"ignored":[],"refused":[],"possible_duplicate_of":null}}

(The lead in the response is the full record; it is shortened here.)

Things worth knowing about the upsert:

• It never blanks a field. Empty values are ignored, so a sync that sends "company": "" leaves the company alone. To clear a field, PATCH it with null.
• A lead that is already won, lost or unqualified keeps its stage unless you send one; was_closed tells you it was matched.
• Money is in the currency's main unit. estimated_value: 4500000 is TSh 4.5M. currency defaults to the workspace's own.
• Identify by a record. Send conversation_id (an inbox conversation) or call_id and the customer is identified by that record — their WhatsApp id, their Instagram id, the number that called — and the record is attached to the lead. Both must belong to your workspace.
• Stages close. won, lost and unqualified close a lead; lost and unqualified need a reason.
• Labels by name. A name that does not exist yet is created only if the key's issuer holds leads.settings; otherwise it comes back in refused and the rest of the call still applies.
• Retries are safe. Send an Idempotency-Key header and a retried call within 24 hours replays the first answer with X-Idempotent-Replay: 1.

A refused call returns the usual error envelope plus a reason code you can branch on — invalid, reason_required, nothing_to_identify, won_locked, assignee_unknown:

{"status":"error","message":"Say why the lead is lost: send a short reason.","reason":"reason_required","errors":{"reason":["A reason is required."]}}

Who a key can see

A key inherits its issuer's permissions and visibility. An issuer with leads.data.all (owners and managers have it) sees every lead. Anyone else sees the leads assigned to them, the unassigned pool, and the leads they added — so a key issued by a sales agent reads exactly what that agent reads in the dashboard. A lead outside that view answers 404, and an upsert that matches one answers 409 rather than revealing it. Use a key issued by someone who sees every lead for a full CRM sync.

The module can be switched off for a workspace; every Leads endpoint then answers 403 Leads are switched off for this workspace.

Reading and syncing

GET /api/v3/leads lists leads, most recently active first, open ones only unless you pass status (closed, archived or all). Filters combine: stage, label (names or ids), channel, assigned_to (me, none or an id), created_by (ai, people, api…), q, from/to with date_field, score_min/score_max. For an incremental sync, poll with status=all&updated_since= the time of your last sync — or better, subscribe to the events below.

GET /api/v3/leads?status=all&updated_since=2026-09-26T00:00:00%2B03:00&limit=100

GET /api/v3/leads/{lead} returns the whole record: the person's identities (every phone, WhatsApp, email and social id the workspace knows them by), the sources the lead is attached to — origin first, calls with their duration and whether a recording exists — the custom_fields, and a possible_duplicate when another lead looks like the same person.

GET /api/v3/leads/{lead}/activities is the timeline, newest first: every field change, stage move, label, note, assignment and attached record, with who did it — a person, the AI agent, an API key or a flow. Page backwards with before= the next_before of the previous page.

Changing a lead

A new phone number or email sent with PATCH is filed against the person, so the next time they call or write from it they are recognised. The stage has its own endpoint because moving to lost or unqualified needs a reason.

GET /api/v3/lead-labels lists the workspace's labels with how many leads carry each; POST, PATCH and DELETE manage them with leads.settings. A label's description is what the AI agent reads to decide when to use it, and ai_assignable: false keeps a label for people only. GET /api/v3/lead-fields lists the custom fields a lead's custom_fields may carry — keys, types and, for select fields, the option keys to send.

For AI assistants: the leads MCP tools

The same leads are available to Claude, ChatGPT and other MCP clients through the leads server of the MCP connection, with the connecting person's permissions and visibility:

There is deliberately no tool to delete or merge leads. The tools check what they are told: a stage change to lost needs a reason, and the customer-facing AI agent can only save a phone number or email the customer actually gave.

Lead events

Subscribe a webhook to any of these to keep another system in step:

Every lead event carries the whole lead, so you can upsert it without calling back:

{"event":"lead.stage_changed","event_id":"evt_01J8Z6Q4M3T8W5K2N7XQ4R9ABC","timestamp":"2026-09-25T14:03:11+03:00","lead":{"id":"0199a2c4-6f1e-7c1a-9d2b-3c5e8f7a1b20","name":"Amina Juma","phone":"+255712345678","email":null,"company":"Amina Shop","location":"Mbezi, Dar es Salaam","stage":"qualified","closed_at":null,"archived_at":null,"lost_reason":null,"source_channel":"whatsapp","source_detail":"Ad: October solar promo","interest":"Solar kit 5 kW","estimated_value":4500000,"currency":"TZS","score":72,"score_reason":"Budget stated, wants install this month","summary":"Shop owner in Mbezi who needs backup power for two fridges. Budget about TSh 4.5M.","next_action":"Send quote","next_action_at":"2026-09-26T10:00:00+03:00","labels":["hot","follow-up"],"assigned_to":{"id":311,"name":"Baraka M."},"custom_fields":{"budget_band":"mid"},"created_by":{"kind":"ai","id":14},"created_at":"2026-09-24T09:12:40+03:00","updated_at":"2026-09-25T14:03:11+03:00","url":"https://business.momo.tz/app/leads/0199a2c4-6f1e-7c1a-9d2b-3c5e8f7a1b20"},"changes":{"stage":{"from":"contacted","to":"qualified"}},"reason":null,"actor":{"kind":"ai","id":14,"label":"Mauzo AI"},"source":{"kind":"conversation","id":"88213","channel":"whatsapp"}}

• changes is {field: {from, to}} on lead.updated, lead.stage_changed and lead.assigned.
• actor says who made the change; source says which call or chat it happened in.
• Dedupe on event_id (also sent as X-Event-Id): it is the same on every retry, every replay and every endpoint.
• Filter at the source. A receiver's filters can narrow lead events to certain stages, labels or channels — {"lead":{"stages":["qualified","opportunity","won"],"labels":["hot"]}} — so a CRM that only wants qualified leads never sees the rest.
• Authenticate to your side. headers adds up to five headers of your own to every delivery, e.g. {"Authorization":"Bearer …"}; the values are stored encrypted.
• Try it. POST /api/v3/webhooks/{webhook}/test with {"event":"lead.stage_changed"} sends the sample above, marked "test": true, and shows you what your receiver answered.

Verify each delivery with X-Signature-V2 over the raw body before parsing it, and refuse timestamps older than five minutes:

$expected = 'sha256='.hash_hmac('sha256', $ts.'.'.$deliveryId.'.'.$rawBody, $secret);
$ok = hash_equals($expected, $header) && abs(time() - (int) $ts) < 300;

const expected = 'sha256=' + crypto.createHmac('sha256', secret)
  .update(`${ts}.${deliveryId}.${rawBody}`).digest('hex');

$ts is X-Timestamp, $deliveryId is X-Delivery-Id and $header is X-Signature-V2. A 2xx is success. A 5xx, 408, 425, 429 or timeout is retried at 1 minute, 5, 30, 2 hours and 6 hours; any other 4xx is not retried. Fifty failures in a row pause the endpoint and tell the people who manage webhooks; replay a failed delivery to resume it. The webhooks chapter covers verification in full.

API ya biashara ndiyo njia ambayo duka la mtandaoni, mfumo wa POS au ofisi inayotumia majedwali (spreadsheets) huweka bidhaa na oda zake sawa na Momo Business — na kupitia Momo Business, sawa na WhatsApp na kila jukwaa lingine ambalo duka limechapishwa.

Katalogi (duka) huhifadhi bidhaa, chapa (brands), makundi na oda. Inakamilika na kufanya kazi bila jukwaa lolote: msaidizi wa AI, menyu za simu na programu ya wafanyakazi wote huisoma. Chaneli ni uwepo wa duka hilo kwenye jukwaa moja. Listing ni bidhaa moja kama jukwaa moja linavyoiona. Mgawanyo huu ndio unaowezesha bidhaa ile ile kuwa hai kwenye storefront yako na kuzuiwa (blocked) kwenye WhatsApp — na kila upande kusema hivyo kwa maneno yake, badala ya kukuacha ukibahatisha.

Tengeneza duka, kisha lijaze

POST /api/v3/catalogues hutengeneza duka kutoka kwenye mfumo wako, ili integration imalize usanidi wake bila mtu kufungua dashibodi. Kuunganisha duka hilo na WhatsApp hubaki kuwa hatua ya dashibodi — inahitaji idhini ambayo bearer token haiwezi kutoa kwa niaba ya mtu. Soma channels[] kwenye jibu lolote la katalogi kuona imechapishwa wapi.

{"name":"Mango Electronics","default_currency":"TZS","sku_prefix":"MNG","stock_policy":"external"}

stock_policy huamua nani anamiliki hesabu ya stoku. external maana yake mfumo wako unaimiliki: sisi tunaakisi unachotuma na kukuambia kilichouzwa, na hatuamui idadi mpya kwa niaba yako. momo maana yake sisi tunashika hesabu. Duka lililotengenezwa kupitia API hili huanza na external; lililotengenezwa kwenye dashibodi au kutoka kwenye spreadsheet huanza na momo. PATCH /api/v3/catalogues/{catalogue} hubadilisha chochote baadaye. sku_prefix hukubaliwa wakati wa kutengeneza tu — imeshapachikwa kwenye kila msimbo ambao duka limeshatoa.

Utambulisho wa bidhaa na pesa

Huhitaji kamwe kubuni msimbo. Usitume sku na duka litatoa mmoja — MNG-00042 — unaosomeka, unaopangika na wa kipekee kwa kila duka. Bidhaa ikishakuwa hai kwenye jukwaa lolote, msimbo wake hugandishwa: majukwaa huuchukulia kama utambulisho wa bidhaa, na kuubadilisha kungeachia bidhaa ya mbali bila mwenyewe na kutengeneza nakala kimya kimya.

name na price pekee ndizo zinazohitajika. Picha, bei isiyo sifuri na mengineyo ni mahitaji ya majukwaa binafsi, na bidhaa isiyo nayo huhifadhiwa na kuripotiwa kama blocked kwenye jukwaa hilo badala ya kukataliwa kabisa. Duka linalouza kwenye storefront yake tu halipaswi kulazimika kutimiza sheria za Meta.

{"sku":"MNG-45W","name":"Charger Mango 45W","description":"USB-C PD, kebo ya mita 1","price":4500000,"currency":"TZS","sale_price":3900000,"image_url":"https://cdn.example.com/mng45.jpg","inventory":12,"availability":"in stock","brand":"Mango","category":"Chargers"}

Ukiacha currency, ya duka hutumika. Ukiacha availability, hutokana na inventory: hesabu ya sifuri maana yake out of stock isipokuwa duka linaruhusu backorder. Ukituma availability moja kwa moja, unachotuma ndicho kinashinda. Maandishi ya chapa na kundi huwa rekodi mara ya kwanza yanapotumika, hivyo import moja hujaza orodha za kuchagua kwa kila kitu kinachoandikwa baadaye.

Usawazishaji wa wingi (bulk sync)

POST /api/v3/catalogues/{catalogue}/products/batch ndiyo endpoint ambayo integration ya duka huishi juu yake. Hadi bidhaa 5,000, kila sehemu iliyoandikwa kwenye nyaraka huhifadhiwa — si zile za utambulisho tu.

Hujibu 202, si 200. Safu hukubaliwa, na kuzitumia na kuzisukuma kwenye jukwaa hufanyika nyuma ya pazia, kwa sababu hilo huchukua muda mrefu kuliko ombi la HTTP linavyopaswa. Jibu hubeba kitambulisho cha sync.

POST /api/v3/catalogues/42/products/batch
Idempotency-Key: nightly-2026-09-11

{"mode":"upsert","products":[ ... ]}

Tuma Idempotency-Key kwenye chochote kilichoratibiwa. Kurudia ufunguo hurudisha mkimbio ulioshamiliki ukiwa na "replayed": true na hakuna kinachoingizwa tena, hivyo cron iliyokwisha muda ni salama kurudiwa.

mode ni upsert kwa chaguo-msingi: bidhaa ambazo payload yako haizitaji huachwa kama zilivyo. mode: "replace" husema payload hii ndiyo katalogi na huondoa kila kitu kisichomo — sahihi kwa export kamili ya usiku, haribifu kwa ile ya sehemu.

Safu hulinganishwa kwa sku unapotuma moja, na kwa jina la bidhaa usipotuma, hivyo laha isiyo na safu ya msimbo husasisha safu zake unapoingiza tena badala ya kuzinakili.

Safu moja mbaya haikatai faili. Safu isiyoweza kuhifadhiwa huwa safu moja iliyokataliwa kwenye ripoti; nyingine 4,999 hutua.

Soma ripoti

GET /api/v3/catalogues/{catalogue}/syncs/{sync} ni nusu nyingine ya mkataba. Iulize hadi status iwe completed au failed.

{"status":"completed","received":2000,"created":12,"updated":1982,"rejected":6,"retired":0,
 "platforms":{"whatsapp":{"synced":1960,"blocked":34}},
 "problems":[{"sku":"MNG-CABLE","stage":"ingest","reason":"Price must be a whole number of minor units, 0 or more."},
             {"sku":"MNG-KNIFE","stage":"whatsapp","reason":"WhatsApp needs a product image it can fetch."}]}

stage ndiyo sehemu ya kusoma kwanza. ingest maana yake safu haikuhifadhiwa kabisa — irekebishe na uitume tena. Thamani nyingine yoyote ni jina la jukwaa: bidhaa imehifadhiwa na iko sawa upande wetu, na jukwaa hilo halitaionyesha hadi tatizo lililotajwa lirekebishwe. Zote mbili huonekana kama "bidhaa yangu haiko hai", na zinahitaji hatua tofauti. Matatizo 200 ya kwanza tu huhifadhiwa; problems_truncated husema yalipokuwa mengi zaidi.

GET /api/v3/catalogues/{catalogue}/syncs huorodhesha mikimbio ya nyuma, mpya kwanza, ikiwa ni pamoja na feed pulls na spreadsheet imports.

Hakuna developer? Tuelekeze kwenye feed

Kila jukwaa la duka — Shopify, WooCommerce, Magento, PrestaShop, Wix — linaweza kuchapisha Google Shopping feed au Meta product feed kwa mpangilio mmoja, bila code. POST /api/v3/catalogues/{catalogue}/feeds huelekeza duka kwenye URL hiyo na sisi tunaivuta kwa ratiba.

{"url":"https://shop.example.com/google-feed.xml","schedule":"daily"}

Uvutaji wa kwanza hufanyika mara moja. Majina ya safu hubashiriwa kutoka kwenye vichwa vya feed yenyewe (g:id, g:price, g:availability na mengineyo yote yanajulikana), huhifadhiwa kwenye feed, na yanaweza kurekebishwa kwa mapping. Kila uvutaji ni sync kama nyingine yoyote — soma last_sync_id kwenye GET /catalogues/{catalogue}/syncs/{sync} kupata ripoti ile ile ambayo batch endpoint hutoa. mode huanza na replace kwa sababu feed kwa kawaida ni katalogi nzima; weka upsert kama yako ni ya sehemu.

Feed ni ya upande mmoja, hivyo weka duka chini ya stock_policy: external: duka linamiliki hesabu, feed inaitamka, na oda za hapa huripotiwa kurudi kupitia webhooks ili duka lizishughulikie. Feeds za CSV na JSON hufanya kazi vivyo hivyo. Baada ya uvutaji kumi ulioshindikana mfululizo feed huzimwa na akaunti huambiwa; irekebishe na uiwashe tena. POST …/feeds/{feed}/run huvuta sasa hivi, bila kujali ratiba.

Kubadilisha bidhaa moja

PUT /api/v3/catalogues/{catalogue}/products/by-sku/{sku} huita bidhaa kwa msimbo ambao mfumo wako tayari unauijua, hivyo sync haihitaji kamwe kushika ramani ya namba zetu. Hutengeneza bidhaa kama haipo, hivyo duka lililoongeza bidhaa sasa hivi halihitaji kujua kama tumeshaiona.

Sehemu unazotuma tu ndizo zinazoguswa. {"inventory": 0} ni sasisho la stoku na si kingine — haifuti maelezo.

GET na DELETE hufanya kazi vivyo hivyo kwenye njia ile ile. Kufuta huondoa bidhaa kwenye kila jukwaa iliko, kisha kwenye rafu. Njia za namba (/products/{product}) hufanya vivyo hivyo na hazijabadilika.

Usomaji wa bidhaa hubeba listings[]: safu moja kwa kila jukwaa ikiwa na state yake (pending, syncing, synced, failed, blocked, drifted) na problem pale ilipo. sync_status kwenye bidhaa ni muhtasari wa safu hizo — bidhaa kwenye duka lisilo na majukwaa ni synced, kwa sababu kwa kweli hakuna cha kusawazisha.

Majukwaa, na nani yuko sahihi

Duka huchapishwa kwenye majukwaa kupitia chaneli; bidhaa ni listing moja kwa kila jukwaa. Bidhaa ile ile inaweza kuwa synced kwenye storefront yako, blocked kwenye WhatsApp (haina picha), na pending kwenye Instagram kwa wakati mmoja, na kila safu husema hivyo.

Drift. Mfanyabiashara anayebadilisha bei moja kwa moja kwenye Meta Commerce Manager amefanya uamuzi, na push inayofuata kutoka kwenye mfumo wako au kutoka momo ilikuwa ikiuandika juu kimya kimya. Kila saa, nakala ya kila jukwaa hulinganishwa na yetu. Tofauti huweka listing kama drifted, hurekodi drift sehemu kwa sehemu, hutuma product.drifted kwenye webhooks zako, kisha hutumia sheria ya duka:

Stoku kamwe si sehemu ya ulinganisho — ni leja, na majukwaa huona neno la upatikanaji linalotokana nayo tu. image_url pia hailinganishwi, kwa sababu Meta huhifadhi upya kila picha inayoichukua.

Kutuma bidhaa. POST /api/v3/catalogues/send-product huchukua platform. Kwenye WhatsApp ni kadi ya bidhaa ya Meta, kama awali. Kwenye jukwaa lingine lolote jibu la kweli ni kiungo (link): jibu hubeba anwani ya bidhaa huko na endpoint ya kuitumia, hivyo kuna njia moja ya kutuma kwa kila jukwaa badala ya moja kwa kila jukwaa. Bidhaa isiyochapishwa kwenye jukwaa hilo hukataliwa kwa 422 inayosema hivyo. send-product-list na send-catalogue ni aina za WhatsApp pekee zisizo na mfano kwingineko, na hubaki WhatsApp tu.

Stoku, pande zote mbili

Stoku ni leja, na kila duka hutamka nani anaimiliki.

Chini ya stock_policy: external — chaguo-msingi kwa duka lililotengenezwa kupitia API hili — mfumo wako unamiliki hesabu. Sukuma viwango kwa endpoint iliyo hapa chini, na sisi tunaviakisi na kukuambia kilichouzwa. Uuzaji uliothibitishwa hautoi kamwe upande wetu, kwa sababu mfumo wako unakaribia kutamka kiwango kipya na pande mbili hazipaswi zote kutoa. Bado tunashikilia vitengo kwa oda inayosubiri kati ya sync zako, ili kitengo kile kile cha mwisho kisiahidiwe kamwe kwa wateja wawili.

Chini ya momo — chaguo-msingi kwa duka lililotengenezwa kwenye dashibodi au kutoka kwenye spreadsheet — sisi tunashika hesabu. Oda inayosubiri huhifadhi vitengo; kuithibitisha huvitoa; kuifuta huvirudisha; wafanyakazi hurekebisha kwa mkono wakiwa na sababu.

Kwa njia yoyote, bidhaa isiyo na inventory kabisa haifuatiliwi. Hakuna aliyeandika hesabu, hivyo hakuna kinachozuiliwa na hakuna kinachokataliwa kamwe. Bidhaa nyingi huanza hivi na si kosa.

Sukuma viwango

POST /api/v3/catalogues/{catalogue}/inventory ndicho cha kuita wakati kitu kinapouzwa kwenye tovuti yako. Hadi safu 5,000, kwa misimbo yako, hesabu tu.

{"levels":[{"sku":"MNG-45W","inventory":0},{"sku":"MNG-20W","inventory":37}]}

Viwango ni kamili (absolute), kamwe si tofauti: mfumo wako unatamka ulicho nacho, na tofauti ingepotea mara ya kwanza ujumbe ungefikishwa mara mbili.

Upatikanaji hufuata hesabu. Isipokuwa duka linaruhusu backorder, 0 huweka bidhaa kama out of stock na stoku inaporudi huiinua kuwa in stock. Jibu hutaja kila bidhaa ambapo hilo lilitokea chini ya derived, na push moja huenda kwenye kila jukwaa duka liliko — hivyo kuisha kwa stoku hufika WhatsApp bila wewe kutuma bidhaa sita nzima moja moja. Bidhaa ya discontinued au preorder kamwe hairudishwi sokoni kimya kimya na mzigo unaofika.

Misimbo tusiyo nayo hurudi kwenye unknown_skus badala ya kupuuzwa. Kiwango ambacho tayari kiko kwenye thamani hiyo huhesabiwa unchanged na hakuna kinachochapishwa upya kwa ajili yake.

Soma viwango na historia

GET /api/v3/catalogues/{catalogue}/inventory hurudisha, kwa kila bidhaa, inventory (kwenye rafu), reserved (inayoshikiliwa na oda zinazosubiri) na available — tofauti, na namba inayoamua kama mteja anaweza kununua. Chuja kwa sku[] au tracked_only=true.

GET /api/v3/catalogues/{catalogue}/products/by-sku/{sku}/movements ni rekodi ya ukaguzi: kila tukio lililobadilisha hesabu, mpya kwanza, likiwa na kind (reserve, release, commit, adjust, sync), idadi yenye alama, thamani zilizokuwa baadaye, na nani au nini kilichosababisha.

Oda hufanya nini kwenye stoku

Oda inapotengenezwa — kutoka kwenye cart ya WhatsApp, storefront yako, flow, au menyu za simu — vitengo huhifadhiwa kwa kila mstari tunaoweza kulinganisha. Kama hakukuwa na vya kutosha kushikilia, mstari huwekewa alama stock_short, oda huwekewa alama needs_attention, na oda bado hurekodiwa: mteja aliiomba, na kuipoteza kungekuwa kubaya zaidi. Mstari ambao msimbo wake haumo kwenye katalogi huwekewa alama unresolved kwa sababu ile ile.

Kuhamisha oda kwenda confirmed (au hali yoyote ya baadaye) hutoa kilichoshikiliwa — utoaji halisi chini ya momo, kuachiliwa kwa kilichoshikiliwa chini ya external. cancelled au refunded huachilia. Oda inayosubiri isiyojibiwa huachilia yenyewe baada ya reservation_ttl_hours za duka (48 kwa chaguo-msingi) kupita.

Weka low_stock_threshold kwenye duka na utaambiwa, mara moja kwa siku kwa kila bidhaa, available inapofika hapo.

Nani anaweza kufanya nini

Ufunguo wa API hurithi ruhusa za mtu aliyeutoa, kamwe si zaidi. Kusoma kunahitaji communications.catalogue.view; kuandika kunahitaji communications.catalogue.manage. Ufunguo uliotolewa kabla ya kiungo hicho kurekodiwa hauna seti ya ruhusa ya kukaguliwa: hufanya kazi kwenye endpoints zilizokuwepo kabla ya mkataba huu na hukataliwa kwenye zilizoongezwa nao. Kama uandishi ukianza kujibu 403, toa ufunguo mpya kutoka Settings → API credentials chini ya mtumiaji mwenye ruhusa hiyo.

Kutuma bidhaa kwenye WhatsApp

/catalogues/send-product, /catalogues/send-product-list na /catalogues/send-catalogue huweka bidhaa kwenye mazungumzo. Huchukua to kwa mpokeaji na from ya hiari kwa utambulisho wa kutuma, na hutumia kitambulisho cha katalogi cha mtoa huduma na product_retailer_id, si namba zetu.

Bidhaa moja inahitaji catalogue_id na product_retailer_id; body ya hiari ≤ 1,024 na footer ≤ 60. Orodha ya bidhaa inahitaji header_text ≤ 60, body ≤ 1,024 na sehemu 1–10, kila moja ikiwa na title ≤ 24 na product_items. Katalogi nzima inahitaji body na inaweza kutaja thumbnail_product_retailer_id.

Hizi huita mtoa huduma moja kwa moja na hurudisha data.message_id, kitambulisho cha gateway — si uid ya kawaida ya ujumbe wa REST. Hakuna akaunti ya WhatsApp iliyosanidiwa hurudisha 422; kukataliwa na mtoa huduma hurudisha 502.

Oda

GET /api/v3/catalogues/orders huorodhesha oda kutoka kila jukwaa, si WhatsApp tu. platform husema kila moja ilitoka wapi — whatsapp, storefront, ivr, manual — na customer_handle ni chochote kinachomtambulisha mteja huko: kitambulisho cha WhatsApp, handle, barua pepe, namba ya simu iliyoandikwa. customer_wa_id ni jina la zamani lake na halijashikilia vitambulisho vya WhatsApp pekee kwa muda mrefu.

Chuja kwa status, platform na catalogue_id. updated_since ndio cursor ya kuuliza unapohitaji kupona kutoka kwenye callback uliyoikosa; matokeo huja mabadiliko-mapya-kwanza.

PUT /api/v3/catalogues/orders/{order}/status husogeza oda kupitia pending, confirmed, processing, shipped, delivered, cancelled, refunded. Hurekodi mabadiliko na husogeza stoku ambayo oda inashikilia (tazama hapo juu); haitekelezi grafu ya mstari na kuweka refunded hakusogezi pesa.

Soma needs_attention kabla ya kutimiza. Ikiwa ni kweli, angalau mstari mmoja ni stock_short (hatukuweza kushikilia idadi yote) au unresolved (msimbo haumo kwenye katalogi), na mtu anapaswa kuamua cha kufanya.

Mistari na jumla ya oda hugandishwa inapotengenezwa. Mabadiliko ya bei ya baadaye kwenye katalogi kamwe hayabadilishi bei ya oda iliyo wazi — mteja alinunua kwa bei aliyoonyeshwa. Tenganisha hali ya utimizaji na malipo yaliyokamilika: paid maana yake pesa imefika, si kwamba ombi lilitumwa.

Viungo vya duka na vikapu

Duka lenye ukurasa wa duka (storefront) linaweza kupokea kikapu kizima — ukubwa, nyongeza na maelezo kwa jiko — na kukituma WhatsApp kama oda moja. Katalogi ya WhatsApp yenyewe haiwezi kupanga kwa aina wala kubeba nyongeza; ukurasa wa duka unaweza. Ukubwa ni matoleo (variants), kila moja likiwa na bei yake inayochukua nafasi ya bei ya bidhaa. Nyongeza (add-ons) kila moja huongeza kwenye bei. Hakuna kati ya hivi kinachotumwa kwenye katalogi ya WhatsApp: tangazo lake huonyesha ukubwa wa bei nafuu zaidi na kutaja mingine kwenye maelezo.

POST /api/v3/shop-links hutengeneza kiungo cha menyu, aina moja (category: id au slug) au bidhaa moja (sku). Weka alichokwisha kuomba mteja kwenye items na kikapu kitafunguka kimejazwa; mstari usiolingana huorodheshwa kwenye problems, na mingine huingia hata hivyo.

{"category":"vyakula","items":[{"sku":"ML-00001","variant":"Kamili","addons":["Kachumbari"],"quantity":2,"note":"Bila vitunguu"}]}

Bila mpokeaji, jibu ni kiungo cha kushiriki (sent: false); mteja humalizia kwenye ukurasa na kutuma kikapu WhatsApp. Ukiwa na conversation_id au to (namba ya simu, msimbo wa nchi kwanza), kiungo hutumwa kwenye mazungumzo hayo kama kitufe, na chochote mteja atakachotuma kutoka kwenye ukurasa hurudi kwenye mazungumzo hayo kama oda. Kutuma humfikia mtu, kwa hiyo ufunguo pia unahitaji communications.send. Nje ya dirisha la saa 24 la WhatsApp ujumbe huru hauwezi kutumwa na jibu ni 409; tumia hatua ya Shop link kwenye flow yenye kiolezo kilichoidhinishwa badala yake.

GET /api/v3/carts huorodhesha vikapu vipya kwanza, kwa status (open, sent, ordered, abandoned, expired) na conversation_id. GET /api/v3/carts/{ref} husoma kimoja kwa msimbo wake wa herufi 5 au id yake. Kila kikapu kina umbo lilelile kila mahali — API, webhooks, MCP na flows: items[] kila mmoja na variant, options[] (nyongeza), note, quantity na bei kwa kipimo kidogo, pamoja na subtotal_minor, note, conversation_id na order_id kinapokuwa oda.

Bei ni zetu daima. Ukurasa hutuma id za bidhaa, ukubwa na nyongeza, kamwe si kiasi, na kikapu kinachodaiwa WhatsApp hupigiwa bei upya wakati huo; bei ikibadilika, mteja huambiwa jumla mpya. Oda inayotokana ni oda ya kawaida yenye platform: storefront (au whatsapp kwa menyu ya ndani ya WhatsApp), kwa hiyo yote yaliyosemwa juu kuhusu stoku na needs_attention yanahusika. Webhooks mbili hufuata kikapu: cart.submitted kinapokuwa oda na cart.abandoned kikapu kilichofunguliwa kutoka kwenye mazungumzo kinapoachwa na vitu ndani — tazama Webhooks.

The payment API lets an integration inspect money requests, settlement, refunds and the accounting entries attached to them. Both endpoints require a REST key whose issuing user currently has payments.view. They return records belonging to the key's account. A payment from another account is not returned even when you know its UUID or reference.

Find payments to reconcile

Call GET /api/v3/payments for a list ordered newest first. Pass state=open to select draft, pending and authorised payments, an individual state to select that state, or state=all for every state. An omitted state also includes everything. State input is trimmed and lowercased; an unrecognized state currently leaves the list unfiltered instead of returning a validation error. Validate state names in your client so a spelling mistake does not broaden your reconciliation query.

subject_id restricts results to a business record identifier, such as an order or data record. There is no accompanying subject-type query parameter. Inspect each result's subject_type when IDs from several record types might overlap.

curl --get 'https://business.momo.tz/api/v3/payments' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'state=open' \
  --data-urlencode 'per_page=25' \
  --data-urlencode 'page=1'

Pagination defaults to 25 and caps at 100. limit overrides per_page if both are supplied. The native response is {data:[...],meta:{current_page,per_page,total,last_page}}; there is no outer success status or data.items wrapper. Advance the page until current_page reaches last_page, and deduplicate by payment ID if records are arriving while you read.

Interpret amounts and states

Use the integer amount_minor for arithmetic and the returned amount string for display. This payment layer defines 100 minor units per major currency unit, including TZS: 4,000,000 minor units represents TZS 40,000. It does not change scale according to a currency's normal decimal convention. currency names the currency; refunded_minor and refundable_minor use the same scale. refunded is a display string when money has been refunded and null otherwise. Do not parse formatted strings back into numbers.

is_open is true only for draft, pending and authorised. is_settled means the money arrived at some point: paid, partly_refunded and refunded. It does not mean the original amount remains retained. Use refunded_minor and refundable_minor alongside it. The next_states list describes the payment state machine; it does not grant a REST write capability.

Read the full payment story

Call GET /api/v3/payments/{payment} with either the UUID or human reference, such as PAY-20301012-0001. The response is {data:{...}}. Keep the stable UUID as your primary integration key; a human reference is useful on receipts and support screens.

The summary includes payer, method, provider, attempts, last_error, expiry and settlement timestamps, subject identity, and nullable customer checkout handles. The detail adds created_by, a timeline ordered oldest first, ledger entries ordered by entry_no, and refunds ordered newest first. Timeline entries identify the old state, new state, source, message and occurrence time. Ledger entries expose their kind, debit/credit direction, account, amount and occurrence time. Read these when a state change needs explanation rather than treating last_error as a complete history.

A refund is a separate payment intent linked through refund_of, with is_refund=true and an optional reason. The original payment retains its own ID and accumulates refunded_minor. Process each refund ID once in your local accounting integration, while updating the original payment's remaining refundable amount from its current detail.

Operational boundaries

The customer REST surface provides these two reads. Collection, retry, cancellation, refund and payout actions use the authorized application or assistant workflows; there is no payment POST/PATCH action to construct from next_states. A checkout URL or token can be null when the provider has not supplied one.

Poll important pending payments with a sensible interval and respect the shared v3 rate limit. Business-event discovery currently declares payment event names with live=false; do not assume an automation payment event will replace reconciliation polling. Automation events explains how to inspect publisher availability. The messaging order.paid callback has its own payload and represents an order payment, which should be matched to payment records using the identifiers actually present.

Data tables hold the business records your account defines: bookings, customers, stock, deliveries or other structured information. Each table has its own field keys and validation rules. Discover those rules before reading or writing; a field label in the dashboard is not necessarily the key your API request must use.

Discover tables and schemas

GET /api/v3/data/tables returns {tables:[...]}. Each summary includes UUID, name, slug, description, icon, record/column counts and updated_at. The list is limited by the issuing user's permissions and table visibility.

GET /api/v3/data/tables/{table}/schema returns:

Schema reads require data.view. Record writes require data.records.edit and table write access. Table-specific grants can narrow module permissions; a hidden table is returned as 404. Re-fetch the schema after a field change or a validation response suggesting your cached rules are stale.

Field values

The data-table currency type is not catalogue minor-unit pricing. It stores an ordinary numeric amount, defaults to TZS with zero decimal places, and can use configured precision. For example, 15000 in a TZS currency field is displayed as TZS 15,000, while catalogue product price follows its separate scaling contract.

File records contain storage metadata and return signed download URLs where allowed. A JSON record write does not upload bytes. Use the account's file tooling or an authorized MCP file operation; this REST table family does not expose a file-upload endpoint. Treat returned signed URLs as expiring access links.

Sensitive data and limits

Field masks apply to record values and titles for the current caller. A masked string is a display value, not the original secret. Avoid sending an entire read response back as an update: select only fields your workflow intends to change.

Each serialized record must fit in 8,192 bytes. Table and account quota allowances can vary; read schema limits rather than hardcoding a sample allowance. Reaching a storage/record quota produces a structured quota refusal. Tables and columns are managed through the dashboard or appropriate MCP tools, while this REST family exposes records and schema discovery.

Data-record lists use cursor pagination and a typed condition tree. Build queries with column keys from the schema. Pass values with their natural JSON types: a numeric comparison should contain a number, and an opt-in comparison should contain a Boolean.

Build a condition tree

{"all":[{"column":"opt_in","op":"equals","value":true},{"column":"balance","op":"greater_than","value":10000},{"any":[{"column":"region","op":"equals","value":"dar"},{"column":"region","op":"equals","value":"arusha"}]}]}

Send this as the URL-encoded JSON filter query parameter to GET /api/v3/data/tables/{table}/records. An absent filter or {} selects all visible records. all combines conditions with AND; any with OR. A leaf names column, op and, except for empty checks, value. Trees allow up to 40 leaves and nesting depth six.

Only operators advertised by the field's type are valid. A file field, for example, advertises empty checks, not text search. Unsupported operators return a structured not_supported refusal; an unknown field or malformed tree is a validation error.

Encode query parameters safely

curl --get 'https://business.momo.tz/api/v3/data/tables/TABLE_UUID/records' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'filter={"column":"opt_in","op":"equals","value":true}' \
  --data-urlencode 'sort=$updated_at' \
  --data-urlencode 'dir=desc' \
  --data-urlencode 'limit=50' \
  --data-urlencode 'with_count=1'

Replace TABLE_UUID. Single quotes preserve the literal $updated_at system key in a shell. Add q for case-insensitive search over up to the first six text, long_text, phone and email columns. A table without those fields ignores q. Search combines with the explicit filter.

Sort defaults to newest created first. A user column key, $created_at or $updated_at can be selected; dir is asc or desc, default desc, and nulls sort last. On tables at or above the schema's sort_index_threshold, a user-column sort needs its configured index. The current refusal is HTTP 501 with code not_supported and reason sort_needs_index. System timestamp sorting remains available.

Walk pages

{"records":[],"next_cursor":null,"has_more":false,"count":0,"served_at":"2030-10-12T06:00:00Z"}

Default limit is 50, clamped between 1 and 200. When has_more is true, send next_cursor back as cursor with the same filter, q, sort and dir. Treat the token as opaque. Invalid cursor text currently restarts at the first page rather than returning an error, so store it exactly and deduplicate record IDs if restarting.

count is null unless with_count is enabled. Counting runs an additional query; request it only when the workflow needs a total. Cursor pages are not a frozen export snapshot. Concurrent writes can change membership or order, so a synchronization process should retain IDs and timestamps and reconcile overlap.

Table groups and overviews

GET /api/v3/data/groups lists group metadata. GET /data/groups/{group} returns group, member tables with columns, and saved report summaries. These groups organize data tables; they are unrelated to SMS contact groups and WhatsApp chat groups.

GET /data/groups/{group}/overview accepts a named range such as last_30_days, a JSON range object, or explicit from/to. It returns totals, member-table cards, amount headlines, time series and relationship summaries. The default is last_30_days. Use the returned window and bucket when labeling charts. These REST group operations are read-only; do not infer a report-write endpoint from a saved report summary.

Create and update records using a data object keyed by the table's column keys. Read the schema first, then send only the values your workflow controls. Required values, field types, unique constraints, status rules and table access are checked before a valid record is saved.

Create and patch

{"data":{"name":"Asha Mwinyi","phone":"0712345678","region":"dar","opt_in":true,"balance":15000}}

POST /api/v3/data/tables/{table}/records returns HTTP 201 with {record:{...}}. Unknown keys are refused. Phone, numeric and other supported fields are coerced to their canonical stored types. The record is stamped source api; its returned source records where it was created and does not change on a later edit.

PATCH /data/tables/{table}/records/{record} merges just the submitted keys:

{"data":{"region":"arusha","optional_note":null}}

Here region changes and optional_note is cleared. Other values remain. Clearing a required field fails validation. The updated response contains the full current record, including id, data, source, created_at, updated_at and title; relations may add a titles map.

The platform serializes concurrent updates to a record, but this REST API does not expose an optimistic version or If-Match precondition. If two clients update the same field, a later accepted update can overwrite it. Keep patches narrow and coordinate business decisions in your integration rather than treating updated_at as an enforced lock token.

State transitions

GET /data/tables/{table}/states describes every status field. It includes its key, label, required/strict flags, initial states and possible next moves. Each move's allowed flag reflects the caller's permission. Use state keys, not translated display labels.

A record must start in an allowed initial state when the state machine requires one. A PATCH to a status field is checked against the current record: illegal transitions return a conflict, and transitions requiring a permission the caller lacks return a permission refusal. Reading the states endpoint does not reserve a transition; another writer may change the record before your PATCH.

Use an authorized MCP transition tool when you need its explicit transition/reason workflow. This REST family does not expose a separate transition or rollback POST endpoint.

Structured failures

{"error":{"code":"conflict","message":"The record was refused. A unique value is already used. Nothing was saved.","field":"phone","retryable":false},"message":"A record with this Phone already exists.","code":"conflict","errors":{"phone":["A record with this Phone already exists."]}}

This abbreviated example shows the shape; human messages and optional details depend on the refusal. Branch on the nested error code and retryable flag, not English text.

Missing data itself is framework validation and can use {status:"error",message,errors} instead. Handle both error families.

Delete and audit

DELETE the record URL returns {ok:true,deleted:1}. It soft-deletes the record, removes it from ordinary lists/reads and frees its record quota contribution. Repeating deletion returns 404; this is not evidence that the earlier delete failed.

GET {record}/history returns history entries, has_more, next_before and field-label columns. Pages contain up to 50 entries, newest first; return next_before as before without reformatting it. Entries name the record, action, changed fields, before/after values, actor, source, optional reason and timestamp. History remains readable after deletion, subject to table access. It is an audit trail, not a recoverable record-version API, and an empty trail does not establish that a current record exists.

Sura hii inaeleza webhooks za mawasiliano — ujumbe, oda, katalogi, vikundi. Webhooks za usajili wa automations zina saini, bahasha na sheria zake za kurudia.

Webhooks ni maombi ya HTTP kutoka Momo Business kwenda kwenye mpokeaji unaoendesha wewe. Si endpoints unazoziita kwenye /api/v3. Zitumie kujua matukio wakati yanapotokea, kisha sawazisha hali muhimu kupitia endpoints husika za kusoma.

Tunachoweza kutuma

GET /api/v3/webhooks/events huorodhesha kila tukio, kwa makundi, likiwa na mfano kamili wa payload. Kichaguzi kwenye Settings → Webhooks huonyesha orodha ile ile, na enum ya event kwenye schema ya uwasilishaji ya API hili hutengenezwa kutoka kwake — hivyo jina unaloliona kwenye yoyote kati ya hizo tatu ni lile ambalo jukwaa hutuma kweli.

order.received hutokea kwa oda kutoka jukwaa lolote — cart ya WhatsApp, storefront yako, flow, menyu za simu — na hubeba order.stock_policy, inayokuambia kama unatarajiwa kutoa stoku. order.status_changed hutokea kutoka kila njia inayobadilisha hali: dashibodi, programu ya wafanyakazi, API, agent. Hakuna kati ya hizo iliyokuwepo kama ishara ya kuaminika awali; zote mbili ndizo integration ya duka huishi juu yake.

Sajili mpokeaji

Kutoka dashibodi: Settings → Webhooks, inahitaji webhooks.manage. Kutoka API:

POST /api/v3/webhooks
{"url":"https://store.example.com/momo","events":["order.received","order.status_changed","stock.low"]}

Anwani lazima iwe https (endpoint iliyosajiliwa kwa http kabla ya 26 Septemba 2026 inaendelea kufanya kazi mpaka anwani yake ibadilishwe). Anwani za ndani na za faragha hukataliwa; hostname hukaguliwa tena kwenye kila jaribio la uwasilishaji; redirects hazifuatwi.

Jibu hubeba secret — mara pekee inapoonyeshwa. Ihifadhi kwenye mazingira ya mpokeaji wako. POST /api/v3/webhooks/{webhook}/rotate-secret hutoa mpya kwa njia ile ile; ya zamani huacha kuthibitisha mara moja, hivyo sasisha mpokeaji kwanza na uzungushe baadaye. GET, PATCH na DELETE kwenye /api/v3/webhooks/{webhook} hufanya wanachosema; ufunguo unahitaji webhooks.view kusoma na webhooks.manage kubadilisha.

Thibitisha uwasilishaji

Kila uwasilishaji hubeba vichwa vitano:

X-Signature:     <hex HMAC-SHA256 ya mwili ghafi>
X-Signature-V2:  sha256=<hex HMAC-SHA256 ya "{X-Timestamp}.{X-Delivery-Id}.{mwili ghafi}">
X-Timestamp:     1757581442
X-Delivery-Id:   dlv_01j9qk3v8x2m7n4p5r6s
X-Event-Id:      evt_01J8Z6Q4M3T8W5K2N7XQ4R9ABC
X-Event:         order.received
Content-Type:    application/json

X-Signature haijabadilika kutoka toleo la kwanza la mkataba huu, hivyo mpokeaji aliyeandikwa dhidi yake anaendelea kufanya kazi. Pendelea X-Signature-V2: kuikagua hukupa ulinzi dhidi ya replay bure — kataa timestamp iliyo na zaidi ya dakika tano, na kumbuka vitambulisho vya uwasilishaji ulivyoshashughulikia. Ondoa nakala kwa X-Event-Id — thamani ile ile na event_id ndani ya mwili. Ni ile ile kwenye kila jaribio, kila replay na kila endpoint inayopokea tukio. X-Delivery-Id ni ile ile kwenye majaribio ya kiotomatiki ya uwasilishaji mmoja lakini mpya kwa replay ya mkono, hivyo ni sehemu ya sahihi, si ufunguo wa kuondoa nakala.

Thibitisha juu ya bytes ghafi, kabla ya kuchanganua au kuandika upya:

$raw = file_get_contents('php://input');
$secret = getenv('MOMO_WEBHOOK_SECRET');
$ts = $_SERVER['HTTP_X_TIMESTAMP'] ?? '';
$id = $_SERVER['HTTP_X_DELIVERY_ID'] ?? '';
$given = $_SERVER['HTTP_X_SIGNATURE_V2'] ?? '';
$eventId = $_SERVER['HTTP_X_EVENT_ID'] ?? '';

if (abs(time() - (int) $ts) > 300) { http_response_code(401); exit; }

$expected = 'sha256='.hash_hmac('sha256', "$ts.$id.$raw", $secret);
if (!hash_equals($expected, $given)) { http_response_code(401); exit; }

if (alreadySeen($eventId)) { http_response_code(200); exit; }   // jaribio au replay ulilokwisha shughulikia

$event = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
enqueue($event);              // hifadhi kwanza, shughulikia baadaye
markSeen($eventId);
http_response_code(200);

Payloads za oda

{"event":"order.received","timestamp":"2026-09-11T09:14:02+00:00",
 "order":{"id":9182,"catalogue_id":42,"platform":"whatsapp","status":"pending","needs_attention":false,
          "stock_policy":"external","customer_handle":"255712345678","customer_name":"Asha Mrisho",
          "lines":[{"sku":"MNG-45W","name":"Charger Mango 45W","quantity":1,"unit_price_minor":3900000,
                    "line_total_minor":3900000,"currency":"TZS","reserved":1,"stock_short":false,"unresolved":false}],
          "total_minor":3900000,"currency":"TZS","conversation_id":771,"priced_at":"2026-09-11T09:14:02+00:00"}}

Soma order.lines[].sku na quantity kutoa stoku yako mwenyewe stock_policy inapokuwa external. needs_attention maana yake mstari ni stock_short (hatukuweza kushikilia idadi yote) au unresolved (msimbo haumo kwenye katalogi) — mtu anapaswa kuangalia kabla ya kusafirisha. priced_at hurekodi kwamba mistari na jumla ziligandishwa wakati wa kutengenezwa; mabadiliko ya bei ya baadaye kwenye katalogi kamwe hayabadilishi bei ya oda iliyo wazi.

order.status_changed hubeba kitu kile kile cha order pamoja na previous_status. order.cancelled ni kile kile tena, hutumwa wakati wa kufuta tu, kwa wapokeaji wasiojali kingine. Stoku yoyote ambayo oda ilikuwa inashikilia imeshaachiliwa unapoipokea.

Majina ya zamani ya kiwango cha juu — order_id, customer_wa_id, product_items, total_amount, total_currency — bado yapo kwenye kila tukio la oda kwa toleo moja. Hamia kwenye order.*; yamewekwa alama ya deprecated kwenye spec.

order.paid haijabadilika: order_id, payment_id, method, amount_minor, currency, payer_msisdn, paid_at, conversation_id. Maana yake pesa imefika, si kwamba ombi lilitumwa.

Payloads za katalogi

sync.completed hubeba ripoti ile ile ya GET /api/v3/catalogues/{catalogue}/syncs/{sync} chini ya sync, bila problems — orodha hiyo inaweza kuwa safu mia mbili, hivyo isome kutoka endpoint rejected au hesabu ya blocked ya jukwaa isipokuwa sifuri. product.blocked hutokea mara moja kwa kila bidhaa kwa kila jukwaa lililoikataa, likiwa na problem kwa maneno. product.drifted hutokea nakala ya jukwaa inapotofautiana na yetu, likiwa na diff sehemu kwa sehemu. stock.low hutokea mara moja kwa kila bidhaa kwa siku available inapofika low_stock_threshold ya duka.

Payloads za ujumbe na vikundi

Matukio ya ujumbe ni tambarare: message_id, direction, sender, recipient, status, body, media_url, channel_type. Tumia message_id ya namba na endpoint ya kusoma SMS/WhatsApp kupata rekodi kamili. Matukio ya vikundi hubeba muhtasari wa group; tumia kitambulisho chake kuchukua hali ya sasa.

Uwasilishaji, kurudia na rekodi

Kila uwasilishaji ni rekodi. GET /api/v3/webhooks/{webhook}/deliveries huziorodhesha mpya kwanza — kilichotumwa, mara ngapi, hali ya mwisho ya HTTP na kilobaiti ya kwanza ya kile mpokeaji wako alichosema. Chuja kwa status, event au since. Rekodi ile ile iko chini ya kila endpoint kwenye Settings → Webhooks, ikiwa na hesabu za kila endpoint kwa saa 24 zilizopita.

Kurudia. 5xx, 408, 425 au 429, timeout au kushindwa kuunganisha hurudiwa mara tano kwa takriban saa sita: baada ya dakika 1, 5, 30, saa 2, saa 6 — majaribio sita kwa jumla. 4xx nyingine yoyote huchukuliwa kama "nimeelewa na nakataa" na hairudiwi — kurudia 401 mara tano hakubadilishi chochote.

Kusimamisha. Baada ya kushindwa hamsini mfululizo endpoint husimamishwa: uwasilishaji hurekodiwa kama skipped badala ya kutumwa, akaunti huarifiwa, na endpoints zako nyingine hupokea webhook.paused. Rekebisha mpokeaji, kisha rudia uwasilishaji wowote ulioshindikana — POST /api/v3/webhooks/{webhook}/deliveries/{delivery}/replay, au kitufe cha Replay kwenye rekodi — na endpoint huendelea. Kuweka is_active: true tena hufanya vivyo hivyo.

Jibu 2xx haraka. Hifadhi au weka kwenye foleni tukio, kisha kubali; weka kazi ya baadaye nje ya ombi. Uwasilishaji ni angalau-mara-moja na mpangilio kati ya matukio hauhakikishwi, hivyo fanya masasisho ya hali yanayorudiwa yasiwe na madhara na ondoa nakala kwa X-Event-Id. Unapohitaji kupona kutoka kwenye hitilafu upande wako, GET /api/v3/catalogues/orders?updated_since= ndio cursor ya kuuliza.

The automation REST API provides three reads: business events, event subscriptions and recurring schedules. Each requires automations.view on the REST key's current issuing user. Configure or change automations through the authorized application or MCP tools; these REST routes do not create, pause, retry or delete them.

Poll the business event log

GET /api/v3/automations/events returns {events,has_more,next_before,event_keys}. Each event carries a stable UUID, key and label, subject_type and subject_id, payload, actor, occurred_at, delivered_at and delivered_count. Store the event UUID to make repeated polling harmless. The payload depends on the event key; read the relevant subject resource when you need its current complete state. Payloads exceeding the publisher’s 64,000-byte budget lose the largest top-level keys and carry __truncated listing removed keys. A record change can emit both record.transitioned and record.updated when it changes a status and another field; a no-op emits neither.

curl --get 'https://business.momo.tz/api/v3/automations/events' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json' \
  --data-urlencode 'key=record.transitioned' \
  --data-urlencode 'limit=50'

The optional key must be a known event name or the API returns 422. Omit it to read all keys; * is for subscriptions, not this query. subject_id narrows events to one subject ID. limit is clamped to 1–50 and defaults to 50. Results are newest first. To go backwards, pass next_before as before, preserving its timezone and URL encoding.

The cursor is a strict timestamp comparison, not an opaque unique position. An unreadable before value currently restarts at the newest page. A full page sets has_more=true even when there may be no subsequent rows, so an additional empty page is normal. Events sharing the boundary timestamp are not distinguished by an ID tie-breaker; do not use this API as a guaranteed lossless bulk export under high event volume. Keep a local event audit, deduplicate refreshed pages and reconcile important source records. delivered_at indicates fan-out processing, while delivered_count counts successful dispatch outcomes, including queued webhook/agent jobs; an external webhook job can still be pending or later fail.

Discover which events actually publish

Every page includes event_keys metadata: key, label, group, subject, publisher and live. A declared event with live=false is part of the vocabulary but its publisher is not currently active. Read this flag instead of assuming every listed key emits.

The business-event message.received name belongs to this bus. The existing messaging webhook dispatcher can independently emit its own message.received callback; the availability and delivery rules of the two systems are separate.

Inspect subscriptions and failures

GET /api/v3/automations/subscriptions returns {subscriptions:[...]}, ordered by key and label, capped at 200 without pagination. key=record.created includes both matching subscriptions and wildcard subscriptions. enabled_only=true leaves out disabled subscriptions. Unknown key strings are not rejected on this read; matching wildcard rows can still appear.

Each subscription has an ID, key, kind, target, label, optional filter/config, enabled flag and counters. Kinds are flow, notification, webhook and agent. A target means a flow or agent ID, a notification audience, or a webhook URL according to kind. Conditions apply to the event payload. signed reports that a signing secret exists; the secret itself is never returned by this read.

Inspect last_error, last_failed_at and failure_count together. A failure count reaching ten switches a subscription off. Successful fan-out dispatch resets the count; for a webhook this includes being queued, before the HTTP delivery result is known. Confirm external receipt in your receiver audit. Paused subscriptions require an authorized change through the application or MCP. For webhook subscriptions, intermediate retries do not each increment failure_count: the final failed delivery does. Watch enabled as well as last_fired_at so an old successful timestamp does not hide a disabled subscription.

Business webhook signature and retry contract

Automation webhook subscriptions use X-Momo-Signature, a different protocol from communication webhooks:

X-Momo-Signature: t=1918015200,v1=HEX_HMAC_SHA256
X-Momo-Event: record.created
X-Momo-Event-Id: EVENT_UUID
X-Momo-Subscription: 12
X-Momo-Attempt: 1

Compute HMAC-SHA256 over <timestamp>.<raw request body> with the subscription secret. Compare hexadecimal digests in constant time and check the signed timestamp against a short clock tolerance; the platform verification helper defaults to 300 seconds. Use the original bytes, not re-encoded JSON. Provision the secret when the subscription is authored or rotated; the REST list only reports its presence.

{"id":"01953b60-4ce0-7000-8000-000000000001","event":"record.created","occurred_at":"2030-10-12T06:00:00+00:00","tenant_id":42,"subject":{"type":"data_record","id":"01953b60-4ce0-7000-8000-000000000002"},"actor":{"kind":"api","label":"ERP integration","id":7},"data":{"table":{"id":"01953b60-4ce0-7000-8000-000000000003","name":"Customers","slug":"customers"},"record_id":"01953b60-4ce0-7000-8000-000000000002","record":{"name":"Example"},"source":"api"},"subscription":{"id":12,"label":"Forward record changes"}}

This example illustrates the envelope; data and actor contents depend on the publisher. Deduplicate by event ID for each subscription you process. Acknowledge with a 2xx response after durable acceptance. The job makes up to six attempts, with a 15-second HTTP timeout. Transport failures, HTTP 408, 429 and 5xx can retry. Other refusals, including 401/403/404 and validation errors, are not retryable. Default delays are 10, 20, 40, 80 and 160 seconds between attempts. A positive numeric Retry-After overrides the next delay, capped at 300 seconds; HTTP-date Retry-After is not interpreted. A new signature timestamp is generated for each attempt. Queue availability can extend actual delivery time.

Read recurring schedules

GET /api/v3/automations/schedules returns {schedules:[...]}, ordered by name, capped at 300 without pagination. Filter by kind=flow, report, record, call or message and optionally enabled_only=true. An unknown kind matches no rows rather than producing validation errors.

Show describes as the readable rhythm and retain spec for structured inspection: every, unit, at, weekdays, day_of_month, timezone and optional until/count. The occurrence timestamps are separate from the configured timezone. Read enabled and next_run_at together; a null next run can indicate a disabled, exhausted or invalid schedule. An invalid stored specification remains readable with an explanatory describes sentence so an owner can repair it.

last_result carries the latest execution outcome, with optional misfire details; last_error and run_count provide operational context. A run receipt is not necessarily the final delivery status of the message, call or flow it started. Follow the resulting reference into that resource's API when available.

The misfire policy controls missed occurrences: run_once performs one late run then advances; skip advances without running missed work; run_all replays missed slots, capped at 12 per runner tick. A slot less than or equal to 90 seconds late is still considered on time. These recurring schedules are distinct from a one-off scheduled message or campaign. Inspect the correct resource when diagnosing an unexpected send time.

Agent tasks let an integration ask a configured account agent to perform work and then inspect the execution. They use the same REST Bearer key as /api/v3, but their URLs and response envelopes are separate: POST /api/engine/tasks and GET /api/engine/runs/{uuid}.

Prepare an agent

Choose an agent belonging to the authenticated account. The account's engine must be enabled, the agent must have an enabled engine profile, and its API availability must be enabled. Agent tools, permissions and spending limits remain governed by its configuration. A run can be denied even when authentication and the request fields are valid.

Agent tasks execute the configured agent and may incur model/tool usage. This is an execution interface, not a free validation endpoint. Read the returned usage and run cost fields when reconciling your integration's activity.

Submit work

{"agent_id":42,"prompt":"Summarize the supplied order details and return the next action.","context":{"order_reference":"ORD-1042","customer_note":"Please arrange collection tomorrow."},"mode":"queued","max_duration_ms":30000}

Use queued mode when the caller can poll. A successful queued acceptance returns 202 with status, run_uuid, execution_state, delivery_state, deadline_at, status_url and denial_reason. A denied or already timed-out submission can return 422 instead. Retain the run UUID regardless of the status so you can inspect what happened.

The API adapter has a 60-second ceiling. The requested duration and configured profile duration can reduce that budget; a large max_duration_ms does not extend it. Queued work still has a deadline. Scheduling it in the background is not a request to wait indefinitely for capacity.

Idempotency belongs to this endpoint

curl 'https://business.momo.tz/api/engine/tasks' \
  --header "Authorization: Bearer $MOMO_API_KEY" \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --header 'Idempotency-Key: order-1042-next-action-v1' \
  --data '{"agent_id":42,"prompt":"Summarize this order.","context":{"order_reference":"ORD-1042"},"mode":"queued"}'

Idempotency-Key is optional, 1–191 characters when supplied. The platform scopes it to the tenant and task trigger. Repeating the key with the same request fingerprint returns the existing run; using it for different agent/prompt/context or other fingerprinted task inputs returns 409. Reuse the same key after an uncertain response, and use a new key for genuinely new work. No fixed expiry period for this key is promised by this contract.

Do not transfer that assumption to ordinary SMS/WhatsApp POSTs, which lack request-key deduplication. See delivery retries.

Poll and distinguish outcome from transport

GET status_url or /api/engine/runs/{uuid} returns run, children and steps. The run includes execution/delivery state, deadline, output, denial_reason, provider/model, token counts, cost/currency, duration and creation time. Steps expose position, kind, tool_name, arguments, result_preview, status and duration. Treat these as potentially sensitive business data when logging.

Sync mode returns HTTP 200 with status, run_uuid, output, denial_reason and usage. A successful run reports succeeded. A 200 can also contain failed, denied, timed_out or handoff; inspect status. Background progress can include queued, running, waiting_tools, waiting_children, awaiting_human, retry_scheduled and finalizing. An awaiting-human state needs its approval workflow, not repeated submission.

Capacity refusal returns 429 with Retry-After 5; temporary ingress contention returns 503 with Retry-After 1. A different payload under an existing key returns 409. Correct account/profile denials before retrying. Agent responses are not wrapped in the ordinary v3 success envelope, and the shared v3 120/minute route throttle is not the rate contract for this separate route group.

MCP connects an assistant to account tools through Streamable HTTP and JSON-RPC. The REST reference lists transport endpoints; the tool catalogue below lists tool names, arguments and permissions. A tool is invoked through tools/call, not through an invented REST URL named after the tool.

Choose a connection URL

Use /mcp when the client supports one connector URL for the product. Use a domain URL when you want a focused connection such as messaging, contacts, data, calls or orders. Read available server keys from discovery/the catalogue rather than assuming a product label is the URL key.

The public manifest describes the platform's catalogue. The tools actually available to a connection depend on its granted servers, scopes, current issuer permissions and feature availability. Call tools/list after connecting and use the returned names and schemas. Aggregate tool names can differ from their per-domain names; do not move a domain tool name to /mcp without discovering it there.

Static MCP credentials

Open API credentials and create an MCP connection. Choose a name, server list and permission preset. Optional expiry is 1–730 days; omitted expiry leaves no expiry date. The token starts with momo_mcp_ and is revealed once. The page returns configuration for the selected domains.

{"mcpServers":{"momo-messaging":{"type":"http","url":"https://business.momo.tz/mcp/v1/messaging","headers":{"Authorization":"Bearer YOUR_MCP_CONNECTION_TOKEN"}}}}

Keep the credential in your client's supported secret configuration. Its permissions are intersected with what the issuing user may currently do. Revoking the connection stops subsequent access. A REST API key is rejected here even if it belongs to the same tenant.

OAuth connection flow

Hosted clients can discover OAuth metadata at /.well-known/oauth-protected-resource and /.well-known/oauth-authorization-server. The authorization-server document publishes the actual authorize, token and registration URLs. Use those values rather than constructing provider URLs yourself.

1. Register the client through /oauth/register when dynamic registration is needed. The registration endpoint is anonymous but subject to redirect-URI restrictions and a 10/minute/IP throttle.
2. Generate a PKCE verifier and S256 challenge, then open the authorization endpoint with response_type=code, client_id, redirect_uri, scope, state and the challenge parameters.
3. The account user signs in and selects capabilities/elevations at consent. Verify the returned state before accepting the authorization code.
4. Exchange the code at /oauth/token using application/x-www-form-urlencoded, including grant_type=authorization_code, code, client_id, redirect_uri and code_verifier.
5. Send the resulting access token as Bearer to the MCP URL. Refresh through the same token endpoint with grant_type=refresh_token and the returned refresh token.

OAuth access tokens are configured for one hour and refresh tokens for 30 days. Respect returned expires_in and any replacement refresh token. This is an authorization-code flow with PKCE; do not invent a client-credentials grant or treat a static API key as an OAuth client secret.

Capabilities and elevations

OAuth requires mcp:use and grants capabilities such as messaging, calls, data or commerce. Elevations add actions with wider consequences: mcp:send, mcp:publish, mcp:spend, mcp:delete, and data-specific mcp:write/mcp:shape. A capability alone does not grant every sensitive action in that domain.

Data record writes need the data capability and write elevation; schema changes need shape. Deletion tools require their underlying write/shape permission and the delete elevation. The consenting user's current permissions remain the ceiling, so an owner cannot grant a connection more authority than the user actually holds.

Tool calls and errors

Follow the MCP client's initialization handshake and negotiated protocol version, then discover tools. A JSON-RPC request has jsonrpc 2.0, an id, method and params. Read the tool's inputSchema and annotations before calling it; some writes create drafts, others publish, send or spend immediately.

The MCP route limiter allows 120 requests/minute per static credential, falling back to the OAuth user's identity where applicable. A throttled response is HTTP 429 with JSON-RPC error code -32003. Back off rather than looping. Permission, server-grant, expired-token and account-state failures need configuration changes. For a successful HTTP response, also inspect JSON-RPC errors and the tool's isError result.

Cache the public manifest with its ETag if useful, but refresh runtime tool discovery when a connection or grant changes. Per-tool schema/version metadata helps detect contract changes; it is not a promise that an old input remains valid after a schema update.

Send Authorization: Bearer <REST key>. Create and revoke keys at /app/api-credentials; the plaintext is returned once. Tenant identity comes from the key, never a request tenant_id.

Data and WhatsApp group endpoints check the key issuer's current permissions; a missing/deactivated issuer is refused there. Legacy message, campaign, contact, catalogue and profile controllers use the tenant credential without this per-action permission map. Treat REST keys as powerful credentials.

Missing, invalid, revoked, expired or wrong-kind REST credentials return 401. A suspended/inactive account returns 403. REST API keys and MCP credentials cannot be interchanged.

Groups of up to 8 people created from a business number. Invite-only: you send the link, they choose to join. Needs an Official Business Account. Group events also arrive as webhooks (group.created, group.participant_joined, …).

A key here inherits the permissions of the user who created it: communications.groups.view to read, communications.groups.manage to change a group, and both that and communications.send to post into one. A key with no creator on record is refused.

Every potential customer, at any stage, in one pipeline. A lead is one person's sales record — new, contacted, qualified, opportunity, won, lost or unqualified — attached to the calls, chats, comments and form answers it came through. The AI agent writes leads during chats and after calls, staff work them in the dashboard, and this API is the same door for your CRM.

One lead per person. POST /api/v3/leads is an upsert: the person is found through the workspace's identity layer — a phone number (in any common form), a WhatsApp id or an email all resolve to the same person — and their lead is updated, or created if they have none. Send a conversation_id or call_id to attach that record and identify the customer by it.

Who sees what. A key inherits its issuer's permissions (leads.view to read, leads.edit to write, leads.assign, leads.delete, leads.settings for the rest) and visibility: without leads.data.all a key sees the issuer's leads, the unassigned pool and the ones the issuer added. The module can be switched off per workspace; its endpoints then answer 403.

Refusals carry a code. Besides message, a refused write returns reason — invalid, reason_required, nothing_to_identify, won_locked, assignee_unknown — so a sync can branch on it.

Events. Subscribe a webhook to lead.created, lead.updated, lead.stage_changed, lead.label_added, lead.label_removed, lead.note_added, lead.assigned, lead.merged and lead.deleted to keep another system in step; see the Webhooks tag.

Read existing shops, manage products, send WhatsApp product messages and inspect customer orders. Resource paths use local numeric IDs; commerce sends use provider catalogue IDs and product retailer IDs. Product price/sale_price and order total_amount use integer hundredths; these differ from data-table currency fields.

Product send endpoints call the provider directly and return its message_id, not a local Message UID. Product synchronization is not an atomic transaction across the local store and provider. Order status updates accept the documented enum and record history without enforcing a linear transition graph or performing a payment refund.

Read schemas and operate on account-defined business records. Tables, groups and records use UUIDs. Read permissions are data.view; record writes need data.records.edit plus table access. Schema responses describe types, masks, grants, unique sets, quotas and state rules.

Record pages use next_cursor/has_more, with a default limit of 50 and maximum 200. Record PATCH merges submitted keys, with null clearing an optional value. Source stays fixed at creation. State changes are enforced; history is an audit trail, not a record-version rollback API.

Data responses have native envelopes. Expected refusals contain a structured error object: validation_error 422, conflict 409, quota_exceeded 402, not_found 404, permission_denied 403, not_supported 501, rate_limited 429, provider_failure 502 or temporary_failure 503. Framework/authentication failures can use the standard v3 error envelope.

The named things this business can do — create a booking, register a customer, process a refund — each written down once by the business and callable from a chat flow, a phone menu, an assistant or your own code. An operation validates its inputs before anything happens, runs its steps inside a compensating transaction, and records every run with its inputs, its outputs and per-step timing.

This is the one write these platform phases added to v3, and deliberately: an operation can only do what somebody in the workspace already defined for it, so a key calling create_booking cannot make it do anything but create a booking. The definitions themselves are written on the Operations page or through an MCP connection — never with a long-lived key.

Submit prompts to configured account agents and poll run progress. Uses a REST API key at /api/engine, with native run envelopes and optional Idempotency-Key protection.

The account engine, agent profile and API availability must permit execution. Tasks may incur usage. Queued acceptance is 202; sync HTTP 200 still requires checking the run status. This route group is separate from the v3 shared throttle and error renderer.

The same account, the same permissions, reached by a language model instead of by your own code.

MCP — the Model Context Protocol — is not a REST API, and this document does not pretend that it is. One MCP server is one HTTP endpoint speaking JSON-RPC 2.0: the operation is the method in the body rather than the URL, the tools are discovered at runtime with tools/list, and each tool's arguments are a JSON Schema rather than path, query and body parameters.

Writing 348 tools as 348 near-identical POST operations would validate perfectly and teach nobody anything. So what is documented under this tag is the transport — the 31 servers' endpoints, the envelope, the OAuth handshake and where the tool contract lives. The tool contract itself is GET /api-docs/mcp.json, which carries a full JSON Schema per tool and is generated from the same code as this section.

Which one should I use

The REST API when your own code drives the interaction — a cron job, a webhook handler, your backend. You know before you deploy which call you want to make, so a fixed contract is exactly what you want.

MCP when a language model drives it — Claude, ChatGPT, or an agent you built. It chooses the call at runtime from what tools/list told it, which is only possible because the tool list is negotiated rather than compiled in.

They reach the same data and enforce the same permissions. What differs is who is holding the wheel.

Where each REST tag lands in MCP

Webhooks have no MCP equivalent, and will not. MCP is request/response with the model asking; Momo Business calling you when something happens stays an HTTP callback.

Reachable only over MCP today: ivr, flows, forms, data, approvals, payments, automations, alerts, operations, studio, numbers, agents, tickets, kb, content, calls, routing, meetings, comments, posts, leads, accounts, navigate.

Authenticating

Two credentials reach the same endpoints, and both resolve to the account's identity narrowed to what was actually granted.

• Authorization: Bearer momo_mcp_… — an MCP connection from Dashboard → Settings → API credentials. For Claude Code, Claude Desktop, a self-hosted agent or curl. A v3 API key is refused here: same table, very different blast radius.
• OAuth 2.1 with dynamic client registration — for claude.ai and ChatGPT, which have nowhere to paste a static token. Discovery, registration, authorization code with PKCE (S256), then the same bearer header.

Scopes come in two kinds, and the split is the safety model: a capability says which part of the business, an elevation says how far — publish, send, spend, delete, and for the data tables write and shape — and crosses every capability granted.

Whatever is granted is still intersected with what the consenting person can do. Scopes are a request; permissions are the ceiling.