API documentation

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.

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".

The commerce API is how an online store, a point-of-sale system or a spreadsheet-driven back office keeps its products and orders in step with Momo Business — and through Momo Business, with WhatsApp and every other platform a shop is published on.

A catalogue (a shop) holds products, brands, categories and orders. It is complete and useful with no platform attached at all: the assistant, the phone menus and the staff app all read it. A channel is that shop's presence on one platform. A listing is one product as one platform sees it. That separation is why the same product can be live on your storefront and blocked on WhatsApp, and why each says so in its own words instead of leaving you to guess.

Create the shop, then fill it

POST /api/v3/catalogues makes a shop from your own system, so an integration can finish its setup without anyone opening a dashboard. Connecting that shop to WhatsApp stays a dashboard step — it needs a consent a bearer token cannot give on a person's behalf. Read channels[] on any catalogue response to see where it is published.

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

stock_policy decides who owns the stock count. external means your system owns it: we mirror what you send and tell you what sold, and we never decide a new number on your behalf. momo means we keep the count. A shop created through this API defaults to external; one created in the dashboard or from a spreadsheet defaults to momo. PATCH /api/v3/catalogues/{catalogue} changes any of it afterwards. sku_prefix is accepted on create only — it is stamped into every code the shop has already issued.

Product identity and money

You never have to invent a code. Send no sku and the shop issues one — MNG-00042 — readable, sortable and unique per shop. Once a product is live on any platform its code is frozen: platforms treat it as the item's identity, and changing it would orphan the remote item and silently create a duplicate.

Only name and price are required. An image, a non-zero price and the rest are what individual platforms require, and a product missing them is stored and reported as blocked on that platform rather than refused outright. A shop selling only on its own storefront should not have to satisfy Meta's rules.

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

Leave currency out and the shop's own is used. Leave availability out and it is derived from inventory: a count of zero means out of stock unless the shop allows backorders. Send availability explicitly and what you send wins. Brand and category text becomes records on first use, so one import fills the pick lists for everything typed afterwards.

The bulk sync

POST /api/v3/catalogues/{catalogue}/products/batch is the endpoint a store integration lives on. Up to 5,000 products, every documented field stored — not just the identity ones.

It answers 202, not 200. The rows are accepted, and applying them and pushing them to a platform happens in the background, because that takes longer than an HTTP request should. The response carries a sync id.

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

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

Send Idempotency-Key on anything scheduled. Repeating a key returns the run that already owns it with "replayed": true and imports nothing, so a cron that times out is safe to retry.

mode is upsert by default: products your payload does not mention are left alone. mode: "replace" says this payload is the catalogue and retires everything missing from it — correct for a full nightly export, destructive for a partial one.

Rows are matched on sku when you send one, and on the product name when you do not, so a sheet with no code column updates its rows on a re-import instead of duplicating them.

One bad row does not refuse the file. A row that cannot be stored becomes one rejected row in the report; the other 4,999 land.

No developer? Point us at a feed

Every store platform — Shopify, WooCommerce, Magento, PrestaShop, Wix — can publish a Google Shopping feed or a Meta product feed with a setting, no code. POST /api/v3/catalogues/{catalogue}/feeds points a shop at that URL and we pull it on a schedule.

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

The first pull runs at once. Column names are guessed from the feed's own headers (g:id, g:price, g:availability and the rest are all known), kept on the feed, and can be corrected with mapping. Every pull is a sync like any other — read last_sync_id at GET /catalogues/{catalogue}/syncs/{sync} for the same report the batch endpoint produces. mode defaults to replace because a feed is normally the whole catalogue; set upsert if yours is partial.

A feed is one-way, so put the shop under stock_policy: external: the store owns the count, the feed states it, and orders here are reported back through webhooks for the store to act on. CSV and JSON feeds work the same way. After ten failed pulls in a row the feed is switched off and the account is told; fix it and switch it back on. POST …/feeds/{feed}/run pulls now, whatever the schedule.

Read the report

GET /api/v3/catalogues/{catalogue}/syncs/{sync} is the other half of the contract. Poll it until status is completed or 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 is the field to read first. ingest means the row was not stored at all — fix it and send it again. Any other value is a platform name: the product is stored and correct on our side, and that platform will not show it until the stated problem is fixed. Both look like "my product is not live", and they need different actions. At most 200 problems are kept; problems_truncated says when there were more.

