{ "item": [ { "id": "3df36ffe-6d3a-4a5a-b2d1-a26a2ae19002", "name": "Messaging", "description": { "content": "Send text messages and approved templates.", "type": "text/plain" }, "item": [ { "id": "60de3bfe-750a-4af3-bad7-8bf5588a405c", "name": "Send a text message or an approved template", "request": { "name": "Send a text message or an approved template", "description": { "content": "Sends a WhatsApp message to any number. The recipient is created as a contact and a\nconversation is opened on the workspace's first connected number if one does not\nalready exist.\n\n* `type: text` (the default) sends free text. WhatsApp only accepts it inside the\n 24-hour customer-service window; outside it, Meta rejects the send and the call\n answers `502 send_failed`.\n* `type: template` sends an approved template and works at any time.\n\nFor templates, `params` fills the body variables in order. If you need header,\nbutton or non-text components, send a raw `components` array instead — it is\nforwarded to Meta as-is and is only read when `params` is absent or empty.\n", "type": "text/plain" }, "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "1735a8a9-8f62-48a1-9a4a-02c9565144ed", "name": "Accepted by WhatsApp and stored in the conversation.", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"message_id\": 91733,\n \"wamid\": \"wamid.HBgMOTY2NTUwNTIxNjcy\",\n \"to\": \"966550521672\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cda4e678-8b68-4fe5-a5a4-98460f689bc1", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cf33d98b-9ed6-42dc-9ba8-d7daba8eca40", "name": "The workspace has no WhatsApp number to send from.", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"no_whatsapp_number\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f338d564-0dbc-490a-a763-0a5bcd21c589", "name": "A required field is missing — `to_required`, `body_required` (text) or\n`template_required` (template).\n", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"to_required\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "4057ca30-c2b4-4dc2-8ca4-607efeff9c66", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "757f7c02-960b-440a-835c-35f0a89087c5", "name": "WhatsApp refused the message. `detail` carries Meta's own error text, and\n`message_id` is the row Marsal stored for the failed attempt.\n", "originalRequest": { "url": { "path": [ "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك يا أحمد، طلبك اتشحن النهاردة ✅\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"send_failed\",\n \"detail\": \"(#131047) Re-engagement message\",\n \"message_id\": 91734\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "9123d95e-464b-4e1c-9a7d-d7d53acbbc4f", "name": "OTP", "description": { "content": "One-time passcodes delivered over WhatsApp.", "type": "text/plain" }, "item": [ { "id": "6f37859a-ad2a-426a-8aae-ebb70589ae24", "name": "Send a one-time passcode", "request": { "name": "Send a one-time passcode", "description": { "content": "Marsal generates a six-digit code (or uses the one you pass), stores only its\nSHA-256 hash with the given TTL, and delivers it over WhatsApp.\n\nPass `template` to deliver through an approved OTP template — that works at any\ntime. Omit it and the code goes out as plain Arabic text, which WhatsApp only\naccepts inside the 24-hour window.\n", "type": "text/plain" }, "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "1cc6f171-f504-4cf8-a541-f53678656df2", "name": "The code was sent and stored.", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"to\": \"966550521672\",\n \"expires_in\": 300,\n \"message_id\": 91740\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ae24da40-6040-4d93-9f28-efcd69dee894", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "23f27008-82b0-461a-a036-fb55d6464855", "name": "The workspace has no WhatsApp number to send from.", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"no_whatsapp_number\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "8389af13-e21c-4c75-b14d-3b73cab9f042", "name": "`to` is missing.", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"to_required\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "1c78c26a-a06e-4011-9854-474e3457e804", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c53acfe3-abfc-46ac-919f-a37db0281574", "name": "WhatsApp refused the message.", "originalRequest": { "url": { "path": [ "otp", "send" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"template\": \"otp_code\",\n \"language\": \"ar\",\n \"ttl\": 300\n}", "options": { "raw": { "language": "json" } } } }, "status": "Bad Gateway", "code": 502, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"send_failed\",\n \"detail\": \"(#132000) Number of parameters does not match\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "a8c2adaf-5f5e-42a7-99e2-384444848104", "name": "Verify a one-time passcode", "request": { "name": "Verify a one-time passcode", "description": { "content": "Checks the code against the newest unverified, unexpired code stored for that\nnumber in your workspace. A correct code is marked used and cannot be replayed.\nA wrong code increments an attempt counter; after five failed attempts the code\nstops matching and `verified` stays `false`.\n\nA wrong, expired or unknown code is **not** an error — the call answers `200` with\n`\"verified\": false`.\n", "type": "text/plain" }, "url": { "path": [ "otp", "verify" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"code\": \"418302\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "b96f1339-7015-4e5d-913f-4dd26f6aa0c3", "name": "The check ran. Read `verified`.", "originalRequest": { "url": { "path": [ "otp", "verify" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"code\": \"418302\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"verified\": true\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d5d3bab7-6a67-483c-85dc-83d0a091ee8b", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "otp", "verify" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"code\": \"418302\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c2adb493-5977-496c-b816-5510cffcd5a2", "name": "`to` or `code` is missing.", "originalRequest": { "url": { "path": [ "otp", "verify" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"code\": \"418302\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"to_and_code_required\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5a0a0f96-8880-4c2b-905a-1971a131b482", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "otp", "verify" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"to\": \"966550521672\",\n \"code\": \"418302\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "868c95b5-9165-441a-8f9c-b4def0792eb7", "name": "Conversations", "description": { "content": "Read, reply to and manage chats.", "type": "text/plain" }, "item": [ { "id": "69ec852f-f995-4d2a-b6ee-294ac406989b", "name": "List conversations", "request": { "name": "List conversations", "description": { "content": "Chats in the workspace, newest activity first. Each row carries the contact, the\nunread count, a preview of the last message and whether the 24-hour window is open.\n\nWorkspaces that set an inbox auto-hide window in their settings drop chats that\nhave had no inbound message for longer than that window; the conversation itself is\nuntouched and returns to the list on the next inbound message.\n", "type": "text/plain" }, "url": { "path": [ "conversations" ], "host": [ "{{base_url}}" ], "query": [ { "disabled": true, "key": "status", "value": "all", "description": "Filter by state. Any other value is treated as `all`." }, { "disabled": true, "key": "limit", "value": "100", "description": "Maximum rows to return." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "2291b025-850a-4772-8212-fe5b836b1b32", "name": "The conversation list.", "originalRequest": { "url": { "path": [ "conversations" ], "host": [ "{{base_url}}" ], "query": [ { "key": "status", "value": "all" }, { "key": "limit", "value": "100" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"conversations\": [\n {\n \"id\": 8421,\n \"contact_id\": 5107,\n \"name\": \"أحمد الغامدي\",\n \"wa_id\": \"966550521672\",\n \"status\": \"open\",\n \"unread\": 2,\n \"last_message_at\": \"2026-09-20 14:31:08\",\n \"last_inbound_at\": \"2026-09-20 14:31:08\",\n \"session_open\": true,\n \"preview\": \"هل المنتج متوفر؟\"\n },\n {\n \"id\": 8377,\n \"contact_id\": 5022,\n \"name\": \"سارة عبد الرحمن\",\n \"wa_id\": \"201001234567\",\n \"status\": \"closed\",\n \"unread\": 0,\n \"last_message_at\": \"2026-09-18 09:12:44\",\n \"last_inbound_at\": \"2026-09-18 09:10:02\",\n \"session_open\": false,\n \"preview\": \"شكراً ليكم 🌹\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d0b8ec9a-8ad2-49c7-8d63-776b57791e7d", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "conversations" ], "host": [ "{{base_url}}" ], "query": [ { "key": "status", "value": "all" }, { "key": "limit", "value": "100" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b9e7acb8-6880-41e4-ad7d-66e99f820c78", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "conversations" ], "host": [ "{{base_url}}" ], "query": [ { "key": "status", "value": "all" }, { "key": "limit", "value": "100" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0b8f95d7-8389-4824-adba-dfb1a71576ab", "name": "Get a conversation's messages", "request": { "name": "Get a conversation's messages", "description": { "content": "The most recent messages of a conversation, oldest first.\n\nEmoji reactions are not returned as their own rows: each one is folded into the\n`reactions` array of the message it points at, with `mine` telling you which side\nsent it. A quoted message is embedded under `reply_to` with its body truncated to\n140 characters. Media that arrived without a caption comes back with an empty\n`body` and a `media_url`.\n", "type": "text/plain" }, "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [ { "disabled": true, "key": "limit", "value": "200", "description": "How many of the newest messages to load before filtering." }, { "disabled": true, "key": "after_id", "value": "0", "description": "Return only messages with an id greater than this. Use it to poll a thread." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "c5299ce5-e6d7-476c-8233-e889d87a849b", "name": "The thread.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [ { "key": "limit", "value": "200" }, { "key": "after_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"session_open\": true,\n \"ai_enabled\": false,\n \"messages\": [\n {\n \"id\": 91730,\n \"direction\": \"in\",\n \"type\": \"text\",\n \"body\": \"هل المنتج متوفر؟\",\n \"media_url\": null,\n \"status\": null,\n \"created_at\": \"2026-09-20 14:31:08\",\n \"reactions\": []\n },\n {\n \"id\": 91733,\n \"direction\": \"out\",\n \"type\": \"text\",\n \"body\": \"أهلاً بيك، أيوه متوفر ✅\",\n \"media_url\": null,\n \"status\": \"delivered\",\n \"created_at\": \"2026-09-20 14:32:55\",\n \"reply_to\": {\n \"id\": 91730,\n \"direction\": \"in\",\n \"type\": \"text\",\n \"body\": \"هل المنتج متوفر؟\"\n },\n \"reactions\": [\n {\n \"emoji\": \"👍\",\n \"mine\": false\n }\n ]\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cfe30757-1864-41fa-9cfb-6f5a66b99843", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [ { "key": "limit", "value": "200" }, { "key": "after_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "44d678b4-d775-43be-b6e3-7b3074a87929", "name": "No conversation with that id in this workspace.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [ { "key": "limit", "value": "200" }, { "key": "after_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"conversation_not_found\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "89b4a541-5a34-4794-92d2-fc9f592e866a", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [ { "key": "limit", "value": "200" }, { "key": "after_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "f3d8acae-229f-4e6b-a5a5-a8711b46d724", "name": "Reply inside a chat", "request": { "name": "Reply inside a chat", "description": { "content": "Sends a free-text reply in an existing conversation. Only works while the 24-hour\nwindow is open — use `POST /messages` with a template otherwise.\n\nReplying takes the chat off the AI bot (human takeover), exactly as the web inbox\ndoes. The message is stored immediately with `status: \"pending\"` and handed to Meta\nafter the response has been flushed, so `wamid` is always `null` here; poll the\nthread to watch the status move to `sent`, `delivered`, `read` or `failed`.\n", "type": "text/plain" }, "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "3d46ca93-c0df-419f-a790-f1290fe5c19b", "name": "Stored and queued for delivery.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"message_id\": 91733,\n \"wamid\": null,\n \"status\": \"pending\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b5ff5f70-91c5-4103-bdf5-46559ef7095b", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "0b8e9d0e-0274-4889-aa2e-8f9beedd62d9", "name": "No conversation with that id in this workspace.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"conversation_not_found\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "ad68f52a-0070-4063-a0c1-8a5a6ea798ba", "name": "`session_closed` — the 24-hour window has expired, so free text is not allowed.\n`number_unavailable` — the conversation's WhatsApp number no longer belongs to\nthis workspace.\n", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "Conflict", "code": 409, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"session_closed\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "3eaf2efd-4977-44ba-b7a5-1328d3d8fed9", "name": "`body` is empty.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"empty_message\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "208f2f26-0f07-4484-8177-ef7aa46305e2", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "messages" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"body\": \"تمام، هجهزلك الطلب النهاردة 👌\",\n \"reply_to\": 91730\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e81ddc0b-b69b-41c7-ad0d-10e4ccbd0b83", "name": "Mark a conversation read", "request": { "name": "Mark a conversation read", "description": { "content": "Clears the unread counter and, when something was actually unread, tells WhatsApp\nthe customer's latest message was read so their ticks turn blue. Takes no body.\n", "type": "text/plain" }, "url": { "path": [ "conversations", "{{conversation_id}}", "read" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null }, "response": [ { "id": "33eb2a3c-925f-4913-b7d6-cfc8e110abea", "name": "Marked read.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "read" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b064be1f-3efc-4aa8-ad9a-9829be31e9db", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "read" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "650b02df-8aa0-4595-92a2-22822e0e9d4b", "name": "No conversation with that id in this workspace.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "read" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"conversation_not_found\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c2f77844-c6c8-4d32-858a-00c566de4935", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "read" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "88d2adf3-d6de-41bc-acab-3ef5e0277620", "name": "Turn the AI bot on or off for one chat", "request": { "name": "Turn the AI bot on or off for one chat", "description": { "content": "Controls whether the AI bot answers in this conversation. Note that any agent or\nAPI reply in the thread switches it off again (human takeover).\n\n`enabled` is read loosely: it is truthy for `1`, `true`, `\"1\"`, `\"true\"`, `\"on\"`\nand `\"yes\"`, and falsy for everything else. Omitting it turns the bot **on**.\n", "type": "text/plain" }, "url": { "path": [ "conversations", "{{conversation_id}}", "ai" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"enabled\": 0\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "7f3ae7bc-a976-46b9-8963-75e726be04ef", "name": "The new state.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "ai" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"enabled\": 0\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"ai_enabled\": 0\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "06c3854a-9373-4d58-bd6a-9daf1e95319a", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "ai" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"enabled\": 0\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bc8fcf8b-9c93-40cd-841e-be00c61ab3c3", "name": "No conversation with that id in this workspace.", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "ai" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"enabled\": 0\n}", "options": { "raw": { "language": "json" } } } }, "status": "Not Found", "code": 404, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"conversation_not_found\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "68bd9049-8ba2-4b52-af42-9270a1e0aa4f", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "conversations", "{{conversation_id}}", "ai" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"enabled\": 0\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "9b6ea61f-5ec2-436f-b1b9-d1dceaba52b5", "name": "Contacts", "description": { "content": "The people in your workspace.", "type": "text/plain" }, "item": [ { "id": "9baa49db-d531-4cc0-bcae-fd362be2ed96", "name": "List contacts", "request": { "name": "List contacts", "description": { "content": "Contacts in the workspace, newest first, each with the tags attached to it. The\nresponse also carries every tag defined in the workspace under `tags`, so a client\ncan draw the full filter list even when the current page uses none of them.\n", "type": "text/plain" }, "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [ { "disabled": true, "key": "q", "value": "أحمد", "description": "Substring match on the contact's name or WhatsApp number." }, { "disabled": true, "key": "tag_id", "value": "2938", "description": "Return only contacts carrying this tag." }, { "disabled": true, "key": "limit", "value": "200", "description": "Maximum rows to return. Values outside the range are clamped." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "f260babf-096f-440b-8d93-b104c610c1bc", "name": "The contact list.", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [ { "key": "q", "value": "أحمد" }, { "key": "tag_id", "value": "2938" }, { "key": "limit", "value": "200" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"tags\": [\n {\n \"id\": 12,\n \"name\": \"عملاء الرياض\",\n \"color\": \"#00E5A4\"\n },\n {\n \"id\": 13,\n \"name\": \"VIP\",\n \"color\": \"#0099FF\"\n }\n ],\n \"contacts\": [\n {\n \"id\": 5107,\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\",\n \"created_at\": \"2026-08-02 11:05:19\",\n \"opted_in\": 1,\n \"last_inbound_at\": \"2026-09-20 14:31:08\",\n \"tags\": [\n {\n \"id\": 12,\n \"name\": \"عملاء الرياض\",\n \"color\": \"#00E5A4\"\n }\n ]\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6340df61-7e08-4e43-a129-416d0cb43824", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [ { "key": "q", "value": "أحمد" }, { "key": "tag_id", "value": "2938" }, { "key": "limit", "value": "200" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "dae21f36-8f15-4853-abb2-c24abe00661d", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [ { "key": "q", "value": "أحمد" }, { "key": "tag_id", "value": "2938" }, { "key": "limit", "value": "200" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "0a0012db-0aaf-428f-ab34-32572d9df5a4", "name": "Add a contact", "request": { "name": "Add a contact", "description": { "content": "Creates the contact, or updates the existing one with the same WhatsApp number —\nthe number is the key, so this call is safe to repeat. Non-digit characters in\n`wa_id` are stripped before use.\n", "type": "text/plain" }, "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Content-Type", "value": "application/json" }, { "key": "Accept", "value": "application/json" } ], "method": "POST", "auth": null, "body": { "mode": "raw", "raw": "{\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\"\n}", "options": { "raw": { "language": "json" } } } }, "response": [ { "id": "4fa19608-065c-4538-9354-cc55926badce", "name": "The contact id.", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"contact_id\": 5107\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "5062e6d0-1c5e-4927-8257-059bc8aa7fb0", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "cd9722d5-5eee-4551-b371-6c9f36e5849f", "name": "`wa_id` is missing.", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Unprocessable Entity (WebDAV) (RFC 4918)", "code": 422, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"wa_id_required\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "2f7a48eb-4425-45aa-ad16-e809e8410b46", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "contacts" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "POST", "body": { "mode": "raw", "raw": "{\n \"wa_id\": \"966550521672\",\n \"name\": \"أحمد الغامدي\",\n \"email\": \"ahmed@example.sa\"\n}", "options": { "raw": { "language": "json" } } } }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "121982ce-bd4f-4005-a08c-c8400f441a93", "name": "Reference", "description": { "content": "Templates, numbers, campaigns and workspace counters.", "type": "text/plain" }, "item": [ { "id": "953fc622-fcd2-4624-bf79-e230558b9756", "name": "List message templates", "request": { "name": "List message templates", "description": { "content": "Your WhatsApp message templates with their Meta status, parsed header, footer and\nbutton labels, and `vars` — the number of distinct `{{n}}` placeholders in the\nbody, which is how many entries `params` needs when you send it.\n\nMarsal refreshes template statuses from Meta at most once every three minutes, so\na fresh approval can take that long to appear here.\n\n`can_manage` reports whether the caller may create or delete templates. An API key\nis read-only for templates and always sees `false`.\n", "type": "text/plain" }, "url": { "path": [ "templates" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "a4a11cc6-12f4-46a8-8633-9734ce9d7cf9", "name": "The template list.", "originalRequest": { "url": { "path": [ "templates" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"can_manage\": false,\n \"templates\": [\n {\n \"id\": 77,\n \"name\": \"order_confirmation\",\n \"language\": \"ar\",\n \"category\": \"UTILITY\",\n \"status\": \"APPROVED\",\n \"body\": \"أهلاً {{1}}، طلبك رقم {{2}} اتأكد ✅\",\n \"header\": \"تأكيد الطلب\",\n \"footer\": \"مرسال\",\n \"buttons\": [\n \"تتبع الطلب\"\n ],\n \"vars\": 2,\n \"wa_number_id\": 4,\n \"created_at\": \"2026-07-14 10:22:51\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "db568bdb-8459-49c5-9937-4df2f284c789", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "templates" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "849cb44a-a500-4d9d-9c4f-24822e4d32c0", "name": "The caller's role or the workspace's plan does not unlock this feature. `feature`\nnames the capability that was refused.\n", "originalRequest": { "url": { "path": [ "templates" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"forbidden\",\n \"feature\": \"templates\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "04a9604c-aa3b-4de5-bb5f-fcd696a98090", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "templates" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "34fbfe23-b900-481e-9aa3-3b8693bd2b0c", "name": "List connected WhatsApp numbers", "request": { "name": "List connected WhatsApp numbers", "description": { "content": "The workspace's WhatsApp numbers with their status, Meta quality rating, and the\n`waba_id` / `phone_number_id` that Meta support asks for. `webhook_url` is the\ninbound callback URL Marsal has registered with Meta for this deployment — it is\nwhere WhatsApp delivers messages to Marsal, not where Marsal calls you. Access\ntokens are never returned.\n", "type": "text/plain" }, "url": { "path": [ "numbers" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "0a161485-003c-4ecf-a5b6-fc14beadaed1", "name": "The number list.", "originalRequest": { "url": { "path": [ "numbers" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"webhook_url\": \"https://usemarsal.cloud/webhook.php\",\n \"numbers\": [\n {\n \"id\": 4,\n \"display_number\": \"+966 55 052 1672\",\n \"verified_name\": \"متجر نجد\",\n \"status\": \"connected\",\n \"quality_rating\": \"GREEN\",\n \"waba_id\": \"102938475610293\",\n \"phone_number_id\": \"109876543210987\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "05538281-a2e3-439c-8c85-d5fbff3050a7", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "numbers" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "6b682a05-05f6-4f4d-9ee8-798664473cbf", "name": "The caller's role or the workspace's plan does not unlock this feature. `feature`\nnames the capability that was refused.\n", "originalRequest": { "url": { "path": [ "numbers" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"forbidden\",\n \"feature\": \"templates\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "faed6088-b677-4c67-98ff-8fb2b6284909", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "numbers" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "79cfeafb-cde5-4e92-90a7-41917b4bb36d", "name": "List broadcast campaigns", "request": { "name": "List broadcast campaigns", "description": { "content": "The 100 most recent campaigns with their per-recipient counters. Read-only over\nthe API; campaigns are created in the workspace panel. `can_manage` is always\n`false` for an API key.\n", "type": "text/plain" }, "url": { "path": [ "campaigns" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "4bed7a47-f0f4-4c4b-8b00-2e4472e79785", "name": "The campaign list.", "originalRequest": { "url": { "path": [ "campaigns" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"can_manage\": false,\n \"items\": [\n {\n \"id\": 311,\n \"name\": \"عرض رمضان\",\n \"status\": \"sent\",\n \"total\": 1200,\n \"sent\": 1187,\n \"delivered\": 1102,\n \"read\": 840,\n \"failed\": 13,\n \"scheduled_at\": \"2026-09-15 09:00:00\",\n \"started_at\": \"2026-09-15 09:00:07\",\n \"finished_at\": \"2026-09-15 09:41:22\",\n \"created_at\": \"2026-09-14 22:10:03\",\n \"template_id\": 77,\n \"template_name\": \"order_confirmation\",\n \"segment_id\": 9,\n \"segment_name\": \"عملاء الخليج\",\n \"wa_number_id\": 4\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "c7f69978-8ca9-4baf-80ce-270515ba325a", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "campaigns" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "bf6d3f9a-4d00-47b1-b480-0cdcc0c5a0e2", "name": "The caller's role or the workspace's plan does not unlock this feature. `feature`\nnames the capability that was refused.\n", "originalRequest": { "url": { "path": [ "campaigns" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Forbidden", "code": 403, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"forbidden\",\n \"feature\": \"templates\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "f2dd6a0f-211d-4beb-b1eb-5c77502f9944", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "campaigns" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } }, { "id": "e32d60bc-3ef5-4f52-b249-27781993af0f", "name": "Workspace counters", "request": { "name": "Workspace counters", "description": { "content": "Live counts for the workspace: total contacts, open conversations, total unread\nmessages, messages created today (server time) and total campaigns.\n", "type": "text/plain" }, "url": { "path": [ "dashboard" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "4e71cff4-ecb5-4566-b8ad-115165226687", "name": "The counters.", "originalRequest": { "url": { "path": [ "dashboard" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"stats\": {\n \"contacts\": 5240,\n \"open_conversations\": 38,\n \"unread\": 71,\n \"messages_today\": 612,\n \"campaigns\": 17\n }\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "43798dd0-bcab-47be-9372-22db3d9cf1f0", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "dashboard" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "31c79f03-6807-47ce-a68f-9dc0f4e9aee3", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "dashboard" ], "host": [ "{{base_url}}" ], "query": [] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] }, { "id": "03fc1fd5-157c-48a2-a318-75b9dd9f8df2", "name": "Realtime", "description": { "content": "Poll for new inbound messages.", "type": "text/plain" }, "item": [ { "id": "da55cdfc-1fdf-4aaa-a6bb-a3b1e95c9609", "name": "Poll for new inbound messages", "request": { "name": "Poll for new inbound messages", "description": { "content": "Returns up to 50 inbound messages with an id greater than `since_id`, oldest first,\nplus `last_id` — the newest inbound message id in the workspace. Store `last_id`\nand pass it as the next `since_id`.\n\nNon-text messages come back with a type placeholder as the body (`[image]`,\n`[audio]`, `[document]`, …) rather than their caption; text bodies are truncated to\n200 characters. For anything longer, or for outbound and status events, use\nwebhooks.\n", "type": "text/plain" }, "url": { "path": [ "updates" ], "host": [ "{{base_url}}" ], "query": [ { "disabled": true, "key": "since_id", "value": "0", "description": "Return only inbound messages with an id greater than this." } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "auth": null }, "response": [ { "id": "2829385d-f686-4152-9c2e-2aa72665ff93", "name": "New inbound messages.", "originalRequest": { "url": { "path": [ "updates" ], "host": [ "{{base_url}}" ], "query": [ { "key": "since_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "OK", "code": 200, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": true,\n \"last_id\": 91742,\n \"unread\": 71,\n \"messages\": [\n {\n \"id\": 91741,\n \"conversation_id\": 8421,\n \"from\": \"أحمد الغامدي\",\n \"type\": \"text\",\n \"body\": \"تمام، مستنيك\",\n \"created_at\": \"2026-09-20 15:02:10\"\n },\n {\n \"id\": 91742,\n \"conversation_id\": 8377,\n \"from\": \"+201001234567\",\n \"type\": \"image\",\n \"body\": \"[image]\",\n \"created_at\": \"2026-09-20 15:03:44\"\n }\n ]\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "d24a5f55-6a94-4391-91f4-934cecc0edd4", "name": "The bearer token is missing, malformed, revoked or expired.", "originalRequest": { "url": { "path": [ "updates" ], "host": [ "{{base_url}}" ], "query": [ { "key": "since_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Unauthorized", "code": 401, "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"unauthenticated\"\n}", "cookie": [], "_postman_previewlanguage": "json" }, { "id": "b57b28e3-2867-4fa2-aeda-378ef114073d", "name": "Too many calls. Applies to mobile device tokens, which are capped at 300 calls per\nminute; `Retry-After` carries the seconds left in the current minute.\n", "originalRequest": { "url": { "path": [ "updates" ], "host": [ "{{base_url}}" ], "query": [ { "key": "since_id", "value": "0" } ] }, "header": [ { "key": "Accept", "value": "application/json" } ], "method": "GET", "body": {} }, "status": "Too Many Requests", "code": 429, "header": [ { "disabled": true, "description": "Seconds until the counter resets.", "key": "Retry-After", "value": "5439" }, { "key": "Content-Type", "value": "application/json" } ], "body": "{\n \"ok\": false,\n \"error\": \"rate_limited\"\n}", "cookie": [], "_postman_previewlanguage": "json" } ], "event": [], "protocolProfileBehavior": { "disableBodyPruning": true } } ], "event": [] } ], "event": [], "variable": [], "auth": { "type": "bearer", "bearer": [ { "key": "token", "value": "{{api_key}}", "type": "string" } ] }, "info": { "_postman_id": "944e7f72-72bd-4198-946d-2fc320039350", "name": "Marsal Cloud WhatsApp Business API", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json", "description": { "content": "Generated from the Marsal OpenAPI 3.1 description (https://usemarsal.cloud/openapi.yaml).\n\nSelect the **Marsal Cloud** environment and set `api_key` to a workspace key from\nDevelopers · API (it looks like `msk_live_…`). Every request inherits the\ncollection’s bearer auth, so nothing else needs configuring.\n\nSending a request here sends a real WhatsApp message from your workspace and is\nbilled like any other send. `POST /otp/verify` and every GET are safe to explore.", "type": "text/markdown" } } }