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.

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 a business phone identity belonging to the account; omitting it uses configured defaults. Use the provider phone-number identity shown by your connection, not a local database channel ID.

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

Contacts belong to a contact group. Obtain the group ID from the account's contact management interface or an authorized MCP contact-group tool. This REST family operates inside a known group; it does not include a group-list or group-create endpoint.

Compatibility routes

The group identifier may be a numeric ID or group UUID. Contact lookup accepts its public UID or numeric ID, but only within the requested group and account. Missing group/contact returns 404. The names search and all do not change their required HTTP method.

Create with explicit phone information

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

PHONE is required and limited to 64 characters; phone_number is an alias. If both are supplied, PHONE wins. Country code is optional, at most eight characters, and should be sent explicitly when you need split country/national fields. With the example above the stored national number is 712345678 and the country code is 255.

Normalization removes nondigits and a matching supplied country code, then removes a national trunk zero when a country code is present. It does not infer country_code merely because PHONE begins with +255; if no country_code is supplied, the digits remain in phone_number. This contact parser differs from the data-table phone field's regional normalization.

Name selection uses name or NAME, then joins FIRST_NAME and LAST_NAME, then falls back to the normalized phone. The normal name field is limited to 160 characters. is_subscribed defaults true at creation.

Every nonreserved request field is saved under custom_field_values. Reserved fields are PHONE, phone_number, country_code, name, NAME, FIRST_NAME, LAST_NAME, is_subscribed and _token. Send custom values at the top level, as in the example; wrapping them inside a custom_field_values input would store that wrapper as a custom key.

PATCH is replacement-like

This endpoint still requires PHONE or phone_number on an update. It recalculates name from the submitted payload and replaces the complete custom-field map. Omitted is_subscribed retains its previous value, but omitted name/custom fields do not follow that same rule.

To retain data, read the contact first, merge the changes in your application, and send the phone, desired name and all custom fields you intend to preserve. This differs from data-record PATCH, which merges only submitted keys.

Listing and campaign use

The contact list accepts search across name and national phone_number, with newest updated contacts first. Use page/limit pagination, default 20, maximum 100. The response contains stable UID, group_id/group_uid, name, country_code, phone_number, full_phone_number, subscription flag, custom fields and timestamps. Empty custom fields are serialized as {}.

Campaigns can use {{name}} and {{cf:order_ref}} from these records. The subscription flag records your data but is not automatically applied by the current campaign dispatch loop. Maintain your intended audience and blacklist deliberately, and avoid creating duplicate contact rows through untracked repeated POST requests.

The commerce API manages existing catalogues, their products and customer orders. Start by listing /api/v3/catalogues, then retain the local catalogue ID for resource operations and the distinct meta_catalogue_id for provider catalogue messages. Creating a shop and connecting it to Meta are account setup tasks outside this REST family.

Product identity and money

For these product fields, 12500 represents 125.00; do not submit a formatted amount or assume the data-table currency field uses the same scale. currency is a three-character code. The account wallet response is another distinct representation, so name money variables with their units in your integration.

{"retailer_id":"BAG-001","name":"Canvas bag","description":"Reusable canvas shopping bag","price":1250000,"currency":"TZS","image_url":"https://assets.example.com/products/bag.jpg","availability":"in stock","condition":"new","inventory":24,"visibility":"published"}

POST to /api/v3/catalogues/{catalogue}/products. Retailer ID and name are required, maximum 100 characters; description maximum 5,000; image URL required, maximum 2,048. Price and currency are required. Inventory and sale_price are optional nonnegative integers. Brand/category maximum 255; product_type maximum 750.

Availability values are in stock, out of stock, preorder, available for order, discontinued. Condition is new, refurbished, used; create visibility is staging or published. Product lists search name/retailer_id and can filter availability, sorted by name, default 25 rows.

Updates, batches and synchronization

PUT /catalogues/{catalogue}/products/{product} applies recognized submitted fields. Its editable fields differ from creation: retailer_id, product_type and visibility are not accepted update inputs. A duplicate retailer_id on creation returns 422.

POST /catalogues/{catalogue}/products/batch takes products, 1–3,000 entries. Each requires retailer_id, name, price, currency and image_url. It upserts local products by retailer_id and initiates publication through configured shop channels. Response imported counts processed entries, and syncing indicates whether the shop has channels. This response does not establish successful publication of every product at every provider.

Single product operations may synchronize a linked Meta product when credentials are available. A provider refusal on create/update can produce 502. An unconnected catalogue keeps products locally. Local deletion and remote synchronization are not an atomic distributed transaction; reconcile important inventory changes by reading current state.

Sending products into WhatsApp

The three send endpoints are /catalogues/send-product, /catalogues/send-product-list and /catalogues/send-catalogue. They use to for recipient and optional from for sending identity, unlike regular message sends.

Single product requires provider catalogue_id and product_retailer_id; optional body maximum 1,024 and footer 60. Product list requires header_text≤60, body≤1,024 and 1–10 sections; each section needs title≤24 and product_items containing product_retailer_id. Whole catalogue requires body and can include thumbnail_product_retailer_id.

These operations call the provider directly and return data.message_id, its gateway ID. They do not create the ordinary REST message UID through the unified send path; do not look for that ID as a local message record. Missing WhatsApp configuration returns 422 and provider refusal returns 502.