GET /api/v3/catalogues/{catalogue}/syncs lists past runs, newest first, including feed pulls and spreadsheet imports.

Changing one product

PUT /api/v3/catalogues/{catalogue}/products/by-sku/{sku} addresses a product by the code your system already knows it by, so a sync never has to keep a map of our ids. It creates the product when there is none, so a store that has just added an item does not have to know whether we have seen it before.

Only the fields you send are touched. {"inventory": 0} is a stock update and nothing else — it does not blank the description.

GET and DELETE work the same way on the same path. Deleting takes the product off every platform it is on, then off the shelf. The numeric-id paths (/products/{product}) do the same thing and are unchanged.

Product reads carry listings[]: one row per platform with its state (pending, syncing, synced, failed, blocked, drifted) and the problem where there is one. sync_status on the product is a roll-up of those rows — a product in a shop with no platforms is synced, because there is genuinely nothing to sync.

Platforms, and who is right

A shop is published to platforms through channels; a product is one listing per platform. The same product can be synced on your storefront, blocked on WhatsApp (no image), and pending on Instagram at the same time, and each row says so.

Drift. A merchant who edits a price directly in Meta Commerce Manager has made a decision, and the next push from your system or from momo used to overwrite it in silence. Every hour, each platform's copy is compared with ours. A difference marks the listing drifted, records the field-by-field drift, sends product.drifted to your webhooks, and then applies the shop's rule:

Stock is never part of the comparison — it is a ledger, and platforms only ever see the availability word derived from it. image_url is not compared either, because Meta re-hosts every image it fetches.

Sending a product. POST /api/v3/catalogues/send-product takes a platform. On WhatsApp it is Meta's interactive product card, as before. On any other platform the honest answer is a link: the response carries the product's address there and the endpoint to send it with, so there is one send path for every platform rather than one per platform. A product not published on that platform is refused with a 422 that says so. send-product-list and send-catalogue are WhatsApp's own interactive types with no equivalent elsewhere, and stay WhatsApp-only.

Stock, in both directions

Stock is a ledger, and every shop declares who owns it.

Under stock_policy: external — the default for a shop created through this API — your system owns the count. Push levels with the endpoint below, and we mirror them and tell you what sold. A confirmed sale never decrements on our side, because your system is about to state the new level and the two must not both subtract. We still hold units for a pending order between your syncs, so the same last unit is never promised to two customers.

Under momo — the default for a shop made in the dashboard or from a spreadsheet — we keep the count. A pending order reserves units; confirming it commits them; cancelling releases them; staff adjust by hand with a reason.

Either way, a product with no inventory at all is not tracked. Nobody typed a count, so nothing is held back and nothing is ever refused. Most products start this way and that is not a fault.

Push levels

POST /api/v3/catalogues/{catalogue}/inventory is what to call the moment something sells on your own site. Up to 5,000 rows, keyed by your own codes, nothing but the count.

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

Levels are absolute, never deltas: your system is stating what it has, and a delta would drift the first time a message was delivered twice.

Availability follows the count. Unless the shop allows backorders, 0 sets the product to out of stock and stock coming back lifts it to in stock. The response names every product where that happened under derived, and one push goes to every platform the shop is on — so a sell-out reaches WhatsApp without you sending six whole products one at a time. A discontinued or preorder product is never quietly put back on sale by a delivery arriving.

Codes we do not have come back in unknown_skus rather than being ignored. A level already at that value is counted unchanged and nothing is re-published for it.

Read levels and history

GET /api/v3/catalogues/{catalogue}/inventory returns, per product, inventory (on hand), reserved (held by pending orders) and available — the difference, and the number that decides whether a customer may buy. Filter with sku[] or tracked_only=true.

GET /api/v3/catalogues/{catalogue}/products/by-sku/{sku}/movements is the audit trail: every event that moved the count, newest first, with kind (reserve, release, commit, adjust, sync), the signed quantity, what the figures became, and who or what caused it.

What an order does to stock

When an order is created — from a WhatsApp cart, your storefront, a flow, or the phone menus — units are reserved for every line we can match. If there was not enough to hold, the line is flagged stock_short, the order is flagged needs_attention, and the order is still recorded: a customer asked for it, and losing that would be worse. A line whose code is not in the catalogue is flagged unresolved for the same reason.

