{ "openapi": "3.1.0", "info": { "title": "v3 Messaging API", "version": "3.1.0", "description": "Tenant-facing v3 communications API for SMS, WhatsApp, contacts, webhooks, profile, and balance.\n\n## Quickstart\n\n1. **Get a token** \u2014 Dashboard \u2192 Settings \u2192 API Keys \u2192 Create token (copy it; we only show it once).\n2. **Verify it works** \u2014 `curl https://business.momo.tz/api/v3/me -H 'Authorization: Bearer YOUR_TOKEN'`\n3. **Send your first message** \u2014 see the SMS or WhatsApp send examples below.\n4. **Subscribe to webhooks** \u2014 point us at a public URL to get real-time delivery, reply, and order events.\n\n## Authentication\n\nEvery request needs `Authorization: Bearer `. See the **Authentication** tag for the full walkthrough including token rotation and rate-limit handling.\n\n## Response envelope\n\n- **Success:** `{ \"status\": \"success\", \"data\": ... }`\n- **Error:** `{ \"status\": \"error\", \"message\": \"...\", \"errors\": { ... } }` \u2014 validation errors include per-field messages under `errors`.\n\n## Rate limits\n\n| Family | Per-tenant cap |\n|---|---|\n| SMS / WhatsApp send | 60 req/min |\n| Read endpoints | 120 req/min |\n| Campaign creation | 10 req/min |\n\nEvery response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`. `429` responses include `Retry-After` (seconds).\n\n## Pagination\n\nList endpoints accept `page` (default 1) and `per_page` (default 25, max 100). The response wraps results in `data.items[]` and `data.pagination` with `current_page`, `per_page`, `total`, `last_page`.\n\n## HTTP status conventions\n\n| Code | Meaning |\n|------|---------|\n| `200 OK` | Read or update succeeded. |\n| `201 Created` | New resource created (e.g. SMS queued, contact stored). |\n| `400` | Malformed request (rare \u2014 most validation surfaces as 422). |\n| `401` | Missing / invalid / expired token. |\n| `403` | Token valid but action not permitted on this resource. |\n| `404` | Resource does not exist or doesn't belong to your tenant. |\n| `422` | Validation failed \u2014 see `errors` for field-level messages. |\n| `429` | Rate limit exceeded \u2014 back off using `Retry-After`. |\n| `5xx` | Server error \u2014 safe to retry idempotent calls (`GET`, `PUT`); for `POST`, dedupe on your side using `client_request_id` if supported. |\n\n## What's new in 3.1\n\n- WhatsApp examples for **location**, **vCard contacts**, **CTA-URL**, **Flow**, **product**, **product_list**, **catalog_message**, **interactive with image header**, **template with components**, and **threaded replies**.\n- SMS examples for **bulk recipients**, **scheduled sends**, **multi-channel routing**.\n- Contacts examples for **custom fields**, **opt-out**, **pagination**, **search filters**.\n- New **Webhooks** reference \u2014 payload shape per event + HMAC signature verification snippets in PHP and Node." }, "servers": [ { "url": "https://business.momo.tz" } ], "security": [ { "BearerToken": [] } ], "tags": [ { "name": "Authentication", "description": "How to authenticate with the v3 API: token creation, header format, rate limits, and a probe call to confirm your token works. Read this first." }, { "name": "SMS", "description": "Send single or bulk SMS messages, list message history with pagination, view individual message details, and create campaigns for mass delivery." }, { "name": "WhatsApp", "description": "Send WhatsApp messages (text, image, video, audio, document, sticker, template, interactive, reaction) and retrieve message history. Supports all WhatsApp Business API message types." }, { "name": "Contacts", "description": "Create, read, update, and delete contacts within contact groups. Contacts are organized by group ID for targeted messaging and campaign management." }, { "name": "Profile & Balance", "description": "Retrieve tenant profile information and current wallet balance. Use these endpoints to verify your identity and check available credits before sending messages." }, { "name": "Webhooks", "description": "Receive real-time updates when your customers reply, when delivery status changes, or when an order is placed against your WhatsApp catalogue. Webhooks are HTTP POSTs from our servers to a URL you control, signed with HMAC-SHA256 so you can verify authenticity. Subscribe under Settings > Webhooks in your dashboard or via the management endpoints below." } ], "components": { "securitySchemes": { "BearerToken": { "type": "http", "scheme": "bearer", "bearerFormat": "tenant_api_token", "description": "Use Authorization: Bearer ." } }, "schemas": { "LegacyErrorEnvelope": { "type": "object", "required": [ "status", "message" ], "description": "Error response envelope for validation and server errors.", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Always \"error\" for failure responses." }, "message": { "type": "string", "description": "Human-readable error message." }, "errors": { "type": "object", "description": "Optional field-level validation errors; keys are field names, values are arrays of messages.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } } }, "RateLimitError": { "type": "object", "required": [ "status", "message" ], "description": "Returned when API rate limit is exceeded. Retry after the X-RateLimit-Reset timestamp.", "properties": { "status": { "type": "string", "enum": [ "error" ], "description": "Always \"error\" for rate limit responses." }, "message": { "type": "string", "example": "Too many requests. Please retry after 60 seconds.", "description": "Human-readable rate limit message." }, "retry_after": { "type": "integer", "example": 60, "description": "Number of seconds to wait before retrying." } } }, "Pagination": { "type": "object", "required": [ "current_page", "per_page", "last_page", "total", "has_more_pages" ], "description": "Cursor-less pagination metadata for list endpoints.", "properties": { "current_page": { "type": "integer", "description": "1-based current page index." }, "per_page": { "type": "integer", "description": "Number of items per page." }, "last_page": { "type": "integer", "description": "1-based index of the last page." }, "total": { "type": "integer", "description": "Total number of items across all pages." }, "has_more_pages": { "type": "boolean", "description": "True if more pages exist after the current page." } } }, "Message": { "type": "object", "required": [ "id", "uid", "direction", "channel_type", "recipient", "body", "status" ], "description": "SMS or WhatsApp message record with delivery and metadata fields.", "properties": { "id": { "type": "integer", "description": "Internal numeric id." }, "uid": { "type": "string", "description": "Public unique identifier (e.g. msg_01JXYZSMS01)." }, "direction": { "type": "string", "description": "inbound or outbound." }, "channel_type": { "type": "string", "enum": [ "sms", "whatsapp" ], "description": "Channel: sms or whatsapp." }, "tenant_channel_id": { "type": "integer", "description": "The account channel selected automatically by the outbound routing policy." }, "channel_code": { "type": [ "string", "null" ], "description": "Resolved channel code returned for observability; it is not caller-selectable." }, "sender": { "type": [ "string", "null" ], "description": "Sender id or phone (outbound); null for inbound." }, "recipient": { "type": "string", "description": "Recipient phone number (E.164 or national)." }, "body": { "type": "string", "description": "Message text content." }, "status": { "type": "string", "description": "Delivery status (e.g. queued, sent, delivered, failed)." }, "media_url": { "type": [ "string", "null" ] }, "media_type": { "type": [ "string", "null" ] }, "gateway_message_id": { "type": [ "string", "null" ] }, "error_message": { "type": [ "string", "null" ] }, "metadata": { "type": [ "object", "null" ], "additionalProperties": true }, "template_params": { "type": [ "object", "null" ], "additionalProperties": true }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] }, "sent_at": { "type": [ "string", "null" ] }, "delivered_at": { "type": [ "string", "null" ] }, "read_at": { "type": [ "string", "null" ] } } }, "Campaign": { "type": "object", "required": [ "id", "uid", "name", "status", "channel_type", "message" ], "description": "SMS campaign with recipient counts and status.", "properties": { "id": { "type": "integer", "description": "Internal numeric id." }, "uid": { "type": "string", "description": "Public unique identifier." }, "name": { "type": "string", "description": "Campaign name." }, "status": { "type": "string", "description": "Campaign status (e.g. scheduled, running, completed)." }, "channel_type": { "type": "string", "enum": [ "sms" ], "description": "Channel type; currently only sms." }, "tenant_channel_id": { "type": "integer", "description": "The account channel selected automatically when the campaign was created." }, "channel_code": { "type": [ "string", "null" ], "description": "Resolved channel code returned for observability; it is not caller-selectable." }, "message": { "type": "string", "description": "Campaign message text." }, "sender": { "type": [ "string", "null" ] }, "scheduled_at": { "type": [ "string", "null" ] }, "total_recipients": { "type": "integer" }, "sent_count": { "type": "integer" }, "failed_count": { "type": "integer" }, "contact_group": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "name": { "type": "string" } }, "additionalProperties": false }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } }, "Contact": { "type": "object", "required": [ "id", "uid", "group_id", "group_uid", "name", "country_code", "phone_number", "full_phone_number", "is_subscribed" ], "description": "Contact record within a group, with phone and optional custom fields.", "properties": { "id": { "type": "integer", "description": "Internal numeric id." }, "uid": { "type": "string", "description": "Public unique identifier." }, "group_id": { "type": "integer", "description": "Contact group internal id." }, "group_uid": { "type": "string", "description": "Contact group public uid." }, "name": { "type": "string", "description": "Contact display name." }, "country_code": { "type": "string", "description": "Country code (e.g. 255)." }, "phone_number": { "type": "string", "description": "National number without country code." }, "full_phone_number": { "type": "string", "description": "E.164 or full number for sending." }, "is_subscribed": { "type": "boolean", "description": "Whether the contact is subscribed to receive messages." }, "custom_field_values": { "type": "object", "description": "Key-value custom attributes.", "additionalProperties": true }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } } } }, "paths": { "/api/v3/_auth": { "get": { "tags": [ "Authentication" ], "operationId": "v3AuthOverview", "summary": "How authentication works (token-based)", "description": "Every v3 API request must include an `Authorization: Bearer ` header. Tokens are tenant-scoped \u2014 a token can only act on resources belonging to the tenant that created it.\n\n## 1. Create a token\n\nLog in to your dashboard, open **Settings \u2192 API Keys**, click **Create token**, and copy the token value (shown only once). Tokens have an optional expiry; if omitted, they don't expire.\n\n## 2. Make your first request\n\nUse the token in the `Authorization` header. Verify it works by hitting `GET /api/v3/me`:\n\n```bash\ncurl https://business.momo.tz/api/v3/me \\\n -H 'Authorization: Bearer YOUR_TOKEN'\n```\n\n## 3. Token scopes\n\nAll v3 tokens have full read/write access on the tenant's resources today. Per-endpoint scoping is on the roadmap; in the meantime, treat tokens as full credentials and rotate them if leaked.\n\n## 4. Rate limiting\n\n- SMS / WhatsApp send: **60 req/min** per tenant\n- Read endpoints: **120 req/min**\n- Campaign creation: **10 req/min**\n\nResponses include `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset` headers. A `429` means you've hit the cap \u2014 back off and retry after the reset.\n\n## 5. Error handling\n\nAll errors follow the envelope `{ \"status\": \"error\", \"message\": \"...\", \"errors\": { ... } }`. Validation errors come back as `422` with `errors` keyed by field name.", "responses": { "200": { "description": "Probe endpoint \u2014 responds with the calling tenant's details when the token is valid.", "content": { "application/json": { "examples": { "default": { "summary": "Successful probe", "value": { "status": "success", "data": { "id": 12, "uid": "tnt_01JXYZTENANT", "name": "Acme Communications", "email": "ops@acme.example.com", "default_currency": "TZS" } } } } } } }, "401": { "description": "Token missing, invalid, or expired.", "content": { "application/json": { "examples": { "default": { "value": { "status": "error", "message": "Invalid API token." } } } } } } } } }, "/api/v3/sms/send": { "post": { "tags": [ "SMS" ], "operationId": "v3SmsSend", "summary": "Send an SMS", "description": "Queues one or many SMS messages using legacy-compatible fields.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string", "description": "One or more recipients, comma-separated (e.g. 255700111222 or 255700111222,255700111223)." }, "recipients": { "type": "array", "items": { "type": "string" }, "description": "Alternative to recipient: array of phone numbers." }, "sender_id": { "type": "string", "description": "Optional approved sender ID, tenant-owned SMS-capable number, or active short code. Unknown or ambiguous identities are rejected." }, "type": { "type": "string", "description": "Message type (e.g. plain)." }, "message": { "type": "string", "description": "SMS body text." }, "tenant_channel_id": { "type": "integer", "deprecated": true, "description": "Deprecated compatibility input. Ignored; routing is resolved automatically from sender_id and account/system defaults." }, "schedule_time": { "type": "string", "description": "Optional ISO datetime for scheduled send." } }, "required": [ "recipient", "message" ] }, "examples": { "default": { "summary": "Single recipient (most common)", "value": { "recipient": "255700111222", "sender_id": "MyBrand", "message": "Hello from Momo Business \u2014 your verification code is 4821." } }, "multi_recipient_csv": { "summary": "Multiple recipients (comma-separated)", "value": { "recipient": "255700111222,255700111223,255700111224", "sender_id": "MyBrand", "message": "Branch closed early today \u2014 back tomorrow at 8am." } }, "multi_recipient_array": { "summary": "Multiple recipients (array form)", "value": { "recipients": [ "255700111222", "255700111223", "255700111224" ], "sender_id": "MyBrand", "message": "Reminder: payment due tomorrow." } }, "scheduled": { "summary": "Scheduled send (queue for later)", "value": { "recipient": "255700111222", "sender_id": "MyBrand", "message": "Good morning! Your appointment is at 10am.", "schedule_time": "2026-04-20T07:00:00Z" } }, "long_unicode": { "summary": "Long Unicode message (will be split into multiple SMS segments)", "value": { "recipient": "255700111222", "sender_id": "MyBrand", "message": "Mteja mpendwa, asante kwa kutembelea duka letu. Tunakushukuru kwa upendeleo wako wa kuendelea kununua bidhaa zetu. Tafadhali piga 0700123456 kwa msaada zaidi." } } } } } }, "responses": { "201": { "description": "Messages queued. Each recipient yields one Message row; check `data.messages[].status` for delivery progression.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "messages": [ { "id": 101, "uid": "msg_01JXYZSMS01", "direction": "outbound", "channel_type": "sms", "sender": "MyBrand", "recipient": "255700111222", "body": "Hello from API v3", "status": "queued" } ] } } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "At least one recipient is required.", "errors": { "recipient": [ "Provide recipient or recipients." ] } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Invalid API token." } } } } } } } } }, "/api/v3/sms/campaign": { "post": { "tags": [ "SMS" ], "operationId": "v3SmsCampaignCreate", "summary": "Create an SMS campaign", "description": "Creates one campaign per resolved contact list identifier and queues campaign processing.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_list_id": { "type": "string" }, "message": { "type": "string" }, "sender_id": { "type": "string", "description": "Optional approved sender ID, tenant-owned SMS-capable number, or active short code." }, "tenant_channel_id": { "type": "integer", "deprecated": true, "description": "Deprecated compatibility input. Ignored; routing is resolved automatically from sender_id and account/system defaults." }, "schedule_time": { "type": "string" }, "name": { "type": "string" } }, "required": [ "contact_list_id", "message" ] }, "examples": { "default": { "value": { "contact_list_id": "grp_01JXYZABC", "message": "Campaign message", "sender_id": "Brand" } } } } } }, "responses": { "201": { "description": "Campaigns created.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "campaigns" ], "properties": { "campaigns": { "type": "array", "items": { "$ref": "#/components/schemas/Campaign" } } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "campaigns": [ { "id": 15, "uid": "cmp_01JXYZ001", "name": "API Campaign - VIP List", "status": "draft", "channel_type": "sms", "message": "Campaign message" } ] } } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "contact_list_id must contain at least one group id." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Invalid API token." } } } } } } } } }, "/api/v3/sms": { "get": { "tags": [ "SMS" ], "operationId": "v3SmsList", "summary": "List SMS messages", "description": "Returns tenant-scoped SMS message logs with pagination.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "SMS collection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "items": [ { "id": 101, "uid": "msg_01JXYZSMS01", "direction": "outbound", "channel_type": "sms", "recipient": "255700111222", "body": "Hello from API v3", "status": "queued" } ], "pagination": { "current_page": 1, "per_page": 20, "last_page": 1, "total": 1, "has_more_pages": false } } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Missing bearer token." } } } } } } } } }, "/api/v3/sms/{uid}": { "get": { "tags": [ "SMS" ], "operationId": "v3SmsShow", "summary": "Get an SMS message", "description": "Fetches one SMS message by public uid with numeric id fallback.", "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Single SMS message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Message" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 101, "uid": "msg_01JXYZSMS01", "direction": "outbound", "channel_type": "sms", "recipient": "255700111222", "body": "Hello from API v3", "status": "delivered" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Message not found." } } } } } } } } }, "/api/v3/campaign/{uid}/view": { "get": { "tags": [ "SMS" ], "operationId": "v3CampaignShow", "summary": "View one campaign", "description": "Retrieves one SMS campaign by uid.", "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Campaign details.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Campaign" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 15, "uid": "cmp_01JXYZ001", "name": "API Campaign - VIP List", "status": "running", "channel_type": "sms", "message": "Campaign message" } } } } } } }, "404": { "description": "Campaign not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Campaign not found." } } } } } } } } }, "/api/v3/whatsapp/send": { "post": { "tags": [ "WhatsApp" ], "operationId": "v3WhatsAppSend", "summary": "Send a WhatsApp message", "description": "Unified send supporting text, media, template, interactive, and reaction payloads.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "recipient": { "type": "string" }, "recipients": { "type": "array", "items": { "type": "string" } }, "message": { "type": "string" }, "body": { "type": "string" }, "message_type": { "type": "string", "enum": [ "text", "image", "video", "audio", "document", "sticker", "template", "interactive", "reaction" ] }, "type": { "type": "string" }, "media_url": { "type": "string" }, "media_type": { "type": "string" }, "template": { "type": "object", "additionalProperties": true }, "interactive": { "type": "object", "additionalProperties": true }, "reaction": { "type": "object", "additionalProperties": true }, "in_reply_to_gateway_id": { "type": "string" }, "tenant_channel_id": { "type": "integer", "deprecated": true, "description": "Deprecated compatibility input. Ignored; routing is resolved automatically from the endpoint type, sending identity, and account/system defaults." } }, "required": [ "recipient" ] }, "examples": { "default": { "summary": "Text message", "value": { "recipient": "255700111222", "message": "Hello from the API" } }, "text": { "summary": "Text", "value": { "recipient": "255700111222", "message_type": "text", "message": "Hello, this is a plain text message." } }, "image": { "summary": "Image", "value": { "recipient": "255700111222", "message_type": "image", "media_url": "https://example.com/image.png", "message": "Optional caption" } }, "video": { "summary": "Video", "value": { "recipient": "255700111222", "message_type": "video", "media_url": "https://example.com/video.mp4", "message": "Optional caption" } }, "audio": { "summary": "Audio", "value": { "recipient": "255700111222", "message_type": "audio", "media_url": "https://example.com/audio.ogg" } }, "document": { "summary": "Document", "value": { "recipient": "255700111222", "message_type": "document", "media_url": "https://example.com/file.pdf", "message": "Optional filename or caption" } }, "sticker": { "summary": "Sticker", "value": { "recipient": "255700111222", "message_type": "sticker", "media_url": "https://example.com/sticker.webp" } }, "template": { "summary": "Template", "value": { "recipient": "255700111222", "message_type": "template", "template": { "name": "welcome_template", "language": "en", "components": [] } } }, "interactive_button": { "summary": "Interactive (buttons)", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "button", "body": { "text": "Choose one" }, "action": { "buttons": [ { "id": "yes", "title": "Yes" }, { "id": "no", "title": "No" } ] } } } }, "interactive_list": { "summary": "Interactive (list)", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "list", "body": { "text": "Select an option" }, "action": { "button": "View options", "sections": [ { "title": "Section 1", "rows": [ { "id": "opt_1", "title": "Option 1", "description": "First choice" }, { "id": "opt_2", "title": "Option 2", "description": "Second choice" } ] } ] } } } }, "reaction": { "summary": "Reaction", "value": { "recipient": "255700111222", "message_type": "reaction", "reaction": { "emoji": "\ud83d\udc4d", "message_id": "wamid.xxxxx" } } }, "location": { "summary": "Location pin", "value": { "recipient": "255700111222", "message_type": "location", "location": { "latitude": -6.7924, "longitude": 39.2083, "name": "Momo Telecom HQ", "address": "Dar es Salaam, Tanzania" } } }, "contacts_vcard": { "summary": "Contact card (vCard)", "value": { "recipient": "255700111222", "message_type": "contacts", "contacts": [ { "name": { "formatted_name": "Asha Mwita", "first_name": "Asha", "last_name": "Mwita" }, "phones": [ { "phone": "+255700123456", "type": "WORK", "wa_id": "255700123456" } ], "emails": [ { "email": "asha@example.com", "type": "WORK" } ], "org": { "company": "Momo Telecom", "title": "Account Manager" } } ] } }, "interactive_cta_url": { "summary": "Interactive \u2014 call-to-action URL button", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "cta_url", "header": { "type": "text", "text": "Track your order" }, "body": { "text": "Your order #4521 has shipped. Tap below to track delivery in real time." }, "footer": { "text": "Powered by Momo Business" }, "action": { "name": "cta_url", "parameters": { "display_text": "Track order", "url": "https://acme.example.com/orders/4521" } } } } }, "interactive_flow": { "summary": "Interactive \u2014 WhatsApp Flow", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "flow", "header": { "type": "text", "text": "Book an appointment" }, "body": { "text": "Pick a time slot that works for you." }, "footer": { "text": "Takes 60 seconds" }, "action": { "name": "flow", "parameters": { "flow_message_version": "3", "flow_token": "FLOW_TOKEN_FROM_BACKEND", "flow_id": "1234567890123456", "flow_cta": "Book now", "flow_action": "navigate", "flow_action_payload": { "screen": "APPOINTMENT_SCREEN" } } } } } }, "interactive_image_header": { "summary": "Interactive buttons with image header", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "button", "header": { "type": "image", "image": { "link": "https://cdn.example.com/promo.jpg" } }, "body": { "text": "Limited-time offer \u2014 30% off today only." }, "action": { "buttons": [ { "type": "reply", "reply": { "id": "shop_now", "title": "Shop now" } }, { "type": "reply", "reply": { "id": "remind_later", "title": "Remind me later" } } ] } } } }, "product_single": { "summary": "Product (single item from a catalogue)", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "product", "body": { "text": "Check out this laptop." }, "action": { "catalog_id": "26191517010530753", "product_retailer_id": "SKU-LAPTOP-X1" } } } }, "product_list": { "summary": "Product list (up to 30 items, 10 sections)", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "product_list", "header": { "type": "text", "text": "Top picks" }, "body": { "text": "Tap any item to see details and add to cart." }, "footer": { "text": "Free delivery on orders over TZS 50,000" }, "action": { "catalog_id": "26191517010530753", "sections": [ { "title": "Laptops", "product_items": [ { "product_retailer_id": "SKU-LAPTOP-X1" }, { "product_retailer_id": "SKU-LAPTOP-AIR" } ] }, { "title": "Phones", "product_items": [ { "product_retailer_id": "SKU-PHONE-15" } ] } ] } } } }, "catalog_message": { "summary": "Full catalogue (storefront entry point)", "value": { "recipient": "255700111222", "message_type": "interactive", "interactive": { "type": "catalog_message", "body": { "text": "Browse our entire catalogue." }, "action": { "name": "catalog_message", "parameters": { "thumbnail_product_retailer_id": "SKU-LAPTOP-X1" } } } } }, "template_with_components": { "summary": "Template with header image + body params + URL button", "value": { "recipient": "255700111222", "message_type": "template", "template": { "name": "order_shipped", "language": "en_US", "components": [ { "type": "header", "parameters": [ { "type": "image", "image": { "link": "https://cdn.example.com/box.jpg" } } ] }, { "type": "body", "parameters": [ { "type": "text", "text": "Asha" }, { "type": "text", "text": "4521" }, { "type": "text", "text": "Tomorrow 9\u201311am" } ] }, { "type": "button", "sub_type": "url", "index": "0", "parameters": [ { "type": "text", "text": "4521" } ] } ] } } }, "reply_in_thread": { "summary": "Reply that quotes a previous message", "value": { "recipient": "255700111222", "message_type": "text", "message": "Got it \u2014 see you tomorrow!", "in_reply_to_gateway_id": "wamid.HBgMMjU1NzAwMTExMjIyFQIAERgSREYx..." } } } } } }, "responses": { "201": { "description": "Messages queued.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "messages": [ { "id": 300, "uid": "msg_01JXYZWA01", "direction": "outbound", "channel_type": "whatsapp", "recipient": "255700111222", "body": "Interactive message", "status": "queued", "metadata": { "interactive": { "type": "button" } } } ] } } } } } } }, "422": { "description": "Validation or payload combination error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Reaction cannot be combined with text, media, template, or interactive payload." } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Invalid API token." } } } } } } } } }, "/api/v3/whatsapp": { "get": { "tags": [ "WhatsApp" ], "operationId": "v3WhatsAppList", "summary": "List WhatsApp messages", "description": "Returns tenant-scoped WhatsApp message logs with pagination.", "parameters": [ { "name": "status", "in": "query", "schema": { "type": "string" } }, { "name": "direction", "in": "query", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "schema": { "type": "integer" } }, { "name": "per_page", "in": "query", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "WhatsApp collection.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Message" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "items": [ { "id": 300, "uid": "msg_01JXYZWA01", "direction": "outbound", "channel_type": "whatsapp", "recipient": "255700111222", "body": "Interactive message", "status": "queued" } ], "pagination": { "current_page": 1, "per_page": 20, "last_page": 1, "total": 1, "has_more_pages": false } } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Missing bearer token." } } } } } } } } }, "/api/v3/whatsapp/{uid}": { "get": { "tags": [ "WhatsApp" ], "operationId": "v3WhatsAppShow", "summary": "Get a WhatsApp message", "description": "Fetches one WhatsApp message by public uid.", "parameters": [ { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Single WhatsApp message.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Message" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 300, "uid": "msg_01JXYZWA01", "direction": "outbound", "channel_type": "whatsapp", "recipient": "255700111222", "body": "Interactive message", "status": "delivered" } } } } } } }, "404": { "description": "Message not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Message not found." } } } } } } } } }, "/api/v3/contacts/{group_id}/store": { "post": { "tags": [ "Contacts" ], "operationId": "v3ContactsStore", "summary": "Create a contact", "description": "Stores one contact in a group using legacy fields and custom dynamic attributes.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "PHONE": { "type": "string" }, "country_code": { "type": "string" }, "name": { "type": "string" }, "FIRST_NAME": { "type": "string" }, "LAST_NAME": { "type": "string" }, "is_subscribed": { "type": "boolean" } }, "required": [ "PHONE" ], "additionalProperties": true }, "examples": { "default": { "summary": "Minimal \u2014 only the phone number is required", "value": { "PHONE": "255700333444" } }, "with_name": { "summary": "With name + structured first/last name", "value": { "PHONE": "255700333444", "name": "Asha Mwita", "FIRST_NAME": "Asha", "LAST_NAME": "Mwita" } }, "with_country_code": { "summary": "Local phone format + explicit country code", "value": { "PHONE": "0700333444", "country_code": "TZ", "name": "Asha Mwita" } }, "with_custom_fields": { "summary": "Custom merge fields (any keys you don't recognise become custom fields)", "value": { "PHONE": "255700333444", "FIRST_NAME": "Asha", "LAST_NAME": "Mwita", "CITY": "Dar es Salaam", "ACCOUNT_NUMBER": "AC-2204", "PLAN": "Pro", "RENEWAL_DATE": "2026-05-01" } }, "opted_out": { "summary": "Mark contact as opted-out (won't receive campaigns)", "value": { "PHONE": "255700333444", "name": "Asha Mwita", "is_subscribed": false } } } } } }, "responses": { "201": { "description": "Contact created. Phone numbers are normalised to E.164 (international) format and de-duplicated within the group \u2014 re-posting the same PHONE returns the existing row.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Contact" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 66, "uid": "ctc_01JXYZ001", "group_id": 8, "group_uid": "grp_01JXYZABC", "name": "John Doe", "country_code": "255", "phone_number": "700333444", "full_phone_number": "255700333444", "is_subscribed": true, "custom_field_values": { "CITY": "Dar es Salaam" } } } } } } } }, "404": { "description": "Group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Contact group not found." } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Validation failed.", "errors": { "PHONE": [ "The PHONE field is required." ] } } } } } } } } } }, "/api/v3/contacts/{group_id}/search/{uid}": { "post": { "tags": [ "Contacts" ], "operationId": "v3ContactsShow", "summary": "Find a contact", "description": "Finds a single contact in a group by public uid.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Single contact.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Contact" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 66, "uid": "ctc_01JXYZ001", "group_id": 8, "group_uid": "grp_01JXYZABC", "name": "John Doe", "country_code": "255", "phone_number": "700333444", "full_phone_number": "255700333444", "is_subscribed": true, "custom_field_values": { "CITY": "Dar es Salaam" } } } } } } } }, "404": { "description": "Contact not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Contact not found." } } } } } } } } }, "/api/v3/contacts/{group_id}/update/{uid}": { "patch": { "tags": [ "Contacts" ], "operationId": "v3ContactsUpdate", "summary": "Update a contact", "description": "Updates a contact record in a group with the same payload conventions as create.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "PHONE": { "type": "string" }, "country_code": { "type": "string" }, "name": { "type": "string" }, "is_subscribed": { "type": "boolean" } }, "required": [ "PHONE" ], "additionalProperties": true }, "examples": { "default": { "value": { "PHONE": "255700333444", "name": "John Updated" } } } } } }, "responses": { "200": { "description": "Contact updated.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "$ref": "#/components/schemas/Contact" } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 66, "uid": "ctc_01JXYZ001", "group_id": 8, "group_uid": "grp_01JXYZABC", "name": "John Updated", "country_code": "255", "phone_number": "700333444", "full_phone_number": "255700333444", "is_subscribed": true, "custom_field_values": [] } } } } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Validation failed.", "errors": { "PHONE": [ "The PHONE field is required." ] } } } } } } }, "404": { "description": "Contact or group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Contact not found." } } } } } } } } }, "/api/v3/contacts/{group_id}/delete/{uid}": { "delete": { "tags": [ "Contacts" ], "operationId": "v3ContactsDelete", "summary": "Delete a contact", "description": "Deletes one contact by uid within a contact group.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } }, { "name": "uid", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Contact deleted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "deleted", "uid" ], "properties": { "deleted": { "type": "boolean" }, "uid": { "type": "string" } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "deleted": true, "uid": "ctc_01JXYZ001" } } } } } } }, "404": { "description": "Contact or group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Contact not found." } } } } } } } } }, "/api/v3/contacts/{group_id}/all": { "post": { "tags": [ "Contacts" ], "operationId": "v3ContactsList", "summary": "List contacts in a group", "description": "Lists contacts by group with optional search and pagination controls.", "parameters": [ { "name": "group_id", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": false, "content": { "application/json": { "schema": { "type": "object", "properties": { "search": { "type": "string" }, "limit": { "type": "integer" }, "per_page": { "type": "integer" } } }, "examples": { "default": { "summary": "Default \u2014 first 25 contacts", "value": { "limit": 25 } }, "search": { "summary": "Search by name or phone substring", "value": { "search": "Asha", "limit": 25 } }, "page_2": { "summary": "Pagination \u2014 page 2", "value": { "limit": 25, "page": 2 } }, "subscribed_only": { "summary": "Only subscribed (campaign-eligible) contacts", "value": { "is_subscribed": true, "limit": 50 } } } } } }, "responses": { "200": { "description": "Contact collection. Phone numbers are returned in two parts: `country_code` + `phone_number` (local), and a pre-joined `full_phone_number`.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "items", "pagination" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/Contact" } }, "pagination": { "$ref": "#/components/schemas/Pagination" } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "items": [ { "id": 66, "uid": "ctc_01JXYZ001", "group_id": 8, "group_uid": "grp_01JXYZABC", "name": "John Doe", "country_code": "255", "phone_number": "700333444", "full_phone_number": "255700333444", "is_subscribed": true, "custom_field_values": { "CITY": "Dar es Salaam" } } ], "pagination": { "current_page": 1, "per_page": 25, "last_page": 1, "total": 1, "has_more_pages": false } } } } } } } }, "404": { "description": "Group not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Contact group not found." } } } } } } } } }, "/api/v3/me": { "get": { "tags": [ "Profile & Balance" ], "operationId": "v3ProfileMe", "summary": "Get current account", "description": "Returns the tenant profile represented by the bearer token.", "responses": { "200": { "description": "Tenant profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "id", "name", "slug" ], "properties": { "id": { "type": "integer" }, "name": { "type": "string" }, "slug": { "type": "string" }, "external_client_id": { "type": [ "string", "null" ] }, "created_at": { "type": [ "string", "null" ] }, "updated_at": { "type": [ "string", "null" ] } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "id": 12, "name": "Workspace Alpha", "slug": "workspace-alpha", "external_client_id": null } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Invalid API token." } } } } } } } } }, "/api/v3/webhooks": { "post": { "tags": [ "Webhooks" ], "operationId": "v3WebhooksDocumentation", "summary": "How webhooks work \u2014 payload reference (not an endpoint)", "description": "**This is a documentation entry, not a callable endpoint.** It describes the payload your server will receive when subscribed events fire.\n\nWhen a subscribed event occurs, we send a `POST` to your configured webhook URL with a JSON body and these headers:\n\n| Header | Purpose |\n|---|---|\n| `Content-Type: application/json` | Always JSON. |\n| `User-Agent: MomoBusiness-Webhook/1.0` | Identifies our delivery agent. |\n| `X-Webhook-Signature: sha256=` | HMAC-SHA256 of the raw request body using your webhook secret \u2014 verify before trusting the payload. |\n| `X-Event: ` | Repeats the `event` field from the body for fast routing. |\n\n## Verifying the signature\n\n```php\n$signature = $request->header('X-Webhook-Signature');\n$expected = 'sha256='.hash_hmac('sha256', $request->getContent(), $yourWebhookSecret);\nif (! hash_equals($expected, $signature)) abort(401);\n```\n\n```node\nconst crypto = require('crypto');\nconst expected = crypto.createHmac('sha256', YOUR_WEBHOOK_SECRET).update(rawBody).digest('hex');\nif ('sha256=' + expected !== req.headers['x-webhook-signature']) return res.status(401).end();\n```\n\n## Subscribed event names\n\n| Event | When it fires |\n|---|---|\n| `message.received` | Customer sent you a message (any channel). |\n| `message.sent` | Your outbound message was accepted by the gateway. |\n| `message.delivered` | Gateway confirmed delivery to the recipient device. |\n| `message.read` | Recipient opened the message (WhatsApp only, requires read receipts). |\n| `message.failed` | Send failed; `metadata.error` carries the gateway message. |\n| `message.echoed` | An agent replied via the WhatsApp Business app on their phone (out-of-band reply mirrored back to you). |\n| `order.received` | Customer submitted a cart through your WhatsApp catalogue. |\n\n## Retry policy\n\nIf your endpoint returns a non-2xx status or doesn't respond within 10s, we retry with exponential backoff (15s, 60s, 300s, 1800s, 3600s) for up to 24h. Idempotency key: `message_id` + `event`.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "event", "message_id", "direction", "status", "channel_type", "timestamp" ], "properties": { "event": { "type": "string", "enum": [ "message.received", "message.sent", "message.delivered", "message.read", "message.failed", "message.echoed", "order.received" ], "description": "Which event triggered this delivery." }, "message_id": { "type": "integer", "description": "Our internal message identifier." }, "direction": { "type": "string", "enum": [ "inbound", "outbound" ] }, "sender": { "type": "string", "nullable": true, "description": "E.164 phone (or sender ID for SMS) of the message originator." }, "recipient": { "type": "string", "description": "E.164 phone of the message recipient." }, "status": { "type": "string", "enum": [ "queued", "sent", "delivered", "read", "failed", "received" ] }, "body": { "type": "string", "nullable": true, "description": "Message text or caption (null for media-only / interactive replies)." }, "media_url": { "type": "string", "nullable": true, "description": "Direct URL to the media file when the message contains media." }, "channel_type": { "type": "string", "enum": [ "sms", "whatsapp", "messenger", "instagram", "email" ] }, "timestamp": { "type": "string", "format": "date-time", "description": "ISO 8601 timestamp of when the event was emitted." } } }, "examples": { "message_received_text": { "summary": "Inbound WhatsApp text reply", "value": { "event": "message.received", "message_id": 8421, "direction": "inbound", "sender": "255700111222", "recipient": "255700000111", "status": "received", "body": "Hi, is the laptop still in stock?", "media_url": null, "channel_type": "whatsapp", "timestamp": "2026-04-18T10:21:33Z" } }, "message_received_image": { "summary": "Inbound WhatsApp image (media)", "value": { "event": "message.received", "message_id": 8422, "direction": "inbound", "sender": "255700111222", "recipient": "255700000111", "status": "received", "body": "Here's the receipt", "media_url": "https://cdn.business.momo.tz/media/abc123.jpg", "channel_type": "whatsapp", "timestamp": "2026-04-18T10:25:11Z" } }, "message_delivered": { "summary": "Outbound delivery confirmation", "value": { "event": "message.delivered", "message_id": 8430, "direction": "outbound", "sender": "MyBrand", "recipient": "255700111222", "status": "delivered", "body": "Your order has shipped.", "media_url": null, "channel_type": "sms", "timestamp": "2026-04-18T10:30:02Z" } }, "message_read": { "summary": "Outbound read receipt (WhatsApp)", "value": { "event": "message.read", "message_id": 8430, "direction": "outbound", "sender": "255700000111", "recipient": "255700111222", "status": "read", "body": "Your order has shipped.", "media_url": null, "channel_type": "whatsapp", "timestamp": "2026-04-18T10:31:48Z" } }, "message_failed": { "summary": "Outbound failure", "value": { "event": "message.failed", "message_id": 8435, "direction": "outbound", "sender": "MyBrand", "recipient": "255799000999", "status": "failed", "body": "Payment due tomorrow", "media_url": null, "channel_type": "sms", "timestamp": "2026-04-18T10:35:00Z" } }, "message_echoed": { "summary": "Agent replied via WhatsApp Business app (smb_message_echoes)", "value": { "event": "message.echoed", "message_id": 8440, "direction": "outbound", "sender": "255700000111", "recipient": "255700111222", "status": "sent", "body": "Yes, I have it in stock \u2014 picking up?", "media_url": null, "channel_type": "whatsapp", "timestamp": "2026-04-18T10:40:55Z" } }, "order_received": { "summary": "Customer placed a cart order from your WhatsApp catalogue", "value": { "event": "order.received", "message_id": 8450, "direction": "inbound", "sender": "255700111222", "recipient": "255700000111", "status": "received", "body": "Order received: Dell Latitude X1 x1, USB-C charger x2", "media_url": null, "channel_type": "whatsapp", "timestamp": "2026-04-18T11:05:14Z" } } } } } }, "responses": { "200": { "description": "Your endpoint should respond with a 2xx within 10 seconds. Body is ignored.", "content": { "application/json": { "examples": { "default": { "value": { "ok": true } } } } } }, "401": { "description": "Return 401 when the signature does not match \u2014 we will retry, but persistent 401s eventually disable the webhook.", "content": { "application/json": { "examples": { "default": { "value": { "error": "Invalid signature" } } } } } } } } }, "/api/v3/balance": { "get": { "tags": [ "Profile & Balance" ], "operationId": "v3ProfileBalance", "summary": "Get balance", "description": "Returns wallet balance, currency, billing mode, and spend metadata.", "responses": { "200": { "description": "Tenant wallet balance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "data" ], "properties": { "status": { "type": "string", "enum": [ "success" ] }, "data": { "type": "object", "required": [ "wallet_balance", "wallet_currency", "billing_mode" ], "properties": { "wallet_balance": { "type": "number" }, "wallet_currency": { "type": "string" }, "billing_mode": { "type": "string" }, "cumulative_spend_cents": { "type": "integer" }, "tier_override": { "type": "boolean" }, "last_updated_at": { "type": [ "string", "null" ] } } } } }, "examples": { "default": { "value": { "status": "success", "data": { "wallet_balance": 12000.5, "wallet_currency": "TZS", "billing_mode": "prepaid", "cumulative_spend_cents": 0, "tier_override": false } } } } } } }, "401": { "description": "Unauthorized.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "examples": { "default": { "value": { "status": "error", "message": "Missing bearer token." } } } } } } } } }, "/api/v3/catalogues": { "get": { "operationId": "v3CataloguesList", "tags": [ "Catalogue" ], "summary": "List shops", "description": "List the shops (product catalogues) belonging to your tenant, with their name, currency and the channels each is published to.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/{catalogue}": { "get": { "operationId": "v3CataloguesShow", "tags": [ "Catalogue" ], "summary": "Get one shop with its products", "description": "Return a single shop and the products it holds, including SKU, price, availability, brand and category.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop id, as returned by the shop list.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/{catalogue}/products": { "post": { "operationId": "v3CatalogueProductCreate", "tags": [ "Catalogue" ], "summary": "Add a product to a shop", "description": "Create one product in a shop. The SKU is optional \u2014 leave it out and the shop issues its own code, which is also what gets sent to any connected platform as its required retailer id.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop the product belongs to.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } }, "get": { "operationId": "v3CatalogueProductsList", "tags": [ "Catalogue" ], "summary": "List a shop's products", "description": "List the products in one shop, with SKU, price, availability, brand and category.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop whose products to list.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/{catalogue}/products/batch": { "post": { "operationId": "v3CatalogueProductsBatch", "tags": [ "Catalogue" ], "summary": "Add or update many products at once", "description": "Create or update products in bulk. Rows are matched on SKU where you supply one, so re-sending the same batch updates rather than duplicating.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop the products belong to.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/{catalogue}/products/{product}": { "delete": { "operationId": "v3CatalogueProductDelete", "tags": [ "Catalogue" ], "summary": "Remove a product from a shop", "description": "Delete one product. It is also retired from any platform it had been published to.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop the product belongs to.", "schema": { "type": "integer" } }, { "name": "product", "in": "path", "required": true, "description": "The product to remove.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } }, "get": { "operationId": "v3CatalogueProductShow", "tags": [ "Catalogue" ], "summary": "Get one product", "description": "Return a single product in full, including its description, images and the platforms it is currently published to.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop the product belongs to.", "schema": { "type": "integer" } }, { "name": "product", "in": "path", "required": true, "description": "The product to return.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } }, "put": { "operationId": "v3CatalogueProductUpdate", "tags": [ "Catalogue" ], "summary": "Update a product", "description": "Update a product's details. The SKU is fixed once the product has been published to a platform, because that platform treats it as the item's identity.", "parameters": [ { "name": "catalogue", "in": "path", "required": true, "description": "The shop the product belongs to.", "schema": { "type": "integer" } }, { "name": "product", "in": "path", "required": true, "description": "The product to update.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/orders": { "get": { "operationId": "v3CatalogueOrdersList", "tags": [ "Catalogue" ], "summary": "List shop orders", "description": "List orders placed against your shops, newest first, with their status, total and whether payment has settled.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/orders/{order}": { "get": { "operationId": "v3CatalogueOrderShow", "tags": [ "Catalogue" ], "summary": "Get one order", "description": "Return a single order in full: the customer, the items ordered, the total, the status history and every payment attempt against it.", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The order id, as returned by the order list.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/orders/{order}/status": { "put": { "operationId": "v3CatalogueOrderStatusUpdate", "tags": [ "Catalogue" ], "summary": "Move an order to a new status", "description": "Advance an order to confirmed, processing, shipped, delivered, cancelled or refunded, and optionally notify the customer on the channel they ordered from.", "parameters": [ { "name": "order", "in": "path", "required": true, "description": "The order to move.", "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/send-product": { "post": { "operationId": "v3CatalogueSendProduct", "tags": [ "Catalogue" ], "summary": "Send one product to a customer", "description": "Send a single product card to a customer on WhatsApp, so they can view it and add it to a cart without leaving the chat.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/send-product-list": { "post": { "operationId": "v3CatalogueSendProductList", "tags": [ "Catalogue" ], "summary": "Send a list of products to a customer", "description": "Send several products grouped into sections as one interactive message \u2014 the usual way to answer \"what do you have?\" in chat.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } }, "/api/v3/catalogues/send-catalogue": { "post": { "operationId": "v3CatalogueSendCatalogue", "tags": [ "Catalogue" ], "summary": "Send the whole shop to a customer", "description": "Send the full catalogue as one message, letting the customer browse everything the shop has published to that channel.", "parameters": [], "responses": { "200": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "data": { "type": "object" } } }, "example": { "status": "success", "data": [] } } } }, "422": { "description": "Validation error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LegacyErrorEnvelope" }, "example": { "status": "error", "message": "Validation failed.", "errors": { "field": [ "The field is required." ] } } } } } } } } } }