Orders and fulfilment

List /catalogues/orders with optional status, read /catalogues/orders/{order}, and PUT {order}/status with a required status. Values are pending, confirmed, processing, shipped, delivered, cancelled and refunded. The current status method accepts any enum value and records the change; it does not enforce a linear transition graph or trigger a payment refund simply because you set refunded.

Orders expose product_items, customer details, total_amount/total_currency and originating provider message ID. Stored total_amount is scaled by 100; incoming cart item_price values are major units before total calculation. Keep fulfilment status distinct from payment settlement, and use order.received/order.paid callbacks only where configured. Poll order state to recover missed callbacks.

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. Automation subscription webhooks have their own signature, event 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 message, group and order events, then reconcile important state through the corresponding read endpoints.

Configure the receiver

Open Settings → Webhooks. Viewing needs webhooks.view; creating, editing or deleting needs webhooks.manage. Supply a public HTTP(S) URL and the events you want. Private/internal targets are rejected, the hostname is checked again at delivery, and redirects are not followed. Prefer an HTTPS endpoint that responds directly at its configured URL.

There is no customer /api/v3/webhooks management endpoint. The event picker and the dispatcher are also not identical: some emitted event names are not currently offered by the picker. Confirm the stored subscription with your administrator when using events beyond those shown in the interface.

Actual signature contract

The messaging/group/order dispatcher sends JSON with this header:

X-Signature: HEX_HMAC_SHA256
Content-Type: application/json

The signature is a lowercase hexadecimal HMAC-SHA256 of the serialized JSON payload, using the endpoint's signing secret. It has no sha256= prefix. This dispatcher does not set X-Webhook-Signature or X-Event. Use the event field in the body.

Verify against the raw body before parsing or changing whitespace:

$raw = file_get_contents('php://input');
$secret = getenv('MOMO_WEBHOOK_SECRET');
$signature = $_SERVER['HTTP_X_SIGNATURE'] ?? '';
if (!is_string($raw) || !is_string($secret) || $secret === '') {
    http_response_code(503);
    exit;
}
$expected = hash_hmac('sha256', $raw, $secret);
if (!hash_equals($expected, $signature)) {
    http_response_code(401);
    exit;
}
$event = json_decode($raw, true, 512, JSON_THROW_ON_ERROR);
// Persist or enqueue the validated event, then acknowledge it.
http_response_code(200);

Provision the matching endpoint secret in your receiver environment. Current limitation: the platform generates this secret server-side, but the customer webhook screen and REST API do not currently expose secret retrieval or rotation. Do not assume you can copy it from the API-key screen. Arrange provisioning with the administrator responsible for the endpoint before enabling signature enforcement. An API key is not the webhook secret.

Message payloads are flat

{"event":"message.delivered","message_id":101,"direction":"outbound","sender":"MyBrand","recipient":"255712345678","status":"delivered","body":"Your order is ready.","media_url":null,"channel_type":"sms","timestamp":"2030-10-12T06:01:00+00:00"}

The message callback contains event, message_id, direction, sender, recipient, status, body, media_url, channel_type and timestamp. It does not wrap a full Message object in data; it does not include public uid, gateway ID or error_message. Use numeric message_id with the SMS/WhatsApp read endpoint for the complete current record.

Emitted message names include message.received, message.sent, message.delivered, message.read, message.failed, message.echoed and message.updated. A failed event may require a follow-up read to retrieve the error. Provider echoes and edits are not new inbound customer requests merely because they carry body text.

Orders and groups

order.received includes order_id, customer_wa_id, customer_name, product_items, total_amount, total_currency, customer_note, conversation_id and created_at. order.paid includes order_id, payment_id, method, amount_minor, currency, payer_msisdn, paid_at and conversation_id. Both also carry event and timestamp.

Group callbacks contain a group summary plus event-specific details. Events cover created, create_failed, updated, deleted, suspended, suspension_cleared, participant_joined/left/removed, join_requested, join_request_revoked and invite_sent. Use IDs in the payload to fetch current group state. Campaign completion/failure labels in the picker are not a delivery guarantee: the campaign execution path currently requires polling for those outcomes.

Delivery reliability

The current dispatcher makes one attempt with a 10-second timeout. It does not retry non-2xx responses, follow redirects or provide a durable customer replay log. Respond quickly after persisting the event, and keep costly downstream processing outside the request.

Do not assume exactly-once delivery or strict ordering. Make repeated status updates harmless, retain your own event audit, and poll important message/order/group IDs to recover from missing callbacks. Route incoming events by event family and ignore unknown fields so compatible additions do not break your receiver. This contract is for the customer messaging dispatcher; other voice/provider webhook integrations can have different headers and payloads.

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.

Operate within a known contact group, using its numeric ID or UUID. Read/search and list are POST routes. Contact lookup accepts UID or numeric ID.

PHONE or phone_number is required on both create and PATCH. Supply country_code explicitly when split normalization is needed. Updates recalculate the name and replace all custom fields; only omitted is_subscribed retains its previous value. The subscription flag is stored data and is not automatically applied by the current campaign dispatch loop.

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 282 tools as 282 near-identical POST operations would validate perfectly and teach nobody anything. So what is documented under this tag is the transport — the 28 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, 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.