Moving the order to confirmed (or any later state) commits the hold — a real decrement under momo, a released hold under external. cancelled or refunded releases it. A pending order that is never answered releases on its own once the shop's reservation_ttl_hours (48 by default) has passed.

Set low_stock_threshold on the shop and you are told, once a day per product, when available reaches it.

Who may do what

An API key inherits the permissions of the person who issued it, never more. Reading needs communications.catalogue.view; writing needs communications.catalogue.manage. A key issued before that link was recorded carries no permission set to check: it keeps working on the endpoints that existed before this contract and is refused on the ones added by it. If a write starts answering 403, issue a new key from Settings → API credentials under a user who holds the permission.

Sending products into WhatsApp

/catalogues/send-product, /catalogues/send-product-list and /catalogues/send-catalogue put products into a chat. They take to for the recipient and an optional from for the sending identity, and they use the provider catalogue id and product_retailer_id, not our numeric ids.

Single product requires catalogue_id and product_retailer_id; optional body ≤ 1,024 and footer ≤ 60. Product list requires header_text ≤ 60, body ≤ 1,024 and 1–10 sections, each with a title ≤ 24 and product_items. Whole catalogue requires body and can name a thumbnail_product_retailer_id.

These call the provider directly and return data.message_id, a gateway id — not the ordinary REST message uid. No WhatsApp account configured returns 422; a provider refusal returns 502.

Orders

GET /api/v3/catalogues/orders lists orders from every platform, not only WhatsApp. platform says where each came from — whatsapp, storefront, ivr, manual — and customer_handle is whatever identifies the customer there: a WhatsApp id, a handle, an email, a typed phone number. customer_wa_id is the older name for it and has not held only WhatsApp ids for a long time.

Filter with status, platform and catalogue_id. updated_since is the cursor to poll from when you need to recover from a callback you missed; results then come newest-change-first.

PUT /api/v3/catalogues/orders/{order}/status moves an order through pending, confirmed, processing, shipped, delivered, cancelled, refunded. It records the change and moves the stock the order is holding (see above); it does not enforce a linear graph and setting refunded does not move money.

Read needs_attention before fulfilling. When it is true, at least one line is stock_short (we could not hold the whole quantity) or unresolved (the code is not in the catalogue), and a person has to decide what to do.

An order's lines and total are frozen when it is created. A later price change in the catalogue never re-prices an open order — the customer bought at the price they were shown. Keep fulfilment status separate from payment settlement: paid means money settled, not that a request was sent.

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.

This chapter documents communication webhooks — messages, orders, catalogue, groups. Automation subscription webhooks have their own signature, envelope and retry rules.

Webhooks are HTTP requests from Momo Business to a receiver you operate. They are not endpoints you call on /api/v3. Use them to learn about events the moment they happen, then reconcile important state through the corresponding read endpoints.

What we can send

GET /api/v3/webhooks/events lists every event, grouped, with a complete sample payload for each. The picker in Settings → Webhooks shows the same list, and the event enum in this API's delivery schema is generated from it — so a name you see in any of the three is one the platform actually sends.

order.received fires for an order from any platform — a WhatsApp cart, your storefront, a flow, the phone menus — and carries order.stock_policy, which tells you whether you are expected to decrement. order.status_changed fires from every path that changes a status: the dashboard, the staff app, the API, an agent. Neither existed as a reliable signal before; both are what a store integration lives on.

Register a receiver

From the dashboard: Settings → Webhooks, needs webhooks.manage. From the API:

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

Private and internal targets are refused; the hostname is checked again on every delivery attempt; redirects are not followed.

The response carries secret — the one time it is ever shown. Store it in your receiver's environment. POST /api/v3/webhooks/{webhook}/rotate-secret issues a new one the same way; the old one stops verifying immediately, so update the receiver first and rotate second. GET, PATCH and DELETE on /api/v3/webhooks/{webhook} do what they say; a key needs webhooks.view to read and webhooks.manage to change.

Verify a delivery

Every delivery carries five headers:

X-Signature:     <hex HMAC-SHA256 of the raw body>
X-Signature-V2:  sha256=<hex HMAC-SHA256 of "{X-Timestamp}.{X-Delivery-Id}.{raw body}">
X-Timestamp:     1757581442
X-Delivery-Id:   dlv_01j9qk3v8x2m7n4p5r6s
X-Event:         order.received
Content-Type:    application/json

X-Signature is unchanged from the first version of this contract, so a receiver written against it keeps working. Prefer X-Signature-V2: checking it gives you replay protection for free — refuse a timestamp more than five minutes old, and remember delivery ids you have already processed. X-Delivery-Id is the same across every retry of one delivery and different for a replay, so it is the right key to dedupe on.

Verify over the raw bytes, before parsing or re-serialising:

$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'] ?? '';

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($id)) { http_response_code(200); exit; }   // a retry you already handled

$event = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
enqueue($event);              // persist first, process later
markSeen($id);
http_response_code(200);

// Node
const crypto = require('crypto');
const ts = req.get('X-Timestamp'), id = req.get('X-Delivery-Id');
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.MOMO_WEBHOOK_SECRET)
  .update(`${ts}.${id}.${rawBody}`).digest('hex');
if (!crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(req.get('X-Signature-V2') || ''))) return res.sendStatus(401);

# Python
import hmac, hashlib
expected = 'sha256=' + hmac.new(SECRET.encode(), f"{ts}.{delivery_id}.".encode() + raw_body, hashlib.sha256).hexdigest()
if not hmac.compare_digest(expected, request.headers.get('X-Signature-V2', '')): abort(401)

Order payloads

{"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"}}

Read order.lines[].sku and quantity to decrement your own stock when stock_policy is external. needs_attention means a line is stock_short (we could not hold the whole quantity) or unresolved (the code is not in the catalogue) — a person has to look before it ships. priced_at records that the lines and total were frozen at creation; a later catalogue price change never re-prices an open order.

order.status_changed carries the same order object plus previous_status. order.cancelled is the same again, sent only on cancellation, for receivers that care about nothing else. Any stock the order was holding has already been released by the time you receive it.

The older top-level names — order_id, customer_wa_id, product_items, total_amount, total_currency — are still present in every order event for one release. Move to order.*; they are marked deprecated in the spec.

order.paid is unchanged: order_id, payment_id, method, amount_minor, currency, payer_msisdn, paid_at, conversation_id. It means money settled, not that a request was sent.

Catalogue payloads

sync.completed carries the same report as GET /api/v3/catalogues/{catalogue}/syncs/{sync} under sync, minus problems — that list can be two hundred rows, so read it from the endpoint when rejected or a platform's blocked count is non-zero. product.blocked fires once per product per platform that refused it, with the problem in words. stock.low fires once per product per day when available reaches the shop's low_stock_threshold.

Message and group payloads

Message events are flat: message_id, direction, sender, recipient, status, body, media_url, channel_type. Use the numeric message_id with the SMS/WhatsApp read endpoint for the full record. Group events carry a group summary; use its id to fetch current state.

Delivery, retries and the log

Every delivery is a record. GET /api/v3/webhooks/{webhook}/deliveries lists them newest first — what was sent, how many times, the last HTTP status and the first kilobyte of what your receiver said. Filter by status, event or since. The same log is under each endpoint in Settings → Webhooks, with per-endpoint counts for the last 24 hours.

Retries. A 5xx, a timeout or a connection failure is retried five times over about six hours: after 1 minute, 5, 30, 2 hours, 6 hours. A 4xx other than 408, 425 or 429 is treated as "understood and refused" and is not retried — retrying a 401 five times changes nothing.

Pausing. After fifty consecutive failures the endpoint is paused: deliveries are recorded as skipped rather than sent, the account is notified, and your other endpoints receive webhook.paused. Fix the receiver, then replay any failed delivery — POST /api/v3/webhooks/{webhook}/deliveries/{delivery}/replay, or the Replay button in the log — and the endpoint resumes. Setting is_active: true again does the same.

Answer 2xx quickly. Persist or enqueue the event, then acknowledge; keep downstream work outside the request. Delivery is at-least-once and ordering across events is not guaranteed, so make repeated status updates harmless and dedupe on X-Delivery-Id. When you need to recover from an outage on your side, GET /api/v3/catalogues/orders?updated_since= is the cursor to poll from.

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.

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 305 tools as 305 near-identical POST operations would validate perfectly and teach nobody anything. So what is documented under this tag is the transport — the 29 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, data, approvals, payments, automations, alerts, operations, studio, numbers, agents, tickets, kb, content, calls, routing, meetings, comments, posts, 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.