{ "info": { "_postman_id": "9d9f1a2c-3a02-4c3e-9f77-99d0a7b2c0d2", "name": "99digital - WhatsApp API (v2)", "description": "Complete, runnable reference for the **99digital WhatsApp API** (v2).\n\nEvery endpoint is here, and each one ships with **one sample per option**: every template kind you can create and send (text, media header, buttons, coupon, authentication, carousel, Hebrew / English), every session message (text, files, buttons, lists, carousels, location, contacts, reactions), profile, history, block list, webhook settings - and samples of every webhook we send you. Fill a few variables, press **Send**, and you are talking to production.\n\n---\n\n## Quick start\n\n1. **Variables tab** -> fill `apiKey` and `from` (your WhatsApp API number, international format without `+`, e.g. `972501234567`).\n2. Fill `to` with a test phone number. For the *session* messages in folder 1 that person must write to your number first (WhatsApp's 24-hour rule); templates in folder 2 need no prior message.\n3. Run *3 - Account & profile -> getProfile* to check your credentials (`reason 2` = unknown `from`, `reason 3` = wrong `apiKey`), then open any folder and press **Send**.\n\nThe collection stores the `unique` of your last successful send in `{{last_unique}}`, so the 'quote your own message' samples work with no copy-paste.\n\n`base_url` is `https://api.99digital.co.il`.\n\n## Authentication\n\nAll endpoints are **POST** with a JSON body (`Content-Type: application/json`).\n\n- The **`apiKey` goes in the request header** - this collection attaches it automatically to every request (collection-level auth), so it never appears in a body.\n- The **`from`** field (in the body) is your WhatsApp API number.\n\n```\nContent-Type: application/json\napiKey: 2f080c-015335-d949da-691933-06ad82\n```\n\n## The one rule that matters: the 24-hour window\n\n| You want to... | Use | Billing |\n|---|---|---|\n| Reply to a customer who wrote to you in the **last 24 hours** | Folder **1** - `sendMessage`, `sendFile`, `sendButtons`, `sendList`, `sendCarousel`, ... | Free, unlimited |\n| Message someone who **never wrote to you**, or whose last message is **older than 24 hours** | Folder **2** - an approved **template** via `sendTemplate` / `sendMultiTemplate` | Per template conversation (utility is free while a window is open) |\n\nEvery incoming message restarts the customer's 24-hour clock. A session message outside the window fails with **reason 7**; every send response carries `templateTimeLeft` = minutes left, and `getTimers` tells you without sending. Sending a template does *not* open the window - only the customer can, by replying.\n\n## Recipients\n\n`to` is a phone number in international format without `+` (`972501234567`), or - for customers who hide their number behind a WhatsApp **username** - the user id from your webhook (`IL.1605856887361213`: two-letter country, a dot, 16 digits). Groups are not supported.\n\n## Reading a response\n\n**Every response is HTTP 200.** Read the JSON `status` (`OK` / `FAIL`) and `reason`, never the HTTP code.\n\n```json\n{ \"status\": \"FAIL\", \"reason\": 7 }\n```\n\nReason codes are **per endpoint** - the meaning of `9` differs between `sendButtons` and `sendList` - so every request in this collection carries its own reason table. Five codes are shared by all sends:\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` is not one of your numbers, the body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 7 | No open 24-hour window with `to` - use a template |\n\n## Asynchronous delivery and `unique`\n\nSends return in well under a second with `status: OK` and a **`unique`** id (47 chars). That means *accepted and queued* - not delivered. Sent / delivered / read / failed arrive on your **webhook** as `hook: update` with `ack` 1 / 2 / 3 / 0 and the same `unique`; the reason of a failure comes as `hook: system`, `type: messages`. Store the `unique`: it is also the id in `getHistory` and the handle for `replyTo`.\n\n## Webhooks\n\nSet your URL once with `setWebhook` (folder 4) and you receive incoming messages (`hook: new`), delivery statuses (`hook: update`), system events (`hook: system`) and, for coexistence numbers, contact and outgoing echoes. Folder 5 contains a sample of every payload, wired to `{{your_webhook_url}}` so you can test your handler from Postman. Answer 2xx within 5 seconds; enable `retry` for automatic redelivery.\n\n## Media\n\nMedia is always a **public https URL that WhatsApp downloads** from your server. Image jpg/png <=5MB, video mp4 <=16MB, audio <=16MB, document <=100MB. The `sample_*_url` variables point at small public sample files that work out of the box. If your server blocks WhatsApp's data centres, add `localStorage: 1` and we fetch and upload the file ourselves.\n\n## Limits\n\n- Business-initiated (template) conversations: 250 per 24h for a new number, rising automatically to 1k / 2k / 10k / 100k / unlimited with volume and quality (`dailyLimit` in `getProfile`).\n- Throughput: 80 messages per second per number (20 for coexistence numbers); at most 10 messages per minute to the same customer.\n- At most 2 marketing templates to the same customer per 24 hours.\n\n## Hosting\n\nYour number may be hosted directly on Meta's Cloud API or through one of our partner providers. The API is identical either way; the few places where a provider behaves differently are noted in the request description.\n\n## IP addresses\n\nWebhooks are sent from **34.165.99.212**. If you allow-list outgoing calls, the API host resolves to **130.211.28.127**.\n\n---\n\nThis collection is generated from the running API, so the copy at **https://api.99digital.co.il/whatsapp-postman** is always in step with production - re-download it after any release note that touches the WhatsApp endpoints. Re-importing updates this same collection instead of creating a duplicate.\n\nFull documentation: https://docs.99digital.co.il  |  Support: support@99digital.co.il", "version": "1.0.0", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "auth": { "type": "apikey", "apikey": [ { "key": "key", "value": "apiKey", "type": "string" }, { "key": "value", "value": "{{apiKey}}", "type": "string" }, { "key": "in", "value": "header", "type": "string" } ] }, "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// 99digital - WhatsApp API", "// The apiKey is sent as an 'apiKey' HEADER on every request", "// (collection-level auth) - never inside the body.", "var vars = pm.collectionVariables;", "if (!vars.get('apiKey')) {", " console.warn('[99digital] The \"apiKey\" collection variable is empty - '", " + 'every request will come back with reason 3. Fill it in the '", " + 'collection Variables tab.');", "}", "if (!vars.get('from')) {", " console.warn('[99digital] The \"from\" collection variable (your WhatsApp '", " + 'number, e.g. 972501234567) is empty - every request will come back '", " + 'with reason 2.');", "}", "var raw = (pm.request.body && pm.request.body.raw) || '';", "if (raw.indexOf('{{to}}') !== -1 && !vars.get('to')) {", " console.warn('[99digital] The \"to\" collection variable is empty - this '", " + 'request will come back with reason 4. Put a test phone number in it '", " + '(international format, no +).');", "}" ] } }, { "listen": "test", "script": { "type": "text/javascript", "exec": [ "// 99digital - shared tests + automatic id capture.", "// Only for calls to our API (not for the webhook simulations in folder 5).", "if (pm.request.url.toString().indexOf('/whatsapp/v2/') === -1) { return; }", "", "// Every response is HTTP 200: the real result is the JSON 'status' field.", "pm.test('HTTP 200', function () { pm.response.to.have.status(200); });", "", "var body = null;", "try { body = pm.response.json(); } catch (e) { body = null; }", "if (body === null || typeof body !== 'object') { return; }", "", "// getHistory / getContacts answer with a bare array on success", "if (Array.isArray(body)) {", " pm.test('OK - ' + body.length + ' records', function () { pm.expect(true).to.be.true; });", " return;", "}", "", "if (body.status === 'OK') {", " pm.test('status = OK', function () { pm.expect(body.status).to.eql('OK'); });", " if (body.templateTimeLeft !== undefined) {", " console.log('[99digital] templateTimeLeft = ' + body.templateTimeLeft", " + ' minutes left in the 24h window with ' + body.to);", " }", "} else {", " pm.test('FAIL - reason ' + body.reason, function () {", " pm.expect.fail('The API returned reason ' + body.reason", " + ' - look it up in the reason table of this request.');", " });", "}", "", "// --- capture the unique of the last send so 'quote your own message' works ---", "var set = function (key, value) {", " if (value) { pm.collectionVariables.set(key, String(value)); }", "};", "if (body.status === 'OK' && body.unique && body.reaction === undefined) {", " set('last_unique', body.unique);", "}", "if (body.status === 'OK' && Array.isArray(body.destinations)) {", " var first = body.destinations.filter(function (d) { return d.unique; })[0];", " if (first) { set('last_unique', first.unique); }", "}" ] } } ], "variable": [ { "key": "base_url", "value": "https://api.99digital.co.il", "type": "string", "description": "API host. Do not add a trailing slash." }, { "key": "apiKey", "value": "", "type": "string", "description": "Your number's apiKey (from onboarding). Sent as the `apiKey` HEADER on every request - the collection does that for you. Treat it as a password: switch this variable to the Postman type 'secret' if you share the collection inside a team workspace." }, { "key": "from", "value": "", "type": "string", "description": "Your WhatsApp API number in international format without `+`, e.g. `972501234567`. It is the `from` of every request." }, { "key": "to", "value": "", "type": "string", "description": "The test recipient: a phone number in international format without `+` (e.g. `972501234567`). For the session messages in folder 1 this person must have written to your number in the last 24 hours. Leave empty until you have one - the pre-request script warns you." }, { "key": "to_user_id", "value": "IL.1605856887361213", "type": "string", "description": "Sample user id (two-letter country, a dot, 16 digits). Customers who hide their phone number behind a WhatsApp username reach you with such an id in the `from_id` of your webhook - replace this with a real one from your webhook before sending." }, { "key": "incoming_unique", "value": "", "type": "string", "description": "The `unique` of an incoming message, copied from your `hook: new` webhook. Used to quote it (`replyTo`) and to react to it (`sendReaction`)." }, { "key": "last_unique", "value": "", "type": "string", "description": "Auto-filled: the `unique` returned by your last successful send. Used by the 'quote your own message' samples - no copy-paste needed." }, { "key": "sample_image_url", "value": "https://storage.99digital.online/samples/hello.png", "type": "string", "description": "A public PNG image (works out of the box). Replace with your own public https image URL when you are ready: jpg/png, up to 5MB." }, { "key": "sample_video_url", "value": "https://storage.99digital.online/samples/meditation.mp4", "type": "string", "description": "A public MP4 video (works out of the box). Your own: mp4, up to 16MB." }, { "key": "sample_document_url", "value": "https://storage.99digital.online/samples/headerSample.pdf", "type": "string", "description": "A public PDF (works out of the box). Your own: pdf/doc/xls/ppt/txt/zip, up to 100MB." }, { "key": "sample_audio_url", "value": "https://example.com/audio.mp3", "type": "string", "description": "REPLACE ME. A public https audio URL (mp3 / ogg / amr / aac, up to 16MB) - the `example.com` default will fail on the webhook." }, { "key": "your_webhook_url", "value": "https://your-server.example.com/99digital/whatsapp-webhook", "type": "string", "description": "Your webhook endpoint. Used by `setWebhook` and by folder *5 - Webhooks*, which POSTs sample payloads at your own server so you can test your handler." }, { "key": "tpl_text", "value": "postman_simple_notice", "type": "string", "description": "Text-only template without variables (createTemplate -> 'Text only')." }, { "key": "tpl_text_vars", "value": "postman_welcome_text", "type": "string", "description": "Text template with 2 body variables (createTemplate -> 'Text with variables')." }, { "key": "tpl_hebrew", "value": "postman_hebrew_welcome", "type": "string", "description": "Hebrew template, 2 variables + 2 quick replies (createTemplate -> 'Hebrew template')." }, { "key": "tpl_image", "value": "postman_offer_image", "type": "string", "description": "Image header + static website button, 2 variables (createTemplate -> 'Image header')." }, { "key": "tpl_document", "value": "postman_invoice_pdf", "type": "string", "description": "Document header + dynamic URL button, 3 variables (createTemplate -> 'Document header')." }, { "key": "tpl_video", "value": "postman_promo_video", "type": "string", "description": "Video header + 3 quick replies, 2 variables (createTemplate -> 'Video header')." }, { "key": "tpl_buttons", "value": "postman_reminder_full", "type": "string", "description": "Call + website + 2 quick replies, 3 variables (createTemplate -> 'Call + website + quick replies')." }, { "key": "tpl_two_sites", "value": "postman_booking_links", "type": "string", "description": "Two website buttons (2nd dynamic) + call, 2 variables (createTemplate -> 'Two website buttons')." }, { "key": "tpl_coupon", "value": "postman_weekend_coupon", "type": "string", "description": "Coupon (copy code) template with image header, 2 variables (createTemplate -> 'Coupon code')." }, { "key": "tpl_auth", "value": "postman_login_code", "type": "string", "description": "Authentication / OTP template (createTemplate -> 'Authentication')." }, { "key": "tpl_carousel", "value": "postman_products_carousel", "type": "string", "description": "Carousel, 3 image cards with dynamic URL + quick reply (createTemplate -> 'Carousel - image cards')." }, { "key": "tpl_carousel_video", "value": "postman_video_carousel", "type": "string", "description": "Carousel, 2 video cards with two quick replies (createTemplate -> 'Carousel - video cards')." }, { "key": "coupon_expiration", "value": "", "type": "string", "description": "UNIX seconds (UTC) - set automatically to now + 7 days by the coupon samples." }, { "key": "otp_code", "value": "", "type": "string", "description": "Random 6-digit code - set automatically by the authentication samples." } ], "item": [ { "name": "1 - Messaging (inside the 24-hour window)", "description": "Everything in this folder is a **session message**: it can be sent only while the customer's 24-hour window is open, i.e. they wrote to your number within the last 24 hours (their every message restarts the clock). Outside the window every endpoint here returns **reason 7** - switch to a template (folder *2*).\n\nSession messages are free of WhatsApp charges, unlimited inside the window, and go to **individuals only** (no groups).\n\nAll sends are **asynchronous**: `OK` + `unique` now, delivery statuses on your webhook later (folder *5*). `templateTimeLeft` in every response tells you how many minutes remain before a template is required; `getTimers` (folder 3) gives the same number without sending anything.\n\nRate limits: 80 messages per second per number (20 for coexistence numbers), at most 10 messages per minute to the same customer.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.", "item": [ { "name": "sendMessage", "description": "`POST /whatsapp/v2/sendMessage` - a plain text message.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.", "item": [ { "name": "Text message", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "The minimal send: `from`, `to`, `body`.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Phone (international, no `+`) or user id -> else 4 |\n| `body` | yes | The text, up to 4096 chars. Empty -> 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request back as `originalRequest` |\n\nLink previews are not generated - a URL in the text is delivered as plain text.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "The minimal send: `from`, `to`, `body`.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Phone (international, no `+`) or user id -> else 4 |\n| `body` | yes | The text, up to 4096 chars. Empty -> 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request back as `originalRequest` |\n\nLink previews are not generated - a URL in the text is delivered as plain text.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "The minimal send: `from`, `to`, `body`.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Phone (international, no `+`) or user id -> else 4 |\n| `body` | yes | The text, up to 4096 chars. Empty -> 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request back as `originalRequest` |\n\nLink previews are not generated - a URL in the text is delivered as plain text.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - wrong apiKey header (reason 3)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "The minimal send: `from`, `to`, `body`.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Phone (international, no `+`) or user id -> else 4 |\n| `body` | yes | The text, up to 4096 chars. Empty -> 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request back as `originalRequest` |\n\nLink previews are not generated - a URL in the text is delivered as plain text.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 3\n}" }, { "name": "Failure - invalid `to` (reason 4)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Hi! Thanks for writing to us. How can we help today?\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "The minimal send: `from`, `to`, `body`.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Phone (international, no `+`) or user id -> else 4 |\n| `body` | yes | The text, up to 4096 chars. Empty -> 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request back as `originalRequest` |\n\nLink previews are not generated - a URL in the text is delivered as plain text.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 4\n}" } ] }, { "name": "Multi-line text with formatting", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"*Order #4711 confirmed* ✅\\n\\nPickup: _today until 18:00_\\nAddress: Herzl 1, Tel Aviv\\n~Delivery fee 20 NIS~ Free delivery this week!\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "Use real line breaks inside the JSON string (`\\n`). WhatsApp renders `*bold*`, `_italic_`, `~strikethrough~` and ```` ```monospace``` ````; emojis are plain UTF-8." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"*Order #4711 confirmed* ✅\\n\\nPickup: _today until 18:00_\\nAddress: Herzl 1, Tel Aviv\\n~Delivery fee 20 NIS~ Free delivery this week!\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "Use real line breaks inside the JSON string (`\\n`). WhatsApp renders `*bold*`, `_italic_`, `~strikethrough~` and ```` ```monospace``` ````; emojis are plain UTF-8." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"*Order #4711 confirmed* ✅\\n\\nPickup: _today until 18:00_\\nAddress: Herzl 1, Tel Aviv\\n~Delivery fee 20 NIS~ Free delivery this week!\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Quote an incoming message (replyTo)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Yes, that item is in stock.\",\n \"replyTo\": \"{{incoming_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`replyTo` = the `unique` of the customer message you are answering, exactly as it arrived in your `hook: new` webhook. The customer sees their message quoted above yours. Fill `{{incoming_unique}}` in the Variables tab first.\n\n`replyTo` quotes a message above yours: pass the `unique` of an incoming message (from your `hook: new` webhook) or the `unique` of one of your own sends. Optional; an unknown id makes WhatsApp fail the message on the webhook." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Yes, that item is in stock.\",\n \"replyTo\": \"{{incoming_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`replyTo` = the `unique` of the customer message you are answering, exactly as it arrived in your `hook: new` webhook. The customer sees their message quoted above yours. Fill `{{incoming_unique}}` in the Variables tab first.\n\n`replyTo` quotes a message above yours: pass the `unique` of an incoming message (from your `hook: new` webhook) or the `unique` of one of your own sends. Optional; an unknown id makes WhatsApp fail the message on the webhook." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Yes, that item is in stock.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Quote your own previous message", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Small correction to the message above: pickup is until 19:00.\",\n \"replyTo\": \"{{last_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`replyTo` also accepts the `unique` of one of **your** sends. The collection stores the `unique` of your last successful send in `{{last_unique}}`, so run any send first and then this request." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Small correction to the message above: pickup is until 19:00.\",\n \"replyTo\": \"{{last_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`replyTo` also accepts the `unique` of one of **your** sends. The collection stores the `unique` of your last successful send in `{{last_unique}}`, so run any send first and then this request." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Small correction to the message above: pickup is until 19:00.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Send to a user id (hidden phone number)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"body\": \"Hi! We received your message and will get back to you shortly.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "Customers who hide their number behind a WhatsApp username appear in your webhook with `from_id` = `IL.1605856887361213` and `phone: null`. Use that id as `to` - the same 24-hour rule applies. You cannot address a `@username` directly." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"body\": \"Hi! We received your message and will get back to you shortly.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "Customers who hide their number behind a WhatsApp username appear in your webhook with `from_id` = `IL.1605856887361213` and `phone: null`. Use that id as `to` - the same 24-hour rule applies. You cannot address a `@username` directly." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Hi! We received your message and will get back to you shortly.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"IL.1605856887361213\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "With showRequest (debug echo)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Testing the echo\",\n \"showRequest\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`showRequest: 1` adds `originalRequest` to the response - the request as we understood it (without `apiKey`, empty fields removed). Handy while integrating." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Testing the echo\",\n \"showRequest\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMessage", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMessage" ] }, "description": "`showRequest: 1` adds `originalRequest` to the response - the request as we understood it (without `apiKey`, empty fields removed). Handy while integrating." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Testing the echo\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1,\n \"originalRequest\": {\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Testing the echo\"\n }\n}" } ] } ] }, { "name": "sendFile", "description": "`POST /whatsapp/v2/sendFile` - image, video, audio or document by URL, with an optional caption.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n> Media is always a **public https URL that WhatsApp downloads from your server**: no login, the right `Content-Type`, and a real file extension in the path. The `{{sample_*_url}}` variables point at small public sample files that work out of the box - replace them with your own when you are ready. If your server blocks downloads from WhatsApp's data centres, add `localStorage: 1` and we fetch and upload the file ourselves.", "item": [ { "name": "Image with caption", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Here is the photo you asked for 📸\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | **The file URL** (public https). Missing / not a URL -> 5 |\n| `caption` | no | Text under the media, up to 1024 chars. Ignored for audio |\n| `fileName` | no | Documents only: the name shown in the chat, **without** extension (we add the real one) |\n| `localStorage` | no | `1` = we download and upload the file ourselves (image / video / document) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe media type is taken from the **file extension in the URL path** (query strings are fine, `…/photo.jpg?sig=abc` works):\n\n| Type | Extensions | Max size |\n|---|---|---|\n| image | jpg, jpeg, png | 5MB |\n| video | mp4, 3gpp | 16MB |\n| audio | mp3, ogg, amr, aac, wav | 16MB (no caption) |\n| document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip - and any other extension, including gif | 100MB |\n\nIf the URL has no extension we ask your server (`HEAD`) for the `Content-Type` / `Content-Disposition` and decide from that. Animated gif is delivered as a document; stickers are not supported.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty or not an absolute http(s) URL |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Here is the photo you asked for 📸\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | **The file URL** (public https). Missing / not a URL -> 5 |\n| `caption` | no | Text under the media, up to 1024 chars. Ignored for audio |\n| `fileName` | no | Documents only: the name shown in the chat, **without** extension (we add the real one) |\n| `localStorage` | no | `1` = we download and upload the file ourselves (image / video / document) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe media type is taken from the **file extension in the URL path** (query strings are fine, `…/photo.jpg?sig=abc` works):\n\n| Type | Extensions | Max size |\n|---|---|---|\n| image | jpg, jpeg, png | 5MB |\n| video | mp4, 3gpp | 16MB |\n| audio | mp3, ogg, amr, aac, wav | 16MB (no caption) |\n| document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip - and any other extension, including gif | 100MB |\n\nIf the URL has no extension we ask your server (`HEAD`) for the `Content-Type` / `Content-Disposition` and decide from that. Animated gif is delivered as a document; stickers are not supported.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty or not an absolute http(s) URL |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://storage.99digital.online/samples/hello.png\",\n \"caption\": \"Here is the photo you asked for 📸\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Here is the photo you asked for 📸\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | **The file URL** (public https). Missing / not a URL -> 5 |\n| `caption` | no | Text under the media, up to 1024 chars. Ignored for audio |\n| `fileName` | no | Documents only: the name shown in the chat, **without** extension (we add the real one) |\n| `localStorage` | no | `1` = we download and upload the file ourselves (image / video / document) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe media type is taken from the **file extension in the URL path** (query strings are fine, `…/photo.jpg?sig=abc` works):\n\n| Type | Extensions | Max size |\n|---|---|---|\n| image | jpg, jpeg, png | 5MB |\n| video | mp4, 3gpp | 16MB |\n| audio | mp3, ogg, amr, aac, wav | 16MB (no caption) |\n| document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip - and any other extension, including gif | 100MB |\n\nIf the URL has no extension we ask your server (`HEAD`) for the `Content-Type` / `Content-Disposition` and decide from that. Animated gif is delivered as a document; stickers are not supported.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty or not an absolute http(s) URL |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - `body` is not a URL (reason 5)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Here is the photo you asked for 📸\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | **The file URL** (public https). Missing / not a URL -> 5 |\n| `caption` | no | Text under the media, up to 1024 chars. Ignored for audio |\n| `fileName` | no | Documents only: the name shown in the chat, **without** extension (we add the real one) |\n| `localStorage` | no | `1` = we download and upload the file ourselves (image / video / document) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe media type is taken from the **file extension in the URL path** (query strings are fine, `…/photo.jpg?sig=abc` works):\n\n| Type | Extensions | Max size |\n|---|---|---|\n| image | jpg, jpeg, png | 5MB |\n| video | mp4, 3gpp | 16MB |\n| audio | mp3, ogg, amr, aac, wav | 16MB (no caption) |\n| document | pdf, doc, docx, xls, xlsx, ppt, pptx, txt, csv, zip - and any other extension, including gif | 100MB |\n\nIf the URL has no extension we ask your server (`HEAD`) for the `Content-Type` / `Content-Disposition` and decide from that. Animated gif is delivered as a document; stickers are not supported.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty or not an absolute http(s) URL |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 5\n}" } ] }, { "name": "Video with caption", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_video_url}}\",\n \"caption\": \"A short demo of the product\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "mp4 (H.264 + AAC) up to 16MB. WhatsApp shows the caption under the player." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_video_url}}\",\n \"caption\": \"A short demo of the product\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "mp4 (H.264 + AAC) up to 16MB. WhatsApp shows the caption under the player." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://storage.99digital.online/samples/meditation.mp4\",\n \"caption\": \"A short demo of the product\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Audio / voice note", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_audio_url}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "mp3 / ogg / amr / aac / wav up to 16MB, shown as a playable audio bubble. Audio has **no caption** - a `caption` you send is dropped. Replace `{{sample_audio_url}}` with a real public file first." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_audio_url}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "mp3 / ogg / amr / aac / wav up to 16MB, shown as a playable audio bubble. Audio has **no caption** - a `caption` you send is dropped. Replace `{{sample_audio_url}}` with a real public file first." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://example.com/audio.mp3\",\n \"caption\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Document (PDF) with file name", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_document_url}}\",\n \"fileName\": \"Invoice 4711\",\n \"caption\": \"Your invoice for August is attached.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "`fileName` is what the customer sees on the attachment (extension added automatically from the URL, here `.pdf`). Without it we use the file name from the URL path. Up to 100MB." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_document_url}}\",\n \"fileName\": \"Invoice 4711\",\n \"caption\": \"Your invoice for August is attached.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "`fileName` is what the customer sees on the attachment (extension added automatically from the URL, here `.pdf`). Without it we use the file name from the URL path. Up to 100MB." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://storage.99digital.online/samples/headerSample.pdf\",\n \"caption\": \"Your invoice for August is attached.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Document - Excel / Word / any file", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"https://www.example.com/files/price-list.xlsx\",\n \"fileName\": \"Price list September 2026\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Anything that is not image / video / audio is delivered as a document with its real extension: xlsx, docx, pptx, csv, txt, zip... Replace the `example.com` URL with a public file of yours." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"https://www.example.com/files/price-list.xlsx\",\n \"fileName\": \"Price list September 2026\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Anything that is not image / video / audio is delivered as a document with its real extension: xlsx, docx, pptx, csv, txt, zip... Replace the `example.com` URL with a public file of yours." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://www.example.com/files/price-list.xlsx\",\n \"caption\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Image - localStorage (we upload the media)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Uploaded by 99digital first\",\n \"localStorage\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Some servers (WAF, geo-blocking, private CDNs) refuse WhatsApp's download. With `localStorage: 1` **we** download the file first and upload it to WhatsApp, then send the resulting media id instead of your link. Works for image (jpg/png/gif), video and document types; audio always goes by link. If our upload fails we fall back to your link." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"Uploaded by 99digital first\",\n \"localStorage\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Some servers (WAF, geo-blocking, private CDNs) refuse WhatsApp's download. With `localStorage: 1` **we** download the file first and upload it to WhatsApp, then send the resulting media id instead of your link. Works for image (jpg/png/gif), video and document types; audio always goes by link. If our upload fails we fall back to your link." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://storage.99digital.online/samples/hello.png\",\n \"caption\": \"Uploaded by 99digital first\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Quote an incoming message (replyTo)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"This one?\",\n \"replyTo\": \"{{incoming_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Same `replyTo` as sendMessage: the customer's `unique` from your webhook, or `{{last_unique}}` for your own last message.\n\n`replyTo` quotes a message above yours: pass the `unique` of an incoming message (from your `hook: new` webhook) or the `unique` of one of your own sends. Optional; an unknown id makes WhatsApp fail the message on the webhook." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"{{sample_image_url}}\",\n \"caption\": \"This one?\",\n \"replyTo\": \"{{incoming_unique}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendFile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendFile" ] }, "description": "Same `replyTo` as sendMessage: the customer's `unique` from your webhook, or `{{last_unique}}` for your own last message.\n\n`replyTo` quotes a message above yours: pass the `unique` of an incoming message (from your `hook: new` webhook) or the `unique` of one of your own sends. Optional; an unknown id makes WhatsApp fail the message on the webhook." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"https://storage.99digital.online/samples/hello.png\",\n \"caption\": \"This one?\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] } ] }, { "name": "sendButtons", "description": "`POST /whatsapp/v2/sendButtons` - text with up to **3 reply buttons**, optionally with an image / video / document header and a footer; or a single **call-to-action button** (link, call or e-mail).\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.", "item": [ { "name": "Three reply buttons with ids", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button1_id\": \"TRACK_ORDER\",\n \"button2\": \"Talk to an agent\",\n \"button2_id\": \"AGENT\",\n \"button3\": \"Opening hours\",\n \"button3_id\": \"HOURS\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 1` = no header, just text + buttons. Up to 3 reply buttons, 20 chars each. Give every button your own `buttonN_id` and branch on it when the tap arrives (`caption` of the `type: button` webhook).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | yes | 1 none, 2 image, 3 video, 4 document -> else 9 |\n| `headerURL` | `header` 2/3/4 | Public https media URL -> missing 13 |\n| `body` | yes | Message text, up to 1024 chars -> empty 5 |\n| `footer` | no | Small grey text, up to 60 bytes (60 Latin / ~30 Hebrew characters) -> 10 |\n| `button1` | yes | Button label, up to 20 chars -> 11 |\n| `button2`, `button3` | no | Labels, up to 20 chars -> 12 |\n| `button1_id`, `button2_id`, `button3_id` | no | Your ids for the taps: letters, digits, `_`, `-`, up to 256 chars, unique. Default `1`, `2`, `3` -> 16 |\n| `buttonExternal` | no | Turns the message into ONE call-to-action button: an `https://` URL, digits only (phone) or an e-mail -> 14. `button1` becomes its label, `button2`/`button3` are ignored |\n| `fileName` | no | `header` 4: document name shown in the chat (no extension) |\n| `localStorage` | no | `1` = we download and upload the header media ourselves (not with `buttonExternal`) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer taps a reply button you receive a `hook: new` webhook with `type: button`, `body` = the label and `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` missing or not 1-4 |\n| 10 | `footer` longer than 60 bytes |\n| 11 | `button1` missing or longer than 20 chars |\n| 12 | `button2` / `button3` longer than 20 chars |\n| 13 | `headerURL` missing while `header` is 2, 3 or 4 |\n| 14 | `buttonExternal` is not a URL, a phone number or an e-mail |\n| 16 | Button ids invalid, duplicated or longer than 256 chars |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button1_id\": \"TRACK_ORDER\",\n \"button2\": \"Talk to an agent\",\n \"button2_id\": \"AGENT\",\n \"button3\": \"Opening hours\",\n \"button3_id\": \"HOURS\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 1` = no header, just text + buttons. Up to 3 reply buttons, 20 chars each. Give every button your own `buttonN_id` and branch on it when the tap arrives (`caption` of the `type: button` webhook).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | yes | 1 none, 2 image, 3 video, 4 document -> else 9 |\n| `headerURL` | `header` 2/3/4 | Public https media URL -> missing 13 |\n| `body` | yes | Message text, up to 1024 chars -> empty 5 |\n| `footer` | no | Small grey text, up to 60 bytes (60 Latin / ~30 Hebrew characters) -> 10 |\n| `button1` | yes | Button label, up to 20 chars -> 11 |\n| `button2`, `button3` | no | Labels, up to 20 chars -> 12 |\n| `button1_id`, `button2_id`, `button3_id` | no | Your ids for the taps: letters, digits, `_`, `-`, up to 256 chars, unique. Default `1`, `2`, `3` -> 16 |\n| `buttonExternal` | no | Turns the message into ONE call-to-action button: an `https://` URL, digits only (phone) or an e-mail -> 14. `button1` becomes its label, `button2`/`button3` are ignored |\n| `fileName` | no | `header` 4: document name shown in the chat (no extension) |\n| `localStorage` | no | `1` = we download and upload the header media ourselves (not with `buttonExternal`) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer taps a reply button you receive a `hook: new` webhook with `type: button`, `body` = the label and `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` missing or not 1-4 |\n| 10 | `footer` longer than 60 bytes |\n| 11 | `button1` missing or longer than 20 chars |\n| 12 | `button2` / `button3` longer than 20 chars |\n| 13 | `headerURL` missing while `header` is 2, 3 or 4 |\n| 14 | `buttonExternal` is not a URL, a phone number or an e-mail |\n| 16 | Button ids invalid, duplicated or longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button2\": \"Talk to an agent\",\n \"button3\": \"Opening hours\",\n \"buttonExternal\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button1_id\": \"TRACK_ORDER\",\n \"button2\": \"Talk to an agent\",\n \"button2_id\": \"AGENT\",\n \"button3\": \"Opening hours\",\n \"button3_id\": \"HOURS\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 1` = no header, just text + buttons. Up to 3 reply buttons, 20 chars each. Give every button your own `buttonN_id` and branch on it when the tap arrives (`caption` of the `type: button` webhook).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | yes | 1 none, 2 image, 3 video, 4 document -> else 9 |\n| `headerURL` | `header` 2/3/4 | Public https media URL -> missing 13 |\n| `body` | yes | Message text, up to 1024 chars -> empty 5 |\n| `footer` | no | Small grey text, up to 60 bytes (60 Latin / ~30 Hebrew characters) -> 10 |\n| `button1` | yes | Button label, up to 20 chars -> 11 |\n| `button2`, `button3` | no | Labels, up to 20 chars -> 12 |\n| `button1_id`, `button2_id`, `button3_id` | no | Your ids for the taps: letters, digits, `_`, `-`, up to 256 chars, unique. Default `1`, `2`, `3` -> 16 |\n| `buttonExternal` | no | Turns the message into ONE call-to-action button: an `https://` URL, digits only (phone) or an e-mail -> 14. `button1` becomes its label, `button2`/`button3` are ignored |\n| `fileName` | no | `header` 4: document name shown in the chat (no extension) |\n| `localStorage` | no | `1` = we download and upload the header media ourselves (not with `buttonExternal`) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer taps a reply button you receive a `hook: new` webhook with `type: button`, `body` = the label and `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` missing or not 1-4 |\n| 10 | `footer` longer than 60 bytes |\n| 11 | `button1` missing or longer than 20 chars |\n| 12 | `button2` / `button3` longer than 20 chars |\n| 13 | `headerURL` missing while `header` is 2, 3 or 4 |\n| 14 | `buttonExternal` is not a URL, a phone number or an e-mail |\n| 16 | Button ids invalid, duplicated or longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - button1 missing / too long (reason 11)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button1_id\": \"TRACK_ORDER\",\n \"button2\": \"Talk to an agent\",\n \"button2_id\": \"AGENT\",\n \"button3\": \"Opening hours\",\n \"button3_id\": \"HOURS\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 1` = no header, just text + buttons. Up to 3 reply buttons, 20 chars each. Give every button your own `buttonN_id` and branch on it when the tap arrives (`caption` of the `type: button` webhook).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | yes | 1 none, 2 image, 3 video, 4 document -> else 9 |\n| `headerURL` | `header` 2/3/4 | Public https media URL -> missing 13 |\n| `body` | yes | Message text, up to 1024 chars -> empty 5 |\n| `footer` | no | Small grey text, up to 60 bytes (60 Latin / ~30 Hebrew characters) -> 10 |\n| `button1` | yes | Button label, up to 20 chars -> 11 |\n| `button2`, `button3` | no | Labels, up to 20 chars -> 12 |\n| `button1_id`, `button2_id`, `button3_id` | no | Your ids for the taps: letters, digits, `_`, `-`, up to 256 chars, unique. Default `1`, `2`, `3` -> 16 |\n| `buttonExternal` | no | Turns the message into ONE call-to-action button: an `https://` URL, digits only (phone) or an e-mail -> 14. `button1` becomes its label, `button2`/`button3` are ignored |\n| `fileName` | no | `header` 4: document name shown in the chat (no extension) |\n| `localStorage` | no | `1` = we download and upload the header media ourselves (not with `buttonExternal`) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer taps a reply button you receive a `hook: new` webhook with `type: button`, `body` = the label and `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` missing or not 1-4 |\n| 10 | `footer` longer than 60 bytes |\n| 11 | `button1` missing or longer than 20 chars |\n| 12 | `button2` / `button3` longer than 20 chars |\n| 13 | `headerURL` missing while `header` is 2, 3 or 4 |\n| 14 | `buttonExternal` is not a URL, a phone number or an e-mail |\n| 16 | Button ids invalid, duplicated or longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 11\n}" }, { "name": "Failure - duplicate button ids (reason 16)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"How can we help you today?\",\n \"footer\": \"Reply anytime, we are here 08:00-20:00\",\n \"button1\": \"Track my order\",\n \"button1_id\": \"TRACK_ORDER\",\n \"button2\": \"Talk to an agent\",\n \"button2_id\": \"AGENT\",\n \"button3\": \"Opening hours\",\n \"button3_id\": \"HOURS\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 1` = no header, just text + buttons. Up to 3 reply buttons, 20 chars each. Give every button your own `buttonN_id` and branch on it when the tap arrives (`caption` of the `type: button` webhook).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | yes | 1 none, 2 image, 3 video, 4 document -> else 9 |\n| `headerURL` | `header` 2/3/4 | Public https media URL -> missing 13 |\n| `body` | yes | Message text, up to 1024 chars -> empty 5 |\n| `footer` | no | Small grey text, up to 60 bytes (60 Latin / ~30 Hebrew characters) -> 10 |\n| `button1` | yes | Button label, up to 20 chars -> 11 |\n| `button2`, `button3` | no | Labels, up to 20 chars -> 12 |\n| `button1_id`, `button2_id`, `button3_id` | no | Your ids for the taps: letters, digits, `_`, `-`, up to 256 chars, unique. Default `1`, `2`, `3` -> 16 |\n| `buttonExternal` | no | Turns the message into ONE call-to-action button: an `https://` URL, digits only (phone) or an e-mail -> 14. `button1` becomes its label, `button2`/`button3` are ignored |\n| `fileName` | no | `header` 4: document name shown in the chat (no extension) |\n| `localStorage` | no | `1` = we download and upload the header media ourselves (not with `buttonExternal`) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer taps a reply button you receive a `hook: new` webhook with `type: button`, `body` = the label and `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` missing or not 1-4 |\n| 10 | `footer` longer than 60 bytes |\n| 11 | `button1` missing or longer than 20 chars |\n| 12 | `button2` / `button3` longer than 20 chars |\n| 13 | `headerURL` missing while `header` is 2, 3 or 4 |\n| 14 | `buttonExternal` is not a URL, a phone number or an e-mail |\n| 16 | Button ids invalid, duplicated or longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 16\n}" } ] }, { "name": "Image header + two buttons", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"body\": \"This is the model you asked about. Shall we reserve one for you?\",\n \"button1\": \"Reserve it\",\n \"button1_id\": \"RESERVE\",\n \"button2\": \"Show me more\",\n \"button2_id\": \"MORE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 2` + `headerURL` puts a picture above the text (jpg/png, up to 5MB, public https URL).\n\n> Media is always a **public https URL that WhatsApp downloads from your server**: no login, the right `Content-Type`, and a real file extension in the path. The `{{sample_*_url}}` variables point at small public sample files that work out of the box - replace them with your own when you are ready. If your server blocks downloads from WhatsApp's data centres, add `localStorage: 1` and we fetch and upload the file ourselves." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"body\": \"This is the model you asked about. Shall we reserve one for you?\",\n \"button1\": \"Reserve it\",\n \"button1_id\": \"RESERVE\",\n \"button2\": \"Show me more\",\n \"button2_id\": \"MORE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 2` + `headerURL` puts a picture above the text (jpg/png, up to 5MB, public https URL).\n\n> Media is always a **public https URL that WhatsApp downloads from your server**: no login, the right `Content-Type`, and a real file extension in the path. The `{{sample_*_url}}` variables point at small public sample files that work out of the box - replace them with your own when you are ready. If your server blocks downloads from WhatsApp's data centres, add `localStorage: 1` and we fetch and upload the file ourselves." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 2,\n \"body\": \"This is the model you asked about. Shall we reserve one for you?\",\n \"footer\": \"\",\n \"button1\": \"Reserve it\",\n \"button2\": \"Show me more\",\n \"button3\": \"\",\n \"buttonExternal\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Video header", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 3,\n \"headerURL\": \"{{sample_video_url}}\",\n \"body\": \"Watch the 30-second setup guide. Did it work?\",\n \"button1\": \"Yes, all good\",\n \"button1_id\": \"OK\",\n \"button2\": \"I need help\",\n \"button2_id\": \"HELP\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 3` = video header (mp4 up to 16MB)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 3,\n \"headerURL\": \"{{sample_video_url}}\",\n \"body\": \"Watch the 30-second setup guide. Did it work?\",\n \"button1\": \"Yes, all good\",\n \"button1_id\": \"OK\",\n \"button2\": \"I need help\",\n \"button2_id\": \"HELP\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 3` = video header (mp4 up to 16MB)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 3,\n \"body\": \"Watch the 30-second setup guide. Did it work?\",\n \"footer\": \"\",\n \"button1\": \"Yes, all good\",\n \"button2\": \"I need help\",\n \"button3\": \"\",\n \"buttonExternal\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Document header + file name", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 4,\n \"headerURL\": \"{{sample_document_url}}\",\n \"fileName\": \"Quote 2026-0917\",\n \"body\": \"Please find your quote attached. It is valid for 14 days.\",\n \"footer\": \"Prices include VAT\",\n \"button1\": \"Approve quote\",\n \"button1_id\": \"APPROVE\",\n \"button2\": \"Request changes\",\n \"button2_id\": \"CHANGES\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 4` = document header (pdf and office files up to 100MB). `fileName` is the attachment name the customer sees; the extension is added from the URL." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 4,\n \"headerURL\": \"{{sample_document_url}}\",\n \"fileName\": \"Quote 2026-0917\",\n \"body\": \"Please find your quote attached. It is valid for 14 days.\",\n \"footer\": \"Prices include VAT\",\n \"button1\": \"Approve quote\",\n \"button1_id\": \"APPROVE\",\n \"button2\": \"Request changes\",\n \"button2_id\": \"CHANGES\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`header: 4` = document header (pdf and office files up to 100MB). `fileName` is the attachment name the customer sees; the extension is added from the URL." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 4,\n \"body\": \"Please find your quote attached. It is valid for 14 days.\",\n \"footer\": \"Prices include VAT\",\n \"button1\": \"Approve quote\",\n \"button2\": \"Request changes\",\n \"button3\": \"\",\n \"buttonExternal\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Call-to-action: open a link", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"body\": \"Your personal offer is ready - 20% off until Sunday.\",\n \"footer\": \"Offer code applied automatically\",\n \"button1\": \"Open my offer\",\n \"buttonExternal\": \"https://www.example.com/offer/4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`buttonExternal` with an `https://` URL renders **one** call-to-action button that opens the link; `button1` is its label. Reply buttons and `buttonExternal` cannot be mixed (`button2`/`button3` are ignored)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"body\": \"Your personal offer is ready - 20% off until Sunday.\",\n \"footer\": \"Offer code applied automatically\",\n \"button1\": \"Open my offer\",\n \"buttonExternal\": \"https://www.example.com/offer/4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "`buttonExternal` with an `https://` URL renders **one** call-to-action button that opens the link; `button1` is its label. Reply buttons and `buttonExternal` cannot be mixed (`button2`/`button3` are ignored)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 2,\n \"body\": \"Your personal offer is ready - 20% off until Sunday.\",\n \"footer\": \"Offer code applied automatically\",\n \"button1\": \"Open my offer\",\n \"button2\": \"\",\n \"button3\": \"\",\n \"buttonExternal\": \"https://www.example.com/offer/4711\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Call-to-action: call us", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"Prefer to talk? Our team is available now.\",\n \"button1\": \"Call us\",\n \"buttonExternal\": \"97231234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "Digits only in `buttonExternal` = a phone number; tapping the button starts a call. International format without `+`." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"Prefer to talk? Our team is available now.\",\n \"button1\": \"Call us\",\n \"buttonExternal\": \"97231234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "Digits only in `buttonExternal` = a phone number; tapping the button starts a call. International format without `+`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 1,\n \"body\": \"Prefer to talk? Our team is available now.\",\n \"footer\": \"\",\n \"button1\": \"Call us\",\n \"button2\": \"\",\n \"button3\": \"\",\n \"buttonExternal\": \"97231234567\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Call-to-action: send an e-mail", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"For invoices and receipts please write to our billing desk.\",\n \"button1\": \"Email billing\",\n \"buttonExternal\": \"billing@example.com\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "An e-mail address in `buttonExternal` opens the customer's mail app with the address filled in." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 1,\n \"body\": \"For invoices and receipts please write to our billing desk.\",\n \"button1\": \"Email billing\",\n \"buttonExternal\": \"billing@example.com\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "An e-mail address in `buttonExternal` opens the customer's mail app with the address filled in." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 1,\n \"body\": \"For invoices and receipts please write to our billing desk.\",\n \"footer\": \"\",\n \"button1\": \"Email billing\",\n \"button2\": \"\",\n \"button3\": \"\",\n \"buttonExternal\": \"billing@example.com\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Image header - localStorage (we upload the media)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"localStorage\": 1,\n \"body\": \"Is this the item you meant?\",\n \"button1\": \"Yes\",\n \"button1_id\": \"YES\",\n \"button2\": \"No\",\n \"button2_id\": \"NO\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "For media servers that block WhatsApp's download: with `localStorage: 1` we fetch the header file and upload it to WhatsApp ourselves before sending. Not available together with `buttonExternal`; if our upload fails we fall back to your link." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": 2,\n \"headerURL\": \"{{sample_image_url}}\",\n \"localStorage\": 1,\n \"body\": \"Is this the item you meant?\",\n \"button1\": \"Yes\",\n \"button1_id\": \"YES\",\n \"button2\": \"No\",\n \"button2_id\": \"NO\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendButtons", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendButtons" ] }, "description": "For media servers that block WhatsApp's download: with `localStorage: 1` we fetch the header file and upload it to WhatsApp ourselves before sending. Not available together with `buttonExternal`; if our upload fails we fall back to your link." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": 2,\n \"body\": \"Is this the item you meant?\",\n \"footer\": \"\",\n \"button1\": \"Yes\",\n \"button2\": \"No\",\n \"button3\": \"\",\n \"buttonExternal\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] } ] }, { "name": "sendList", "description": "`POST /whatsapp/v2/sendList` - a message with a button that opens a **menu of up to 10 options**.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.", "item": [ { "name": "Simple list (3 options)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": \"Customer service\",\n \"body\": \"Please choose a department and we will connect you.\",\n \"footer\": \"Available Sun-Thu 08:00-18:00\",\n \"buttonText\": \"Choose department\",\n \"itemTitle1\": \"Sales\",\n \"itemDescription1\": \"Quotes, orders and pricing\",\n \"itemID1\": \"SALES\",\n \"itemTitle2\": \"Support\",\n \"itemDescription2\": \"Help with an existing product\",\n \"itemID2\": \"SUPPORT\",\n \"itemTitle3\": \"Billing\",\n \"itemDescription3\": \"Invoices and payments\",\n \"itemID3\": \"BILLING\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | no | Title line, up to 60 chars (text only) -> 9 |\n| `body` | yes | Text, up to 1024 chars -> empty 5 |\n| `footer` | no | Up to 60 chars -> 10 |\n| `buttonText` | yes | Label of the button that opens the menu, up to 20 chars -> 11 |\n| `itemTitle1` | yes | First option, up to 24 chars -> 12 |\n| `itemTitle2`..`itemTitle10` | no | More options, up to 24 chars each -> 13 |\n| `itemDescription1`..`10` | no | Grey sub-line per option, up to 72 chars -> 14 |\n| `itemID1`..`itemID10` | no | Your id per option: letters, digits, `_`, `-`, up to 200 chars, unique. Default = the position (`1`..`10`) -> 16 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer picks an option you receive a `hook: new` webhook with `type: list`, `body` = the option title and `caption` = its id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` longer than 60 chars |\n| 10 | `footer` longer than 60 chars |\n| 11 | `buttonText` missing or longer than 20 chars |\n| 12 | `itemTitle1` missing or longer than 24 chars |\n| 13 | An `itemTitleN` is longer than 24 chars |\n| 14 | An `itemDescriptionN` is longer than 72 chars |\n| 16 | Item ids invalid, duplicated, too long, or given for an empty item |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": \"Customer service\",\n \"body\": \"Please choose a department and we will connect you.\",\n \"footer\": \"Available Sun-Thu 08:00-18:00\",\n \"buttonText\": \"Choose department\",\n \"itemTitle1\": \"Sales\",\n \"itemDescription1\": \"Quotes, orders and pricing\",\n \"itemID1\": \"SALES\",\n \"itemTitle2\": \"Support\",\n \"itemDescription2\": \"Help with an existing product\",\n \"itemID2\": \"SUPPORT\",\n \"itemTitle3\": \"Billing\",\n \"itemDescription3\": \"Invoices and payments\",\n \"itemID3\": \"BILLING\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | no | Title line, up to 60 chars (text only) -> 9 |\n| `body` | yes | Text, up to 1024 chars -> empty 5 |\n| `footer` | no | Up to 60 chars -> 10 |\n| `buttonText` | yes | Label of the button that opens the menu, up to 20 chars -> 11 |\n| `itemTitle1` | yes | First option, up to 24 chars -> 12 |\n| `itemTitle2`..`itemTitle10` | no | More options, up to 24 chars each -> 13 |\n| `itemDescription1`..`10` | no | Grey sub-line per option, up to 72 chars -> 14 |\n| `itemID1`..`itemID10` | no | Your id per option: letters, digits, `_`, `-`, up to 200 chars, unique. Default = the position (`1`..`10`) -> 16 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer picks an option you receive a `hook: new` webhook with `type: list`, `body` = the option title and `caption` = its id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` longer than 60 chars |\n| 10 | `footer` longer than 60 chars |\n| 11 | `buttonText` missing or longer than 20 chars |\n| 12 | `itemTitle1` missing or longer than 24 chars |\n| 13 | An `itemTitleN` is longer than 24 chars |\n| 14 | An `itemDescriptionN` is longer than 72 chars |\n| 16 | Item ids invalid, duplicated, too long, or given for an empty item |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": \"Customer service\",\n \"body\": \"Please choose a department and we will connect you.\",\n \"footer\": \"Available Sun-Thu 08:00-18:00\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": \"Customer service\",\n \"body\": \"Please choose a department and we will connect you.\",\n \"footer\": \"Available Sun-Thu 08:00-18:00\",\n \"buttonText\": \"Choose department\",\n \"itemTitle1\": \"Sales\",\n \"itemDescription1\": \"Quotes, orders and pricing\",\n \"itemID1\": \"SALES\",\n \"itemTitle2\": \"Support\",\n \"itemDescription2\": \"Help with an existing product\",\n \"itemID2\": \"SUPPORT\",\n \"itemTitle3\": \"Billing\",\n \"itemDescription3\": \"Invoices and payments\",\n \"itemID3\": \"BILLING\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | no | Title line, up to 60 chars (text only) -> 9 |\n| `body` | yes | Text, up to 1024 chars -> empty 5 |\n| `footer` | no | Up to 60 chars -> 10 |\n| `buttonText` | yes | Label of the button that opens the menu, up to 20 chars -> 11 |\n| `itemTitle1` | yes | First option, up to 24 chars -> 12 |\n| `itemTitle2`..`itemTitle10` | no | More options, up to 24 chars each -> 13 |\n| `itemDescription1`..`10` | no | Grey sub-line per option, up to 72 chars -> 14 |\n| `itemID1`..`itemID10` | no | Your id per option: letters, digits, `_`, `-`, up to 200 chars, unique. Default = the position (`1`..`10`) -> 16 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer picks an option you receive a `hook: new` webhook with `type: list`, `body` = the option title and `caption` = its id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` longer than 60 chars |\n| 10 | `footer` longer than 60 chars |\n| 11 | `buttonText` missing or longer than 20 chars |\n| 12 | `itemTitle1` missing or longer than 24 chars |\n| 13 | An `itemTitleN` is longer than 24 chars |\n| 14 | An `itemDescriptionN` is longer than 72 chars |\n| 16 | Item ids invalid, duplicated, too long, or given for an empty item |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - buttonText missing (reason 11)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"header\": \"Customer service\",\n \"body\": \"Please choose a department and we will connect you.\",\n \"footer\": \"Available Sun-Thu 08:00-18:00\",\n \"buttonText\": \"Choose department\",\n \"itemTitle1\": \"Sales\",\n \"itemDescription1\": \"Quotes, orders and pricing\",\n \"itemID1\": \"SALES\",\n \"itemTitle2\": \"Support\",\n \"itemDescription2\": \"Help with an existing product\",\n \"itemID2\": \"SUPPORT\",\n \"itemTitle3\": \"Billing\",\n \"itemDescription3\": \"Invoices and payments\",\n \"itemID3\": \"BILLING\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `header` | no | Title line, up to 60 chars (text only) -> 9 |\n| `body` | yes | Text, up to 1024 chars -> empty 5 |\n| `footer` | no | Up to 60 chars -> 10 |\n| `buttonText` | yes | Label of the button that opens the menu, up to 20 chars -> 11 |\n| `itemTitle1` | yes | First option, up to 24 chars -> 12 |\n| `itemTitle2`..`itemTitle10` | no | More options, up to 24 chars each -> 13 |\n| `itemDescription1`..`10` | no | Grey sub-line per option, up to 72 chars -> 14 |\n| `itemID1`..`itemID10` | no | Your id per option: letters, digits, `_`, `-`, up to 200 chars, unique. Default = the position (`1`..`10`) -> 16 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nWhen the customer picks an option you receive a `hook: new` webhook with `type: list`, `body` = the option title and `caption` = its id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 9 | `header` longer than 60 chars |\n| 10 | `footer` longer than 60 chars |\n| 11 | `buttonText` missing or longer than 20 chars |\n| 12 | `itemTitle1` missing or longer than 24 chars |\n| 13 | An `itemTitleN` is longer than 24 chars |\n| 14 | An `itemDescriptionN` is longer than 72 chars |\n| 16 | Item ids invalid, duplicated, too long, or given for an empty item |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 11\n}" } ] }, { "name": "Full list (10 options, no descriptions)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Which day suits you for the delivery?\",\n \"buttonText\": \"Pick a day\",\n \"itemTitle1\": \"Sunday\",\n \"itemID1\": \"DAY_SUN\",\n \"itemTitle2\": \"Monday\",\n \"itemID2\": \"DAY_MON\",\n \"itemTitle3\": \"Tuesday\",\n \"itemID3\": \"DAY_TUE\",\n \"itemTitle4\": \"Wednesday\",\n \"itemID4\": \"DAY_WED\",\n \"itemTitle5\": \"Thursday\",\n \"itemID5\": \"DAY_THU\",\n \"itemTitle6\": \"Friday morning\",\n \"itemID6\": \"DAY_FRI\",\n \"itemTitle7\": \"Next Sunday\",\n \"itemID7\": \"NEXT_SUN\",\n \"itemTitle8\": \"Next Monday\",\n \"itemID8\": \"NEXT_MON\",\n \"itemTitle9\": \"Next Tuesday\",\n \"itemID9\": \"NEXT_TUE\",\n \"itemTitle10\": \"Call me to arrange\",\n \"itemID10\": \"CALL_ME\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "The maximum: 10 options in one list. `header`, `footer` and the descriptions are all optional. Options are shown in the order of their number; an empty `itemTitleN` is skipped." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Which day suits you for the delivery?\",\n \"buttonText\": \"Pick a day\",\n \"itemTitle1\": \"Sunday\",\n \"itemID1\": \"DAY_SUN\",\n \"itemTitle2\": \"Monday\",\n \"itemID2\": \"DAY_MON\",\n \"itemTitle3\": \"Tuesday\",\n \"itemID3\": \"DAY_TUE\",\n \"itemTitle4\": \"Wednesday\",\n \"itemID4\": \"DAY_WED\",\n \"itemTitle5\": \"Thursday\",\n \"itemID5\": \"DAY_THU\",\n \"itemTitle6\": \"Friday morning\",\n \"itemID6\": \"DAY_FRI\",\n \"itemTitle7\": \"Next Sunday\",\n \"itemID7\": \"NEXT_SUN\",\n \"itemTitle8\": \"Next Monday\",\n \"itemID8\": \"NEXT_MON\",\n \"itemTitle9\": \"Next Tuesday\",\n \"itemID9\": \"NEXT_TUE\",\n \"itemTitle10\": \"Call me to arrange\",\n \"itemID10\": \"CALL_ME\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendList" ] }, "description": "The maximum: 10 options in one list. `header`, `footer` and the descriptions are all optional. Options are shown in the order of their number; an empty `itemTitleN` is skipped." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"header\": \"\",\n \"body\": \"Which day suits you for the delivery?\",\n \"footer\": \"\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] } ] }, { "name": "sendCarousel", "description": "`POST /whatsapp/v2/sendCarousel` - a text bubble plus **2-10 swipeable media cards**, each with the same button layout. This is the *session* carousel; for a carousel outside the 24-hour window use a carousel **template** (folder 2).\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n> Media is always a **public https URL that WhatsApp downloads from your server**: no login, the right `Content-Type`, and a real file extension in the path. The `{{sample_*_url}}` variables point at small public sample files that work out of the box - replace them with your own when you are ready.", "item": [ { "name": "Link / call buttons (buttons 1)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Two ways to reach us today:\",\n \"buttons\": 1,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Browse the full catalogue online.\",\n \"card1_buttonExternal\": \"https://www.example.com/catalogue\",\n \"card1_buttonExternalText\": \"Open catalogue\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Or talk to a human - we pick up fast.\",\n \"card2_buttonExternal\": \"97231234567\",\n \"card2_buttonExternalText\": \"Call us\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 1` = one call-to-action per card. Each card decides its own action: an `https://` link, digits (call) or an e-mail.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The text bubble above the cards -> empty 5 |\n| `buttons` | yes | Button layout of **every** card: 1 = one call-to-action (link / call / e-mail), 2 = one reply button, 3 = two reply buttons -> 11 |\n| `cardX_headerLink` | yes per card | `https://` image or video URL (all cards the same kind, detected from the extension) -> 10 / 12 |\n| `cardX_body` | no (all cards or none) | Card text, up to 160 chars and 2 line breaks -> 13 |\n| `cardX_buttonExternal` | `buttons` 1 | URL, digits (phone) or e-mail -> 14 |\n| `cardX_buttonExternalText` | `buttons` 1 | Label, up to 20 chars -> 15 |\n| `cardX_button1` | `buttons` 2/3 | Reply label, up to 20 chars -> 16 |\n| `cardX_button1ID` | no | Your id, up to 256 chars (default `1`) -> 17 |\n| `cardX_button2` | `buttons` 3 | Second reply label, up to 20 chars -> 18 |\n| `cardX_button2ID` | no | Your id (default `2`) -> 19 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nCards are numbered `card1_`..`card10_` without gaps, **2 to 10 cards**. Only the fields of the chosen `buttons` layout may appear (a `card1_button1` on a `buttons: 1` carousel -> 10). Taps on reply buttons arrive as `type: button` webhooks with `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 10 | Cards invalid: fewer than 2 / more than 10, numbering with gaps, a `cardX_headerLink` missing or not https, or fields of another `buttons` layout |\n| 11 | `buttons` missing or not 1-3 |\n| 12 | Cards mix images and videos |\n| 13 | A `cardX_body` is longer than 160 chars / has more than 2 line breaks, or only some cards have a body |\n| 14 | `cardX_buttonExternal` missing or not a URL / phone / e-mail |\n| 15 | `cardX_buttonExternalText` missing or longer than 20 chars |\n| 16 | `cardX_button1` missing or longer than 20 chars |\n| 17 | `cardX_button1ID` longer than 256 chars |\n| 18 | `cardX_button2` missing or longer than 20 chars |\n| 19 | `cardX_button2ID` longer than 256 chars |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Two ways to reach us today:\",\n \"buttons\": 1,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Browse the full catalogue online.\",\n \"card1_buttonExternal\": \"https://www.example.com/catalogue\",\n \"card1_buttonExternalText\": \"Open catalogue\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Or talk to a human - we pick up fast.\",\n \"card2_buttonExternal\": \"97231234567\",\n \"card2_buttonExternalText\": \"Call us\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 1` = one call-to-action per card. Each card decides its own action: an `https://` link, digits (call) or an e-mail.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The text bubble above the cards -> empty 5 |\n| `buttons` | yes | Button layout of **every** card: 1 = one call-to-action (link / call / e-mail), 2 = one reply button, 3 = two reply buttons -> 11 |\n| `cardX_headerLink` | yes per card | `https://` image or video URL (all cards the same kind, detected from the extension) -> 10 / 12 |\n| `cardX_body` | no (all cards or none) | Card text, up to 160 chars and 2 line breaks -> 13 |\n| `cardX_buttonExternal` | `buttons` 1 | URL, digits (phone) or e-mail -> 14 |\n| `cardX_buttonExternalText` | `buttons` 1 | Label, up to 20 chars -> 15 |\n| `cardX_button1` | `buttons` 2/3 | Reply label, up to 20 chars -> 16 |\n| `cardX_button1ID` | no | Your id, up to 256 chars (default `1`) -> 17 |\n| `cardX_button2` | `buttons` 3 | Second reply label, up to 20 chars -> 18 |\n| `cardX_button2ID` | no | Your id (default `2`) -> 19 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nCards are numbered `card1_`..`card10_` without gaps, **2 to 10 cards**. Only the fields of the chosen `buttons` layout may appear (a `card1_button1` on a `buttons: 1` carousel -> 10). Taps on reply buttons arrive as `type: button` webhooks with `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 10 | Cards invalid: fewer than 2 / more than 10, numbering with gaps, a `cardX_headerLink` missing or not https, or fields of another `buttons` layout |\n| 11 | `buttons` missing or not 1-3 |\n| 12 | Cards mix images and videos |\n| 13 | A `cardX_body` is longer than 160 chars / has more than 2 line breaks, or only some cards have a body |\n| 14 | `cardX_buttonExternal` missing or not a URL / phone / e-mail |\n| 15 | `cardX_buttonExternalText` missing or longer than 20 chars |\n| 16 | `cardX_button1` missing or longer than 20 chars |\n| 17 | `cardX_button1ID` longer than 256 chars |\n| 18 | `cardX_button2` missing or longer than 20 chars |\n| 19 | `cardX_button2ID` longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Two ways to reach us today:\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1,\n \"templateTimeLeft\": 1380,\n \"card1_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card1_body\": \"Browse the full catalogue online.\",\n \"card2_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card2_body\": \"Or talk to a human - we pick up fast.\"\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Two ways to reach us today:\",\n \"buttons\": 1,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Browse the full catalogue online.\",\n \"card1_buttonExternal\": \"https://www.example.com/catalogue\",\n \"card1_buttonExternalText\": \"Open catalogue\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Or talk to a human - we pick up fast.\",\n \"card2_buttonExternal\": \"97231234567\",\n \"card2_buttonExternalText\": \"Call us\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 1` = one call-to-action per card. Each card decides its own action: an `https://` link, digits (call) or an e-mail.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The text bubble above the cards -> empty 5 |\n| `buttons` | yes | Button layout of **every** card: 1 = one call-to-action (link / call / e-mail), 2 = one reply button, 3 = two reply buttons -> 11 |\n| `cardX_headerLink` | yes per card | `https://` image or video URL (all cards the same kind, detected from the extension) -> 10 / 12 |\n| `cardX_body` | no (all cards or none) | Card text, up to 160 chars and 2 line breaks -> 13 |\n| `cardX_buttonExternal` | `buttons` 1 | URL, digits (phone) or e-mail -> 14 |\n| `cardX_buttonExternalText` | `buttons` 1 | Label, up to 20 chars -> 15 |\n| `cardX_button1` | `buttons` 2/3 | Reply label, up to 20 chars -> 16 |\n| `cardX_button1ID` | no | Your id, up to 256 chars (default `1`) -> 17 |\n| `cardX_button2` | `buttons` 3 | Second reply label, up to 20 chars -> 18 |\n| `cardX_button2ID` | no | Your id (default `2`) -> 19 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nCards are numbered `card1_`..`card10_` without gaps, **2 to 10 cards**. Only the fields of the chosen `buttons` layout may appear (a `card1_button1` on a `buttons: 1` carousel -> 10). Taps on reply buttons arrive as `type: button` webhooks with `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 10 | Cards invalid: fewer than 2 / more than 10, numbering with gaps, a `cardX_headerLink` missing or not https, or fields of another `buttons` layout |\n| 11 | `buttons` missing or not 1-3 |\n| 12 | Cards mix images and videos |\n| 13 | A `cardX_body` is longer than 160 chars / has more than 2 line breaks, or only some cards have a body |\n| 14 | `cardX_buttonExternal` missing or not a URL / phone / e-mail |\n| 15 | `cardX_buttonExternalText` missing or longer than 20 chars |\n| 16 | `cardX_button1` missing or longer than 20 chars |\n| 17 | `cardX_button1ID` longer than 256 chars |\n| 18 | `cardX_button2` missing or longer than 20 chars |\n| 19 | `cardX_button2ID` longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - only one card (reason 10)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Two ways to reach us today:\",\n \"buttons\": 1,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Browse the full catalogue online.\",\n \"card1_buttonExternal\": \"https://www.example.com/catalogue\",\n \"card1_buttonExternalText\": \"Open catalogue\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Or talk to a human - we pick up fast.\",\n \"card2_buttonExternal\": \"97231234567\",\n \"card2_buttonExternalText\": \"Call us\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 1` = one call-to-action per card. Each card decides its own action: an `https://` link, digits (call) or an e-mail.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The text bubble above the cards -> empty 5 |\n| `buttons` | yes | Button layout of **every** card: 1 = one call-to-action (link / call / e-mail), 2 = one reply button, 3 = two reply buttons -> 11 |\n| `cardX_headerLink` | yes per card | `https://` image or video URL (all cards the same kind, detected from the extension) -> 10 / 12 |\n| `cardX_body` | no (all cards or none) | Card text, up to 160 chars and 2 line breaks -> 13 |\n| `cardX_buttonExternal` | `buttons` 1 | URL, digits (phone) or e-mail -> 14 |\n| `cardX_buttonExternalText` | `buttons` 1 | Label, up to 20 chars -> 15 |\n| `cardX_button1` | `buttons` 2/3 | Reply label, up to 20 chars -> 16 |\n| `cardX_button1ID` | no | Your id, up to 256 chars (default `1`) -> 17 |\n| `cardX_button2` | `buttons` 3 | Second reply label, up to 20 chars -> 18 |\n| `cardX_button2ID` | no | Your id (default `2`) -> 19 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nCards are numbered `card1_`..`card10_` without gaps, **2 to 10 cards**. Only the fields of the chosen `buttons` layout may appear (a `card1_button1` on a `buttons: 1` carousel -> 10). Taps on reply buttons arrive as `type: button` webhooks with `caption` = the button id.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 6 | Your number is not configured for sending - contact support |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |\n| 10 | Cards invalid: fewer than 2 / more than 10, numbering with gaps, a `cardX_headerLink` missing or not https, or fields of another `buttons` layout |\n| 11 | `buttons` missing or not 1-3 |\n| 12 | Cards mix images and videos |\n| 13 | A `cardX_body` is longer than 160 chars / has more than 2 line breaks, or only some cards have a body |\n| 14 | `cardX_buttonExternal` missing or not a URL / phone / e-mail |\n| 15 | `cardX_buttonExternalText` missing or longer than 20 chars |\n| 16 | `cardX_button1` missing or longer than 20 chars |\n| 17 | `cardX_button1ID` longer than 256 chars |\n| 18 | `cardX_button2` missing or longer than 20 chars |\n| 19 | `cardX_button2ID` longer than 256 chars |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 10\n}" } ] }, { "name": "One reply button per card (buttons 2)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Our picks for you this week - tap the one you like:\",\n \"buttons\": 2,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Leather wallet - 199 NIS\",\n \"card1_button1\": \"I want this\",\n \"card1_button1ID\": \"WANT_WALLET\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Canvas backpack - 249 NIS\",\n \"card2_button1\": \"I want this\",\n \"card2_button1ID\": \"WANT_BACKPACK\",\n \"card3_headerLink\": \"{{sample_image_url}}\",\n \"card3_body\": \"Travel mug - 89 NIS\",\n \"card3_button1\": \"I want this\",\n \"card3_button1ID\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 2` = one reply button per card. Same label on every card is fine - the `cardX_button1ID` tells you which card was tapped." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Our picks for you this week - tap the one you like:\",\n \"buttons\": 2,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_body\": \"Leather wallet - 199 NIS\",\n \"card1_button1\": \"I want this\",\n \"card1_button1ID\": \"WANT_WALLET\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_body\": \"Canvas backpack - 249 NIS\",\n \"card2_button1\": \"I want this\",\n \"card2_button1ID\": \"WANT_BACKPACK\",\n \"card3_headerLink\": \"{{sample_image_url}}\",\n \"card3_body\": \"Travel mug - 89 NIS\",\n \"card3_button1\": \"I want this\",\n \"card3_button1ID\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 2` = one reply button per card. Same label on every card is fine - the `cardX_button1ID` tells you which card was tapped." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Our picks for you this week - tap the one you like:\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1,\n \"templateTimeLeft\": 1380,\n \"card1_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card1_body\": \"Leather wallet - 199 NIS\",\n \"card2_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card2_body\": \"Canvas backpack - 249 NIS\",\n \"card3_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card3_body\": \"Travel mug - 89 NIS\"\n}" } ] }, { "name": "Two reply buttons per card (buttons 3)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Choose a workshop and a seat type:\",\n \"buttons\": 3,\n \"card1_headerLink\": \"{{sample_video_url}}\",\n \"card1_body\": \"Sunday 10:00 - Intro to espresso\",\n \"card1_button1\": \"Standard seat\",\n \"card1_button1ID\": \"SUN_STD\",\n \"card1_button2\": \"Front row\",\n \"card1_button2ID\": \"SUN_FRONT\",\n \"card2_headerLink\": \"{{sample_video_url}}\",\n \"card2_body\": \"Tuesday 18:00 - Latte art\",\n \"card2_button1\": \"Standard seat\",\n \"card2_button1ID\": \"TUE_STD\",\n \"card2_button2\": \"Front row\",\n \"card2_button2ID\": \"TUE_FRONT\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 3` = two reply buttons per card. This sample also shows **video cards** - every card must be the same kind (all images or all videos)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Choose a workshop and a seat type:\",\n \"buttons\": 3,\n \"card1_headerLink\": \"{{sample_video_url}}\",\n \"card1_body\": \"Sunday 10:00 - Intro to espresso\",\n \"card1_button1\": \"Standard seat\",\n \"card1_button1ID\": \"SUN_STD\",\n \"card1_button2\": \"Front row\",\n \"card1_button2ID\": \"SUN_FRONT\",\n \"card2_headerLink\": \"{{sample_video_url}}\",\n \"card2_body\": \"Tuesday 18:00 - Latte art\",\n \"card2_button1\": \"Standard seat\",\n \"card2_button1ID\": \"TUE_STD\",\n \"card2_button2\": \"Front row\",\n \"card2_button2ID\": \"TUE_FRONT\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`buttons: 3` = two reply buttons per card. This sample also shows **video cards** - every card must be the same kind (all images or all videos)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Choose a workshop and a seat type:\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1,\n \"templateTimeLeft\": 1380,\n \"card1_headerLink\": \"https://storage.99digital.online/samples/meditation.mp4\",\n \"card1_body\": \"Sunday 10:00 - Intro to espresso\",\n \"card2_headerLink\": \"https://storage.99digital.online/samples/meditation.mp4\",\n \"card2_body\": \"Tuesday 18:00 - Latte art\"\n}" } ] }, { "name": "Cards without text", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Swipe through the new collection:\",\n \"buttons\": 2,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_button1\": \"Details\",\n \"card1_button1ID\": \"ITEM_1\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_button1\": \"Details\",\n \"card2_button1ID\": \"ITEM_2\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`cardX_body` is optional, but it is all-or-nothing: either every card has a text or none does (reason 13 otherwise)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Swipe through the new collection:\",\n \"buttons\": 2,\n \"card1_headerLink\": \"{{sample_image_url}}\",\n \"card1_button1\": \"Details\",\n \"card1_button1ID\": \"ITEM_1\",\n \"card2_headerLink\": \"{{sample_image_url}}\",\n \"card2_button1\": \"Details\",\n \"card2_button1ID\": \"ITEM_2\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendCarousel", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendCarousel" ] }, "description": "`cardX_body` is optional, but it is all-or-nothing: either every card has a text or none does (reason 13 otherwise)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Swipe through the new collection:\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1,\n \"templateTimeLeft\": 1380,\n \"card1_headerLink\": \"https://storage.99digital.online/samples/hello.png\",\n \"card2_headerLink\": \"https://storage.99digital.online/samples/hello.png\"\n}" } ] } ] }, { "name": "sendLocation", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"lat\": \"32.0853\",\n \"lng\": \"34.7818\",\n \"caption\": \"Our store - Azrieli Center, Tel Aviv\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendLocation" ] }, "description": "`POST /whatsapp/v2/sendLocation` - a map pin.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `lat` | yes | Latitude, e.g. `32.0853` -> missing 5 |\n| `lng` | yes | Longitude, e.g. `34.7818` -> missing 5 |\n| `caption` | no | Label shown under the pin (name / address) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `lat` or `lng` missing |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"lat\": \"32.0853\",\n \"lng\": \"34.7818\",\n \"caption\": \"Our store - Azrieli Center, Tel Aviv\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendLocation" ] }, "description": "`POST /whatsapp/v2/sendLocation` - a map pin.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `lat` | yes | Latitude, e.g. `32.0853` -> missing 5 |\n| `lng` | yes | Longitude, e.g. `34.7818` -> missing 5 |\n| `caption` | no | Label shown under the pin (name / address) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `lat` or `lng` missing |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"lat\": \"32.0853\",\n \"lng\": \"34.7818\",\n \"caption\": \"Our store - Azrieli Center, Tel Aviv\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"lat\": \"32.0853\",\n \"lng\": \"34.7818\",\n \"caption\": \"Our store - Azrieli Center, Tel Aviv\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendLocation" ] }, "description": "`POST /whatsapp/v2/sendLocation` - a map pin.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `lat` | yes | Latitude, e.g. `32.0853` -> missing 5 |\n| `lng` | yes | Longitude, e.g. `34.7818` -> missing 5 |\n| `caption` | no | Label shown under the pin (name / address) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `lat` or `lng` missing |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - lat/lng missing (reason 5)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"lat\": \"32.0853\",\n \"lng\": \"34.7818\",\n \"caption\": \"Our store - Azrieli Center, Tel Aviv\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendLocation" ] }, "description": "`POST /whatsapp/v2/sendLocation` - a map pin.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `lat` | yes | Latitude, e.g. `32.0853` -> missing 5 |\n| `lng` | yes | Longitude, e.g. `34.7818` -> missing 5 |\n| `caption` | no | Label shown under the pin (name / address) |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `lat` or `lng` missing |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 5\n}" } ] }, { "name": "requestLocation", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Where should we deliver? Tap the button to share your location.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestLocation" ] }, "description": "`POST /whatsapp/v2/requestLocation` - your text plus WhatsApp's own **Send location** button. When the customer shares it you receive a `hook: new` webhook with `type: location`, `body` = `lat,lng` and `caption` = the place name / address.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The prompt text -> empty 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe button label is fixed by WhatsApp.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Where should we deliver? Tap the button to share your location.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestLocation" ] }, "description": "`POST /whatsapp/v2/requestLocation` - your text plus WhatsApp's own **Send location** button. When the customer shares it you receive a `hook: new` webhook with `type: location`, `body` = `lat,lng` and `caption` = the place name / address.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The prompt text -> empty 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe button label is fixed by WhatsApp.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"Where should we deliver? Tap the button to share your location.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"body\": \"Where should we deliver? Tap the button to share your location.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestLocation", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestLocation" ] }, "description": "`POST /whatsapp/v2/requestLocation` - your text plus WhatsApp's own **Send location** button. When the customer shares it you receive a `hook: new` webhook with `type: location`, `body` = `lat,lng` and `caption` = the place name / address.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `body` | yes | The prompt text -> empty 5 |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nThe button label is fixed by WhatsApp.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" } ] }, { "name": "requestPhone", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"body\": \"To complete your order we need your phone number - please tap the button to share it.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestPhone", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestPhone" ] }, "description": "`POST /whatsapp/v2/requestPhone` - for customers who hide their number behind a WhatsApp **username** (you only know their user id). The message carries a WhatsApp button that lets them reveal their phone number and name; the answer arrives as a `hook: new` webhook with `type: phone`, `body` = the phone number and `senderName` / `caption` = the name.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | Usually the user id (`IL.…`); a phone number works too -> 4 |\n| `body` | yes | The prompt text -> empty 5 |\n| `showRequest` | no | `1` = echo the request |\n\n`replyTo` is not available on this endpoint.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"body\": \"To complete your order we need your phone number - please tap the button to share it.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestPhone", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestPhone" ] }, "description": "`POST /whatsapp/v2/requestPhone` - for customers who hide their number behind a WhatsApp **username** (you only know their user id). The message carries a WhatsApp button that lets them reveal their phone number and name; the answer arrives as a `hook: new` webhook with `type: phone`, `body` = the phone number and `senderName` / `caption` = the name.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | Usually the user id (`IL.…`); a phone number works too -> 4 |\n| `body` | yes | The prompt text -> empty 5 |\n| `showRequest` | no | `1` = echo the request |\n\n`replyTo` is not available on this endpoint.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"body\": \"To complete your order we need your phone number - please tap the button to share it.\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"IL.1605856887361213\",\n \"templateTimeLeft\": 1380,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"body\": \"To complete your order we need your phone number - please tap the button to share it.\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/requestPhone", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "requestPhone" ] }, "description": "`POST /whatsapp/v2/requestPhone` - for customers who hide their number behind a WhatsApp **username** (you only know their user id). The message carries a WhatsApp button that lets them reveal their phone number and name; the answer arrives as a `hook: new` webhook with `type: phone`, `body` = the phone number and `senderName` / `caption` = the name.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | Usually the user id (`IL.…`); a phone number works too -> 4 |\n| `body` | yes | The prompt text -> empty 5 |\n| `showRequest` | no | `1` = echo the request |\n\n`replyTo` is not available on this endpoint.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `body` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" } ] }, { "name": "sendContact", "description": "`POST /whatsapp/v2/sendContact` - a contact card (vCard) the customer can save with one tap.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.", "item": [ { "name": "Contact - name and phone", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `contact_name` | yes | Display name -> empty 5 |\n| `contact_phone` | yes | International, no `+` (also makes the *Message* button work) -> empty 6 |\n| `contact_email` | no | E-mail address |\n| `contact_birthday` | no | `YYYY-MM-DD` |\n| `address_street`, `address_city`, `address_country` | no | One postal address |\n| `website` | no | One URL |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nOne contact per message, one phone / e-mail / address / URL each.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `contact_name` is empty |\n| 6 | `contact_phone` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `contact_name` | yes | Display name -> empty 5 |\n| `contact_phone` | yes | International, no `+` (also makes the *Message* button work) -> empty 6 |\n| `contact_email` | no | E-mail address |\n| `contact_birthday` | no | `YYYY-MM-DD` |\n| `address_street`, `address_city`, `address_country` | no | One postal address |\n| `website` | no | One URL |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nOne contact per message, one phone / e-mail / address / URL each.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `contact_name` is empty |\n| 6 | `contact_phone` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `contact_name` | yes | Display name -> empty 5 |\n| `contact_phone` | yes | International, no `+` (also makes the *Message* button work) -> empty 6 |\n| `contact_email` | no | E-mail address |\n| `contact_birthday` | no | `YYYY-MM-DD` |\n| `address_street`, `address_city`, `address_country` | no | One postal address |\n| `website` | no | One URL |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nOne contact per message, one phone / e-mail / address / URL each.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `contact_name` is empty |\n| 6 | `contact_phone` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - contact_phone missing (reason 6)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `contact_name` | yes | Display name -> empty 5 |\n| `contact_phone` | yes | International, no `+` (also makes the *Message* button work) -> empty 6 |\n| `contact_email` | no | E-mail address |\n| `contact_birthday` | no | `YYYY-MM-DD` |\n| `address_street`, `address_city`, `address_country` | no | One postal address |\n| `website` | no | One URL |\n| `replyTo` | no | `unique` of the message to quote |\n| `showRequest` | no | `1` = echo the request |\n\nOne contact per message, one phone / e-mail / address / URL each.\n\n`to` is the customer's number in international format without `+` (`972501234567` - we strip spaces and dashes and fix a leading `9720`), or the user id from your webhook (`IL.1605856887361213`) for customers who hide their number. A local format such as `0501234567` is rejected with reason 4.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 5 | `contact_name` is empty |\n| 6 | `contact_phone` is empty |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 6\n}" } ] }, { "name": "Contact - full card", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\",\n \"contact_email\": \"dana@example.com\",\n \"contact_birthday\": \"1990-05-14\",\n \"address_street\": \"Herzl 1\",\n \"address_city\": \"Tel Aviv\",\n \"address_country\": \"Israel\",\n \"website\": \"https://www.example.com\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "Every optional field filled in. Empty optional fields may simply be omitted." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\",\n \"contact_email\": \"dana@example.com\",\n \"contact_birthday\": \"1990-05-14\",\n \"address_street\": \"Herzl 1\",\n \"address_city\": \"Tel Aviv\",\n \"address_country\": \"Israel\",\n \"website\": \"https://www.example.com\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendContact", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendContact" ] }, "description": "Every optional field filled in. Empty optional fields may simply be omitted." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"contact_name\": \"Dana Levi - Sales\",\n \"contact_phone\": \"972521234567\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"templateTimeLeft\": 1380,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] } ] }, { "name": "sendReaction", "description": "`POST /whatsapp/v2/sendReaction` - react to a customer's message with an emoji, or remove your reaction.\n\n**Session message.** Allowed only while the customer's **24-hour window** is open - they wrote to your number in the last 24 hours (every incoming message restarts the clock; `templateTimeLeft` in the response is what is left, in minutes). Outside the window - including a customer who never wrote to you - the call returns **reason 7** and you must use `sendTemplate` instead. Session messages are not billed.", "item": [ { "name": "React to an incoming message", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"👍\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | The customer who sent the message -> 4 |\n| `unique` | yes | The **incoming** message's `unique` from your `hook: new` webhook -> empty 4 |\n| `reaction` | yes | One emoji. `\"\"` removes your reaction |\n| `showRequest` | no | `1` = echo the request |\n\nOne reaction per message (a new emoji replaces the old one). Only messages the customer sent can be reacted to through the API. The response `unique` is the id of the reaction itself.\n\nWhen the **customer** reacts to one of your messages you receive a `hook: new` webhook with `type: reaction`, `body` = the emoji and `quoteUnique` = the `unique` of your message.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `unique` (message id) is empty, or `to` is invalid |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"👍\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | The customer who sent the message -> 4 |\n| `unique` | yes | The **incoming** message's `unique` from your `hook: new` webhook -> empty 4 |\n| `reaction` | yes | One emoji. `\"\"` removes your reaction |\n| `showRequest` | no | `1` = echo the request |\n\nOne reaction per message (a new emoji replaces the old one). Only messages the customer sent can be reacted to through the API. The response `unique` is the id of the reaction itself.\n\nWhen the **customer** reacts to one of your messages you receive a `hook: new` webhook with `type: reaction`, `body` = the emoji and `quoteUnique` = the `unique` of your message.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `unique` (message id) is empty, or `to` is invalid |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"reaction\": \"👍\",\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"👍\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | The customer who sent the message -> 4 |\n| `unique` | yes | The **incoming** message's `unique` from your `hook: new` webhook -> empty 4 |\n| `reaction` | yes | One emoji. `\"\"` removes your reaction |\n| `showRequest` | no | `1` = echo the request |\n\nOne reaction per message (a new emoji replaces the old one). Only messages the customer sent can be reacted to through the API. The response `unique` is the id of the reaction itself.\n\nWhen the **customer** reacts to one of your messages you receive a `hook: new` webhook with `type: reaction`, `body` = the emoji and `quoteUnique` = the `unique` of your message.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `unique` (message id) is empty, or `to` is invalid |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" }, { "name": "Failure - unique missing (reason 4)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"👍\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "| Field | Mandatory | Rules |\n|---|---|---|\n| `to` | yes | The customer who sent the message -> 4 |\n| `unique` | yes | The **incoming** message's `unique` from your `hook: new` webhook -> empty 4 |\n| `reaction` | yes | One emoji. `\"\"` removes your reaction |\n| `showRequest` | no | `1` = echo the request |\n\nOne reaction per message (a new emoji replaces the old one). Only messages the customer sent can be reacted to through the API. The response `unique` is the id of the reaction itself.\n\nWhen the **customer** reacts to one of your messages you receive a `hook: new` webhook with `type: reaction`, `body` = the emoji and `quoteUnique` = the `unique` of your message.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id in well under a second. Sent / delivered / read / failed arrive later on your webhook (`hook: update`, `ack` 1 / 2 / 3 / 0) keyed by that `unique` - see folder *5 - Webhooks*.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued (watch the `hook: update` webhook for the delivery status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `unique` (message id) is empty, or `to` is invalid |\n| 7 | No open 24-hour window with `to` (they never wrote to you, or more than 24h ago) - use `sendTemplate` |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 4\n}" } ] }, { "name": "Remove a reaction", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "An empty `reaction` removes the emoji you previously put on that message." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"unique\": \"{{incoming_unique}}\",\n \"reaction\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendReaction", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendReaction" ] }, "description": "An empty `reaction` removes the emoji you previously put on that message." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"reaction\": \"\",\n \"reason\": 1\n}" } ] } ] }, { "name": "typing", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/typing", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "typing" ] }, "description": "`POST /whatsapp/v2/typing` - shows the **typing…** indicator to the customer and marks their last message as read (blue ticks) in the same call. Ideal right before a bot answer that takes a few seconds.\n\nOnly `from` and `to`. The indicator disappears by itself after ~20-25 seconds or as soon as your next message arrives; there is no 'stop' call. Requires an open 24-hour window **and** at least one message from this customer in your history (reason 7 otherwise). Synchronous - no `unique`, no webhook.\n\nDo not call it more than once per answer, and skip it when you reply within a second anyway.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |\n| 7 | No open 24-hour window, or no message from this customer on record |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/typing", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "typing" ] }, "description": "`POST /whatsapp/v2/typing` - shows the **typing…** indicator to the customer and marks their last message as read (blue ticks) in the same call. Ideal right before a bot answer that takes a few seconds.\n\nOnly `from` and `to`. The indicator disappears by itself after ~20-25 seconds or as soon as your next message arrives; there is no 'stop' call. Requires an open 24-hour window **and** at least one message from this customer in your history (reason 7 otherwise). Synchronous - no `unique`, no webhook.\n\nDo not call it more than once per answer, and skip it when you reply within a second anyway.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |\n| 7 | No open 24-hour window, or no message from this customer on record |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1\n}" }, { "name": "Failure - 24h window closed, use a template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/typing", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "typing" ] }, "description": "`POST /whatsapp/v2/typing` - shows the **typing…** indicator to the customer and marks their last message as read (blue ticks) in the same call. Ideal right before a bot answer that takes a few seconds.\n\nOnly `from` and `to`. The indicator disappears by itself after ~20-25 seconds or as soon as your next message arrives; there is no 'stop' call. Requires an open 24-hour window **and** at least one message from this customer in your history (reason 7 otherwise). Synchronous - no `unique`, no webhook.\n\nDo not call it more than once per answer, and skip it when you reply within a second anyway.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |\n| 7 | No open 24-hour window, or no message from this customer on record |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" } ] }, { "name": "readStatus (mark as read)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/readStatus", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "readStatus" ] }, "description": "`POST /whatsapp/v2/readStatus` - mark the customer's **latest** message as read (blue ticks); earlier messages in the chat turn blue with it. No message id needed: we pick the newest incoming message from `to`. Cannot be undone. Works regardless of the 24-hour window. Synchronous - no `unique`, no webhook.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist, no message from this customer on record, or an internal error (an `error` text is added) |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/readStatus", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "readStatus" ] }, "description": "`POST /whatsapp/v2/readStatus` - mark the customer's **latest** message as read (blue ticks); earlier messages in the chat turn blue with it. No message id needed: we pick the newest incoming message from `to`. Cannot be undone. Works regardless of the 24-hour window. Synchronous - no `unique`, no webhook.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist, no message from this customer on record, or an internal error (an `error` text is added) |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"reason\": 1\n}" }, { "name": "Failure - no message from this customer yet (reason 2)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/readStatus", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "readStatus" ] }, "description": "`POST /whatsapp/v2/readStatus` - mark the customer's **latest** message as read (blue ticks); earlier messages in the chat turn blue with it. No message id needed: we pick the newest incoming message from `to`. Cannot be undone. Works regardless of the 24-hour window. Synchronous - no `unique`, no webhook.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist, no message from this customer on record, or an internal error (an `error` text is added) |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` missing or invalid |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 2,\n \"error\": \"No HB message found in history\"\n}" } ] } ] }, { "name": "2 - Templates", "description": "Templates are the pre-approved messages that WhatsApp lets you send **outside the 24-hour window** - to a new customer, or to one who has not written to you in the last 24 hours. Everything else (folder *1*) is a reply and requires an open window.\n\n**Life cycle:** `createTemplate` (submit to Meta) -> `getTemplates` (wait for `approved`, or use the `hook: system` / `type: template` webhook) -> `sendTemplate` / `sendMultiTemplate` -> `deleteTemplate` when retired.\n\n**Billing.** Marketing and authentication templates are billed per message. A utility template is billed only when no 24-hour conversation is open with that customer. A regular reply inside an open window is never billed. Full explanation: https://docs.99digital.co.il/whatsapp-api/information/template-conversation-and-message\n\n**Limits.** New numbers can open 250 template conversations per 24h, rising automatically (2k / 10k / 100k / unlimited) with quality and volume; at most 2 marketing templates to the same person per 24h; templates you have not used for 12 months are deleted by Meta.\n\nThe samples in *createTemplate* and *sendTemplate* are paired by the `{{tpl_*}}` variables: create a template, wait for approval, then send it with the sample of the same name.", "item": [ { "name": "createTemplate", "description": "`POST /whatsapp/v2/createTemplate` - submit a new message template to Meta for approval. **One endpoint for every template kind**: plain text, media header, buttons, coupon, authentication (OTP) and carousel.\n\nTemplates cannot be edited - to change one, create a new one under a new name and delete the old one.\n\nEvery sample below has a matching *sendTemplate* sample with the **same template name** (`{{tpl_*}}` variables), so the flow is: create here -> wait for approval -> send from the *sendTemplate* folder.\n\n> The `{{1}}`, `{{2}}` placeholders inside `body` are **WhatsApp variables**, not Postman variables - Postman leaves them untouched (never create a collection variable with a numeric name).\n\nText formatting inside `body`: `*bold*`, `_italic_`, `~strike~`, `\\n` line break.\n\n> ⚠️ **Two different header code tables.** `createTemplate` uses `header` (1 none, 2 image, 3 video, 4 document, 5 carousel) while `sendTemplate` / `sendMultiTemplate` use `headerType` (1 none *or carousel*, 2 text, 3 image, 4 video, 5 document). The same picture header is `header: 2` when you create and `headerType: 3` when you send.\n\nA new template is **`submitted`** to Meta for review. You can only send it once it is `approved` - usually within minutes, sometimes up to 24-48 hours. Poll `getTemplates`, or turn on **system messages** in `setWebhook` and wait for the `hook: system`, `type: template` webhook (`templateUpdate: 1` = approved).\n\n**Categories.** We submit regular templates as *utility* and let Meta re-classify (`allow_category_change`), so the response `category` may come back as 2 (marketing). Carousels are always marketing, `authentication: 1` is always authentication.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number, international, no `+` |\n| `name` | yes | Lowercase letters, digits and `_` only. We lowercase it and strip spaces. Must be unique in your account (a deleted name is blocked for 30 days) -> else reason 4 |\n| `language` | yes | 1 Hebrew, 2 English, 3 Arabic, 4 Russian, 5 Spanish, 6 Chinese, 7 Hindi, 8 Thai, 9 French -> else 5 |\n| `header` | yes | 1 none, 2 image, 3 video, 4 document, 5 carousel -> else 6 |\n| `body` | yes | <=1024 chars, up to 10 variables `{{1}}`..`{{10}}`, each used once, may not start or end with a variable, ~3 words of text per variable -> else 7 (or 22 from Meta) |\n| `footer` | no | <=60 chars, plain text, no variables -> else 8 |\n| `buttons` | yes | 1 none, 2 call-to-action, 3 quick replies, 4 both -> else 9 |\n| `callToAction` | with `buttons` 2/4 | 1 website, 2 call, 3 website + call, 4 two websites + call, 5 two websites -> else 10 |\n| `callToActionWebsiteText` | CTA 1/3/4/5 | Button label, <=20 chars -> 11 |\n| `callToActionWebsiteType` | CTA 1/3/4/5 | 1 static URL, 2 dynamic URL -> 12 |\n| `callToActionWebsiteURL` | CTA 1/3/4/5 | Full https URL **without** `{{1}}` -> 13. Dynamic: we append `/{{1}}` for you |\n| `callToActionCallText` | CTA 2/3/4 | <=20 chars -> 14 |\n| `callToActionCallNumber` | CTA 2/3/4 | International with `+`, <=20 chars -> 15 |\n| `callToActionWebsiteText2` / `...Type2` / `...URL2` | CTA 4/5 | Same rules as the first website -> 23 / 24 / 25 |\n| `quickReply1`..`quickReply10` | `buttons` 3/4 (`quickReply1` mandatory -> 16) | <=25 chars each -> 21. No emoji (Meta -> 31) |\n| `bodyVariableSample1`..`10` | **recommended** | Realistic sample values for the Meta reviewer, one per `{{n}}`. If you skip them we insert generic Hebrew utility sentences |\n| `useCoupon` | no | 1 = add a *Copy code* button (see the coupon sample) |\n| `couponTitle` | with `useCoupon` | Offer title, <=16 chars -> 26 |\n| `couponExpiration` | with `useCoupon` | 1 = the offer shows an expiry, 0 = no expiry -> else 27 |\n| `authentication` | no | 1 = OTP template (see the authentication sample). Ignores header / body / footer / buttons |\n| `add_security_text` | auth | 0 / 1 -> 33 |\n| `code_expiration` | auth | 0-90 minutes, 0 = no expiry line -> 34 |\n| `carouselMedia` | `header` 5 | 1 image cards, 2 video cards -> 36 |\n| `carouselButtons` | `header` 5 | 1 website, 2 quick reply, 3 two quick replies, 4 website + quick reply, 5 phone + website, 6 phone + quick reply -> 39 |\n| `carouselCardX_*` | `header` 5 | One set per card, `X` = 1..10, see the carousel samples -> 37 / 38 / 40 / 41 / 42 / 43 |\n\n**Maximum 10 buttons in total** (quick replies + call-to-action + coupon) -> reason 17.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - the template was submitted to Meta for review |\n| 2 | `from` does not exist, body is not valid JSON, or we could not reach Meta |\n| 3 | Wrong `apiKey` header |\n| 4 | `name` invalid, too long, or already exists (also for 30 days after a delete) |\n| 5 | `language` is not 1-9 |\n| 6 | `header` is not 1-5 (or a document header on a coupon template) |\n| 7 | `body` problem: empty, >1024 chars, >10 variables, a variable used twice, or >600 chars on a coupon template |\n| 8 | `footer` >60 chars (or a footer on a coupon template) |\n| 9 | `buttons` is not 1-4 (coupon templates need 2 or 4) |\n| 10 | `callToAction` missing / not 1-5, or `quickReply1` missing with `buttons: 4` |\n| 11 | `callToActionWebsiteText` missing or >20 chars |\n| 12 | `callToActionWebsiteType` is not 1 or 2 |\n| 13 | `callToActionWebsiteURL` missing or contains `{{1}}` |\n| 14 | `callToActionCallText` missing or >20 chars |\n| 15 | `callToActionCallNumber` missing or >20 chars |\n| 16 | `quickReply1` missing while `buttons` is 3 or 4 |\n| 17 | More than 10 buttons in total |\n| 18 | Meta: the number of variable samples does not match the variables |\n| 19 | Meta: header sample media rejected |\n| 20 | Dynamic website sample missing |\n| 21 | A `quickReplyX` is longer than 25 chars |\n| 22 | Meta: too many variables for the amount of text |\n| 23 | Second website text missing / >20 chars (or Meta: the same button twice) |\n| 24 | Second website type is not 1 or 2 |\n| 25 | Second website URL missing or contains `{{1}}` |\n| 26 | `couponTitle` missing or >16 chars |\n| 27 | `couponExpiration` is not 0 or 1 |\n| 30 | Meta rejected the submission for another reason (syntax) - check the text |\n| 31 | Meta: emoji inside a quick reply button |\n| 32 | Meta: the body looks like an authentication template - use `authentication: 1` |\n| 33 | `add_security_text` is not 0/1 (or Meta rejected the auth template) |\n| 34 | `code_expiration` is not 0-90 |\n| 35 | This account has no permission to create templates - contact support |\n| 36 | `carouselMedia` missing or not 1/2 |\n| 37 | Carousel needs 2-10 cards numbered 1..N without gaps |\n| 38 | A card body >160 chars / >2 line breaks, or only some cards have a body |\n| 39 | `carouselButtons` missing or not 1-6 |\n| 40 | Card variable problem: only one `{{1}}` per card, all cards or none, sample <=160 |\n| 41 | Card website button: text >25, URL missing/>2000/contains `{{`, type not 1/2, or mixed types across cards |\n| 42 | Card quick reply missing or >25 chars |\n| 43 | Card call button: text missing/>25 or number missing/>20 |", "item": [ { "name": "Text only - no variables, no buttons", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"footer\": \"Reply STOP to opt out\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The simplest template: fixed text, optional footer, no buttons. Send it later with `headerType: 1` and no variables.\n\n`language: 2` = English. The text of the template is fixed at creation - only `{{n}}` variables can change per message." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"footer\": \"Reply STOP to opt out\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The simplest template: fixed text, optional footer, no buttons. Send it later with `headerType: 1` and no variables.\n\n`language: 2` = English. The text of the template is fixed at creation - only `{{n}}` variables can change per message." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_simple_notice\",\n \"timestamp\": 1789900000,\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"category\": 1,\n \"reason\": 1\n}" }, { "name": "Failure - name already exists (reason 4)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"footer\": \"Reply STOP to opt out\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The simplest template: fixed text, optional footer, no buttons. Send it later with `headerType: 1` and no variables.\n\n`language: 2` = English. The text of the template is fixed at creation - only `{{n}}` variables can change per message." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 4\n}" }, { "name": "Failure - wrong apiKey header (reason 3)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"footer\": \"Reply STOP to opt out\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The simplest template: fixed text, optional footer, no buttons. Send it later with `headerType: 1` and no variables.\n\n`language: 2` = English. The text of the template is fixed at creation - only `{{n}}` variables can change per message." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 3\n}" } ] }, { "name": "Text with variables + samples", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, your order {{2}} was received. We will let you know when it ships.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"4711\",\n \"footer\": \"Thank you for shopping with us\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "Variables are `{{1}}`..`{{10}}`, each used once, never at the very start or end of the body, with a few words of real text around each one.\n\n**Always send `bodyVariableSampleN`** - Meta's reviewers see the body with the samples filled in, and a template with realistic samples is approved faster. Without them we insert generic Hebrew utility sentences.\n\nWhen sending, you will pass `bodyVariable1` = the name and `bodyVariable2` = the order number." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, your order {{2}} was received. We will let you know when it ships.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"4711\",\n \"footer\": \"Thank you for shopping with us\",\n \"buttons\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "Variables are `{{1}}`..`{{10}}`, each used once, never at the very start or end of the body, with a few words of real text around each one.\n\n**Always send `bodyVariableSampleN`** - Meta's reviewers see the body with the samples filled in, and a template with realistic samples is approved faster. Without them we insert generic Hebrew utility sentences.\n\nWhen sending, you will pass `bodyVariable1` = the name and `bodyVariable2` = the order number." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_welcome_text\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, your order {{2}} was received. We will let you know when it ships.\",\n \"category\": 1,\n \"reason\": 1\n}" } ] }, { "name": "Hebrew template (language 1)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_hebrew}}\",\n \"language\": 1,\n \"header\": 1,\n \"body\": \"שלום {{1}}, ההזמנה שלך מספר {{2}} התקבלה בהצלחה. נעדכן אותך כשהיא תישלח.\",\n \"bodyVariableSample1\": \"דנה\",\n \"bodyVariableSample2\": \"4711\",\n \"footer\": \"תודה שקניתם אצלנו\",\n \"buttons\": 3,\n \"quickReply1\": \"מעקב משלוח\",\n \"quickReply2\": \"דברו איתי\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "Same idea in Hebrew (`language: 1`) - the body, footer and button labels are all UTF-8, and WhatsApp renders right-to-left automatically. Other languages: 3 Arabic, 4 Russian, 5 Spanish, 6 Chinese, 7 Hindi, 8 Thai, 9 French.\n\nOne `name` = one language. To offer the same message in two languages, create two templates (e.g. `welcome_he` and `welcome_en`) and pick the name per recipient when you send." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_hebrew}}\",\n \"language\": 1,\n \"header\": 1,\n \"body\": \"שלום {{1}}, ההזמנה שלך מספר {{2}} התקבלה בהצלחה. נעדכן אותך כשהיא תישלח.\",\n \"bodyVariableSample1\": \"דנה\",\n \"bodyVariableSample2\": \"4711\",\n \"footer\": \"תודה שקניתם אצלנו\",\n \"buttons\": 3,\n \"quickReply1\": \"מעקב משלוח\",\n \"quickReply2\": \"דברו איתי\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "Same idea in Hebrew (`language: 1`) - the body, footer and button labels are all UTF-8, and WhatsApp renders right-to-left automatically. Other languages: 3 Arabic, 4 Russian, 5 Spanish, 6 Chinese, 7 Hindi, 8 Thai, 9 French.\n\nOne `name` = one language. To offer the same message in two languages, create two templates (e.g. `welcome_he` and `welcome_en`) and pick the name per recipient when you send." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_hebrew_welcome\",\n \"timestamp\": 1789900000,\n \"body\": \"שלום {{1}}, ההזמנה שלך מספר {{2}} התקבלה בהצלחה. נעדכן אותך כשהיא תישלח.\",\n \"category\": 1,\n \"reason\": 1\n}" } ] }, { "name": "Image header + website button (static URL)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_image}}\",\n \"language\": 2,\n \"header\": 2,\n \"body\": \"Hi {{1}}, this week only: {{2}} off everything in the summer collection. Tap below to shop.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"20%\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Shop now\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/summer\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 2` = image header. You do **not** upload the picture now - we register a sample image with Meta; the real picture is given per message as `headerLink` when you send (`headerType: 3`).\n\n`buttons: 2` + `callToAction: 1` = a single website button. `callToActionWebsiteType: 1` is a **static** URL - identical for every recipient, nothing to pass when sending.\n\nMarketing wording like this is usually re-classified by Meta as `category: 2` (marketing) - that is expected." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_image}}\",\n \"language\": 2,\n \"header\": 2,\n \"body\": \"Hi {{1}}, this week only: {{2}} off everything in the summer collection. Tap below to shop.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"20%\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Shop now\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/summer\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 2` = image header. You do **not** upload the picture now - we register a sample image with Meta; the real picture is given per message as `headerLink` when you send (`headerType: 3`).\n\n`buttons: 2` + `callToAction: 1` = a single website button. `callToActionWebsiteType: 1` is a **static** URL - identical for every recipient, nothing to pass when sending.\n\nMarketing wording like this is usually re-classified by Meta as `category: 2` (marketing) - that is expected." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_offer_image\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, this week only: {{2}} off everything in the summer collection. Tap below to shop.\",\n \"category\": 2,\n \"reason\": 1\n}" } ] }, { "name": "Document header + dynamic URL button", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_document}}\",\n \"language\": 2,\n \"header\": 4,\n \"body\": \"Dear {{1}}, your invoice for {{2}} is attached. The total amount is {{3}}. Thank you for your business.\",\n \"bodyVariableSample1\": \"Dana Levi\",\n \"bodyVariableSample2\": \"August 2026\",\n \"bodyVariableSample3\": \"350 USD\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Pay online\",\n \"callToActionWebsiteType\": 2,\n \"callToActionWebsiteURL\": \"https://www.example.com/pay\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 4` = document (PDF) header - the file itself is passed per message as `headerLink` (`headerType: 5`).\n\n`callToActionWebsiteType: 2` = **dynamic** URL. We store the button as `https://www.example.com/pay/{{1}}` (a `/` is appended if the URL has none), and at send time you pass `websiteVariable`, e.g. `inv-4711`, so the customer opens `https://www.example.com/pay/inv-4711`. Do **not** write `{{1}}` in the URL yourself (reason 13)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_document}}\",\n \"language\": 2,\n \"header\": 4,\n \"body\": \"Dear {{1}}, your invoice for {{2}} is attached. The total amount is {{3}}. Thank you for your business.\",\n \"bodyVariableSample1\": \"Dana Levi\",\n \"bodyVariableSample2\": \"August 2026\",\n \"bodyVariableSample3\": \"350 USD\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Pay online\",\n \"callToActionWebsiteType\": 2,\n \"callToActionWebsiteURL\": \"https://www.example.com/pay\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 4` = document (PDF) header - the file itself is passed per message as `headerLink` (`headerType: 5`).\n\n`callToActionWebsiteType: 2` = **dynamic** URL. We store the button as `https://www.example.com/pay/{{1}}` (a `/` is appended if the URL has none), and at send time you pass `websiteVariable`, e.g. `inv-4711`, so the customer opens `https://www.example.com/pay/inv-4711`. Do **not** write `{{1}}` in the URL yourself (reason 13)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_invoice_pdf\",\n \"timestamp\": 1789900000,\n \"body\": \"Dear {{1}}, your invoice for {{2}} is attached. The total amount is {{3}}. Thank you for your business.\",\n \"category\": 1,\n \"reason\": 1\n}" } ] }, { "name": "Video header + quick reply buttons", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_video}}\",\n \"language\": 2,\n \"header\": 3,\n \"body\": \"Hi {{1}}, watch our new {{2}} in action. Interested? Pick an option below.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"espresso machine\",\n \"buttons\": 3,\n \"quickReply1\": \"Tell me more\",\n \"quickReply2\": \"Book a demo\",\n \"quickReply3\": \"Not interested\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 3` = video header (mp4, passed per message as `headerLink` with `headerType: 4`).\n\n`buttons: 3` = quick replies only - up to 10, <=25 chars each, no emoji. When the customer taps one you receive a `type: button` webhook whose `body` is the button text and whose `caption` is the id you passed as `quickReplyN_id` when sending." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_video}}\",\n \"language\": 2,\n \"header\": 3,\n \"body\": \"Hi {{1}}, watch our new {{2}} in action. Interested? Pick an option below.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"espresso machine\",\n \"buttons\": 3,\n \"quickReply1\": \"Tell me more\",\n \"quickReply2\": \"Book a demo\",\n \"quickReply3\": \"Not interested\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 3` = video header (mp4, passed per message as `headerLink` with `headerType: 4`).\n\n`buttons: 3` = quick replies only - up to 10, <=25 chars each, no emoji. When the customer taps one you receive a `type: button` webhook whose `body` is the button text and whose `caption` is the id you passed as `quickReplyN_id` when sending." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_promo_video\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, watch our new {{2}} in action. Interested? Pick an option below.\",\n \"category\": 2,\n \"reason\": 1\n}" } ] }, { "name": "Call + website + quick replies (buttons 4)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_buttons}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, this is a reminder of your appointment on {{2}} at {{3}}. Please arrive 10 minutes early.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"Sunday 14 September\",\n \"bodyVariableSample3\": \"10:30\",\n \"footer\": \"Need to reschedule? Just reply here\",\n \"buttons\": 4,\n \"callToAction\": 3,\n \"callToActionWebsiteText\": \"Navigate\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://waze.com/ul/hsv8wtf4k1\",\n \"callToActionCallText\": \"Call us\",\n \"callToActionCallNumber\": \"+97231234567\",\n \"quickReply1\": \"Confirm\",\n \"quickReply2\": \"Reschedule\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`buttons: 4` = call-to-action **and** quick replies together. `callToAction: 3` = one website + one call button. The phone number is international with a leading `+`.\n\nOther `callToAction` layouts: 1 website, 2 call only, 4 two websites + call, 5 two websites (see the next sample). Whatever the mix, the grand total is 10 buttons (reason 17)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_buttons}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, this is a reminder of your appointment on {{2}} at {{3}}. Please arrive 10 minutes early.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"Sunday 14 September\",\n \"bodyVariableSample3\": \"10:30\",\n \"footer\": \"Need to reschedule? Just reply here\",\n \"buttons\": 4,\n \"callToAction\": 3,\n \"callToActionWebsiteText\": \"Navigate\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://waze.com/ul/hsv8wtf4k1\",\n \"callToActionCallText\": \"Call us\",\n \"callToActionCallNumber\": \"+97231234567\",\n \"quickReply1\": \"Confirm\",\n \"quickReply2\": \"Reschedule\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`buttons: 4` = call-to-action **and** quick replies together. `callToAction: 3` = one website + one call button. The phone number is international with a leading `+`.\n\nOther `callToAction` layouts: 1 website, 2 call only, 4 two websites + call, 5 two websites (see the next sample). Whatever the mix, the grand total is 10 buttons (reason 17)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_reminder_full\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, this is a reminder of your appointment on {{2}} at {{3}}. Please arrive 10 minutes early.\",\n \"category\": 1,\n \"reason\": 1\n}" } ] }, { "name": "Two website buttons + call (callToAction 4)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_two_sites}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, your table for {{2}} is booked. You can view the menu or manage your booking below.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"Friday 20:00\",\n \"buttons\": 2,\n \"callToAction\": 4,\n \"callToActionWebsiteText\": \"View menu\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/menu\",\n \"callToActionWebsiteText2\": \"My booking\",\n \"callToActionWebsiteType2\": 2,\n \"callToActionWebsiteURL2\": \"https://www.example.com/booking\",\n \"callToActionCallText\": \"Call the restaurant\",\n \"callToActionCallNumber\": \"+97231234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`callToAction: 4` = two website buttons + a call button (use 5 for two websites without the call). The second website has its own trio: `callToActionWebsiteText2`, `callToActionWebsiteType2`, `callToActionWebsiteURL2`.\n\nHere the first URL is static and the second is dynamic - when sending you pass `websiteVariable2` only (the *N-th URL button* maps to `websiteVariable` / `websiteVariable2`)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_two_sites}}\",\n \"language\": 2,\n \"header\": 1,\n \"body\": \"Hi {{1}}, your table for {{2}} is booked. You can view the menu or manage your booking below.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"Friday 20:00\",\n \"buttons\": 2,\n \"callToAction\": 4,\n \"callToActionWebsiteText\": \"View menu\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/menu\",\n \"callToActionWebsiteText2\": \"My booking\",\n \"callToActionWebsiteType2\": 2,\n \"callToActionWebsiteURL2\": \"https://www.example.com/booking\",\n \"callToActionCallText\": \"Call the restaurant\",\n \"callToActionCallNumber\": \"+97231234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`callToAction: 4` = two website buttons + a call button (use 5 for two websites without the call). The second website has its own trio: `callToActionWebsiteText2`, `callToActionWebsiteType2`, `callToActionWebsiteURL2`.\n\nHere the first URL is static and the second is dynamic - when sending you pass `websiteVariable2` only (the *N-th URL button* maps to `websiteVariable` / `websiteVariable2`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_booking_links\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, your table for {{2}} is booked. You can view the menu or manage your booking below.\",\n \"category\": 1,\n \"reason\": 1\n}" } ] }, { "name": "Coupon code (copy-code button)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"language\": 2,\n \"header\": 2,\n \"body\": \"Hi {{1}}, as a VIP customer here is {{2}} off your next order. Copy the code and use it at checkout before it expires.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"20%\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Shop now\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/shop\",\n \"useCoupon\": 1,\n \"couponTitle\": \"Weekend sale\",\n \"couponExpiration\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`useCoupon: 1` adds a **Copy code** button and a *limited time offer* banner titled `couponTitle` (<=16 chars). `couponExpiration: 1` shows an expiry on the banner - at send time you pass `couponCode` and the `couponExpiration` timestamp.\n\nCoupon rules (all validated here): body <=600 chars, header none / image / video (no document -> 6), no footer (-> 8), `buttons` 2 or 4 (-> 9), at least one website button (a call-only CTA -> 10).\n\nMeta classifies coupon templates as marketing (`category: 2`)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"language\": 2,\n \"header\": 2,\n \"body\": \"Hi {{1}}, as a VIP customer here is {{2}} off your next order. Copy the code and use it at checkout before it expires.\",\n \"bodyVariableSample1\": \"Dana\",\n \"bodyVariableSample2\": \"20%\",\n \"buttons\": 2,\n \"callToAction\": 1,\n \"callToActionWebsiteText\": \"Shop now\",\n \"callToActionWebsiteType\": 1,\n \"callToActionWebsiteURL\": \"https://www.example.com/shop\",\n \"useCoupon\": 1,\n \"couponTitle\": \"Weekend sale\",\n \"couponExpiration\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`useCoupon: 1` adds a **Copy code** button and a *limited time offer* banner titled `couponTitle` (<=16 chars). `couponExpiration: 1` shows an expiry on the banner - at send time you pass `couponCode` and the `couponExpiration` timestamp.\n\nCoupon rules (all validated here): body <=600 chars, header none / image / video (no document -> 6), no footer (-> 8), `buttons` 2 or 4 (-> 9), at least one website button (a call-only CTA -> 10).\n\nMeta classifies coupon templates as marketing (`category: 2`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_weekend_coupon\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, as a VIP customer here is {{2}} off your next order. Copy the code and use it at checkout before it expires.\",\n \"category\": 2,\n \"reason\": 1\n}" } ] }, { "name": "Authentication (OTP) template", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_auth}}\",\n \"language\": 2,\n \"authentication\": 1,\n \"add_security_text\": 1,\n \"code_expiration\": 5\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`authentication: 1` creates a **one-time-passcode** template. Meta fixes the text per language (*\" is your verification code\"*) and adds a *Copy code* button - so there is no `header` / `body` / `footer` / `buttons` here.\n\n- `add_security_text: 1` appends *\"For your security, do not share this code\"*.\n- `code_expiration: 5` appends *\"This code expires in 5 minutes\"* (1-90; 0 = no expiry line).\n\nSend it with the `otp` field (see *sendTemplate -> Authentication*). Authentication templates are billed per message and are not available on `sendMultiTemplate`." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_auth}}\",\n \"language\": 2,\n \"authentication\": 1,\n \"add_security_text\": 1,\n \"code_expiration\": 5\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`authentication: 1` creates a **one-time-passcode** template. Meta fixes the text per language (*\" is your verification code\"*) and adds a *Copy code* button - so there is no `header` / `body` / `footer` / `buttons` here.\n\n- `add_security_text: 1` appends *\"For your security, do not share this code\"*.\n- `code_expiration: 5` appends *\"This code expires in 5 minutes\"* (1-90; 0 = no expiry line).\n\nSend it with the `otp` field (see *sendTemplate -> Authentication*). Authentication templates are billed per message and are not available on `sendMultiTemplate`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_login_code\",\n \"timestamp\": 1789900000,\n \"category\": 3,\n \"reason\": 1\n}" }, { "name": "Failure - code_expiration out of range (reason 34)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_auth}}\",\n \"language\": 2,\n \"authentication\": 1,\n \"add_security_text\": 1,\n \"code_expiration\": 5\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`authentication: 1` creates a **one-time-passcode** template. Meta fixes the text per language (*\" is your verification code\"*) and adds a *Copy code* button - so there is no `header` / `body` / `footer` / `buttons` here.\n\n- `add_security_text: 1` appends *\"For your security, do not share this code\"*.\n- `code_expiration: 5` appends *\"This code expires in 5 minutes\"* (1-90; 0 = no expiry line).\n\nSend it with the `otp` field (see *sendTemplate -> Authentication*). Authentication templates are billed per message and are not available on `sendMultiTemplate`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 34\n}" } ] }, { "name": "Carousel - image cards, website + quick reply", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"language\": 2,\n \"header\": 5,\n \"carouselMedia\": 1,\n \"carouselButtons\": 4,\n \"body\": \"Hi {{1}}, here are this week's picks for you - swipe to see them all.\",\n \"bodyVariableSample1\": \"Dana\",\n \"carouselCard1_body\": \"{{1}} - premium quality, in stock now.\",\n \"carouselCard1_var\": \"Leather wallet\",\n \"carouselCard1_websiteText\": \"View product\",\n \"carouselCard1_websiteType\": 2,\n \"carouselCard1_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard1_quickReply1\": \"I want this\",\n \"carouselCard2_body\": \"{{1}} - our best seller this month.\",\n \"carouselCard2_var\": \"Canvas backpack\",\n \"carouselCard2_websiteText\": \"View product\",\n \"carouselCard2_websiteType\": 2,\n \"carouselCard2_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard2_quickReply1\": \"I want this\",\n \"carouselCard3_body\": \"{{1}} - limited edition, few left.\",\n \"carouselCard3_var\": \"Travel mug\",\n \"carouselCard3_websiteText\": \"View product\",\n \"carouselCard3_websiteType\": 2,\n \"carouselCard3_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard3_quickReply1\": \"I want this\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 5` = **carousel**: a shared `body` above 2-10 swipeable cards. Every card has a media header (`carouselMedia` 1 image / 2 video, the actual picture is passed per message), an optional card body (<=160 chars, one optional `{{1}}` with its sample in `carouselCardX_var`) and up to two buttons.\n\n**Meta requires every card to have the same structure**, so the button layout is chosen once with `carouselButtons`:\n\n| `carouselButtons` | Card buttons | Card fields |\n|---|---|---|\n| 1 | website | `_websiteText`, `_websiteType`, `_websiteURL` |\n| 2 | quick reply | `_quickReply1` |\n| 3 | two quick replies | `_quickReply1`, `_quickReply2` |\n| 4 | website + quick reply | website trio + `_quickReply1` |\n| 5 | phone + website | `_callText`, `_callNumber` + website trio |\n| 6 | phone + quick reply | `_callText`, `_callNumber` + `_quickReply1` |\n\nThis sample uses **dynamic** card URLs (`_websiteType: 2`): every card is stored as `https://www.example.com/p/{{1}}` and you pass `carouselCardX_websiteVariable` per card when sending. All cards must use the same website type (reason 41). Cards must be numbered 1..N with no gaps (reason 37); a card body on some cards but not others -> 38.\n\nCarousel templates are always **marketing** (`category: 2`)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"language\": 2,\n \"header\": 5,\n \"carouselMedia\": 1,\n \"carouselButtons\": 4,\n \"body\": \"Hi {{1}}, here are this week's picks for you - swipe to see them all.\",\n \"bodyVariableSample1\": \"Dana\",\n \"carouselCard1_body\": \"{{1}} - premium quality, in stock now.\",\n \"carouselCard1_var\": \"Leather wallet\",\n \"carouselCard1_websiteText\": \"View product\",\n \"carouselCard1_websiteType\": 2,\n \"carouselCard1_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard1_quickReply1\": \"I want this\",\n \"carouselCard2_body\": \"{{1}} - our best seller this month.\",\n \"carouselCard2_var\": \"Canvas backpack\",\n \"carouselCard2_websiteText\": \"View product\",\n \"carouselCard2_websiteType\": 2,\n \"carouselCard2_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard2_quickReply1\": \"I want this\",\n \"carouselCard3_body\": \"{{1}} - limited edition, few left.\",\n \"carouselCard3_var\": \"Travel mug\",\n \"carouselCard3_websiteText\": \"View product\",\n \"carouselCard3_websiteType\": 2,\n \"carouselCard3_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard3_quickReply1\": \"I want this\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 5` = **carousel**: a shared `body` above 2-10 swipeable cards. Every card has a media header (`carouselMedia` 1 image / 2 video, the actual picture is passed per message), an optional card body (<=160 chars, one optional `{{1}}` with its sample in `carouselCardX_var`) and up to two buttons.\n\n**Meta requires every card to have the same structure**, so the button layout is chosen once with `carouselButtons`:\n\n| `carouselButtons` | Card buttons | Card fields |\n|---|---|---|\n| 1 | website | `_websiteText`, `_websiteType`, `_websiteURL` |\n| 2 | quick reply | `_quickReply1` |\n| 3 | two quick replies | `_quickReply1`, `_quickReply2` |\n| 4 | website + quick reply | website trio + `_quickReply1` |\n| 5 | phone + website | `_callText`, `_callNumber` + website trio |\n| 6 | phone + quick reply | `_callText`, `_callNumber` + `_quickReply1` |\n\nThis sample uses **dynamic** card URLs (`_websiteType: 2`): every card is stored as `https://www.example.com/p/{{1}}` and you pass `carouselCardX_websiteVariable` per card when sending. All cards must use the same website type (reason 41). Cards must be numbered 1..N with no gaps (reason 37); a card body on some cards but not others -> 38.\n\nCarousel templates are always **marketing** (`category: 2`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_products_carousel\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, here are this week's picks for you - swipe to see them all.\",\n \"category\": 2,\n \"reason\": 1\n}" }, { "name": "Failure - cards not numbered 1..N (reason 37)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"language\": 2,\n \"header\": 5,\n \"carouselMedia\": 1,\n \"carouselButtons\": 4,\n \"body\": \"Hi {{1}}, here are this week's picks for you - swipe to see them all.\",\n \"bodyVariableSample1\": \"Dana\",\n \"carouselCard1_body\": \"{{1}} - premium quality, in stock now.\",\n \"carouselCard1_var\": \"Leather wallet\",\n \"carouselCard1_websiteText\": \"View product\",\n \"carouselCard1_websiteType\": 2,\n \"carouselCard1_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard1_quickReply1\": \"I want this\",\n \"carouselCard2_body\": \"{{1}} - our best seller this month.\",\n \"carouselCard2_var\": \"Canvas backpack\",\n \"carouselCard2_websiteText\": \"View product\",\n \"carouselCard2_websiteType\": 2,\n \"carouselCard2_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard2_quickReply1\": \"I want this\",\n \"carouselCard3_body\": \"{{1}} - limited edition, few left.\",\n \"carouselCard3_var\": \"Travel mug\",\n \"carouselCard3_websiteText\": \"View product\",\n \"carouselCard3_websiteType\": 2,\n \"carouselCard3_websiteURL\": \"https://www.example.com/p\",\n \"carouselCard3_quickReply1\": \"I want this\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "`header: 5` = **carousel**: a shared `body` above 2-10 swipeable cards. Every card has a media header (`carouselMedia` 1 image / 2 video, the actual picture is passed per message), an optional card body (<=160 chars, one optional `{{1}}` with its sample in `carouselCardX_var`) and up to two buttons.\n\n**Meta requires every card to have the same structure**, so the button layout is chosen once with `carouselButtons`:\n\n| `carouselButtons` | Card buttons | Card fields |\n|---|---|---|\n| 1 | website | `_websiteText`, `_websiteType`, `_websiteURL` |\n| 2 | quick reply | `_quickReply1` |\n| 3 | two quick replies | `_quickReply1`, `_quickReply2` |\n| 4 | website + quick reply | website trio + `_quickReply1` |\n| 5 | phone + website | `_callText`, `_callNumber` + website trio |\n| 6 | phone + quick reply | `_callText`, `_callNumber` + `_quickReply1` |\n\nThis sample uses **dynamic** card URLs (`_websiteType: 2`): every card is stored as `https://www.example.com/p/{{1}}` and you pass `carouselCardX_websiteVariable` per card when sending. All cards must use the same website type (reason 41). Cards must be numbered 1..N with no gaps (reason 37); a card body on some cards but not others -> 38.\n\nCarousel templates are always **marketing** (`category: 2`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 37\n}" } ] }, { "name": "Carousel - video cards, two quick replies, no card text", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel_video}}\",\n \"language\": 2,\n \"header\": 5,\n \"carouselMedia\": 2,\n \"carouselButtons\": 3,\n \"body\": \"Hi {{1}}, two short clips from our workshop - which one would you like to join?\",\n \"bodyVariableSample1\": \"Dana\",\n \"carouselCard1_quickReply1\": \"Join Sunday\",\n \"carouselCard1_quickReply2\": \"Send details\",\n \"carouselCard2_quickReply1\": \"Join Tuesday\",\n \"carouselCard2_quickReply2\": \"Send details\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The minimal carousel: `carouselMedia: 2` (video cards), `carouselButtons: 3` (two quick replies per card), no card bodies at all (allowed - but then **no** card may have one). The per-message video of each card is passed as `carouselCardX_headerLink` when sending." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel_video}}\",\n \"language\": 2,\n \"header\": 5,\n \"carouselMedia\": 2,\n \"carouselButtons\": 3,\n \"body\": \"Hi {{1}}, two short clips from our workshop - which one would you like to join?\",\n \"bodyVariableSample1\": \"Dana\",\n \"carouselCard1_quickReply1\": \"Join Sunday\",\n \"carouselCard1_quickReply2\": \"Send details\",\n \"carouselCard2_quickReply1\": \"Join Tuesday\",\n \"carouselCard2_quickReply2\": \"Send details\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/createTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "createTemplate" ] }, "description": "The minimal carousel: `carouselMedia: 2` (video cards), `carouselButtons: 3` (two quick replies per card), no card bodies at all (allowed - but then **no** card may have one). The per-message video of each card is passed as `carouselCardX_headerLink` when sending." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_video_carousel\",\n \"timestamp\": 1789900000,\n \"body\": \"Hi {{1}}, two short clips from our workshop - which one would you like to join?\",\n \"category\": 2,\n \"reason\": 1\n}" } ] } ] }, { "name": "sendTemplate", "description": "`POST /whatsapp/v2/sendTemplate` - send an **approved** template to one recipient. This is the only way to message someone who has not written to you in the last 24 hours (or ever).\n\nEvery sample matches a template from the *createTemplate* folder (same `{{tpl_*}}` variable). If you already have your own approved templates, change the variable values in the **Variables** tab and adjust the `bodyVariableX` count to your template.\n\n**What you pass depends on the template**, not on your mood: exactly one `bodyVariableN` per `{{n}}` in the body, a `headerLink` if the template has a media header, `websiteVariable` if a URL button is dynamic, `otp` for an authentication template, `carouselCardX_*` for a carousel.\n\n> ⚠️ **Two different header code tables.** `createTemplate` uses `header` (1 none, 2 image, 3 video, 4 document, 5 carousel) while `sendTemplate` / `sendMultiTemplate` use `headerType` (1 none *or carousel*, 2 text, 3 image, 4 video, 5 document). The same picture header is `header: 2` when you create and `headerType: 3` when you send.\n\n**Delivery is asynchronous.** `OK` means we validated and queued the message and gives you a `unique` id. Delivery, read and failure statuses arrive on your webhook (`hook: update`, `ack` 1 sent / 2 delivered / 3 read / 0 failed, and `hook: system`, `type: messages` with the failure code - e.g. 12 template not approved, 14 marketing limit reached, 8 window closed for a non-template). See folder *5 - Webhooks*.\n\n`templateTimeLeft` in the response is the number of minutes left in the customer's 24-hour reply window (0 = closed, so a template was indeed required).\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `from` | yes | Your WhatsApp number |\n| `to` | yes | Recipient: international number without `+` (e.g. `972501234567`) **or** a user id (e.g. `IL.1605856887361213`). Empty / invalid -> 4 |\n| `name` | yes | Template name (case-insensitive). Unknown -> 12 |\n| `headerType` | yes | 1 none (also for carousel), 2 text, 3 image, 4 video, 5 document -> else 14 |\n| `headerVariable` | `headerType` 2 | Value of the `{{1}}` in a text header |\n| `headerLink` | `headerType` 3/4/5 | Public https URL. Image jpg/png <=5MB, video mp4 <=16MB, document pdf <=100MB |\n| `pdfFilename` | no (`headerType` 5) | File name shown in the chat. Default: the file name taken from the URL |\n| `bodyVariable1`..`bodyVariable10` | one per `{{n}}` in the body | Fill them consecutively, never empty. <=1024 chars each -> 19; wrong count -> 17. Line breaks and tabs are removed |\n| `websiteVariable` / `websiteVariable2` | dynamic URL buttons | The value appended to the button URL (1st / 2nd URL button) |\n| `quickReply1_id`..`quickReply10_id` | no | Your own id for each quick reply button (string, <=256 chars incl. the template name) -> 28. Comes back as `caption` on the `type: button` webhook |\n| `couponCode` | coupon templates | The code the user copies, <=15 chars -> 20 |\n| `couponExpiration` | no | UNIX seconds (UTC) when the offer expires |\n| `otp` | authentication templates | The one-time code, <=15 chars -> 23 |\n| `localStorage` | no | 1 = we download the media and upload it to WhatsApp ourselves (for media servers that block WhatsApp). Slower. Failure -> 24 |\n| `carouselCardX_*` | carousel templates | One set per card, see the carousel samples -> 29 / 30 / 31 / 32 / 33 / 34 |\n| `showRequest` | no | 1 = echo the request back as `originalRequest` |\n\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - queued for delivery (watch the `hook: update` webhook for the status) |\n| 2 | `from` does not exist, body is not valid JSON, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 4 | `to` is empty or not a valid international number / user id |\n| 12 | `name` is not one of your templates (or the template list could not be loaded) |\n| 14 | `headerType` missing or not 1-5 |\n| 17 | The number of `bodyVariableX` you sent differs from the variables in the template body |\n| 19 | A `bodyVariableX` is longer than 1024 chars |\n| 20 | `couponCode` is longer than 15 chars |\n| 23 | Authentication template without `otp`, or `otp` >15 chars |\n| 24 | `localStorage: 1` but we could not download / upload the `headerLink` |\n| 28 | A `quickReplyX_id` is not a string or too long |\n| 29 | Carousel: a `carouselCardX_` index does not exist in the template |\n| 30 | Carousel: `carouselCardX_bodyVariable` missing, or the card body would exceed 160 chars |\n| 31 | Carousel: `carouselCardX_headerLink` missing or not an http(s) URL |\n| 32 | Carousel: `carouselCardX_websiteVariable` missing for a dynamic URL card button |\n| 33 | Carousel: a `carouselCardX_quickReplyN_id` is not a string or too long |\n| 34 | Carousel + `localStorage: 1`: a card media could not be downloaded / uploaded |", "item": [ { "name": "Text template - no variables", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text}}\",\n \"headerType\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "The minimal send: a text-only template without variables needs just `from`, `to`, `name` and `headerType: 1`.\n\n`to` is the customer's number in international format without `+` (we strip spaces, dashes and a leading `9720` -> `972`), or the user id from your webhook (`IL.16058...`)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text}}\",\n \"headerType\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "The minimal send: a text-only template without variables needs just `from`, `to`, `name` and `headerType: 1`.\n\n`to` is the customer's number in international format without `+` (we strip spaces, dashes and a leading `9720` -> `972`), or the user id from your webhook (`IL.16058...`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Our store is open today until 20:00. Come say hi!\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - template name unknown (reason 12)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text}}\",\n \"headerType\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "The minimal send: a text-only template without variables needs just `from`, `to`, `name` and `headerType: 1`.\n\n`to` is the customer's number in international format without `+` (we strip spaces, dashes and a leading `9720` -> `972`), or the user id from your webhook (`IL.16058...`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 12\n}" }, { "name": "Failure - wrong apiKey header (reason 3)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text}}\",\n \"headerType\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "The minimal send: a text-only template without variables needs just `from`, `to`, `name` and `headerType: 1`.\n\n`to` is the customer's number in international format without `+` (we strip spaces, dashes and a leading `9720` -> `972`), or the user id from your webhook (`IL.16058...`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 3\n}" }, { "name": "Failure - invalid `to` (reason 4)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text}}\",\n \"headerType\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "The minimal send: a text-only template without variables needs just `from`, `to`, `name` and `headerType: 1`.\n\n`to` is the customer's number in international format without `+` (we strip spaces, dashes and a leading `9720` -> `972`), or the user id from your webhook (`IL.16058...`)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 4\n}" } ] }, { "name": "Text template with body variables", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "One `bodyVariableN` per `{{n}}` in the template body - here two. The count must match exactly (reason 17), so never leave one empty. Tabs and line breaks inside a variable are removed; keep each value short and on one line.\n\nThe response `body` is the final text with your variables filled in - store it with the `unique` as your copy of what the customer received." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "One `bodyVariableN` per `{{n}}` in the template body - here two. The count must match exactly (reason 17), so never leave one empty. Tabs and line breaks inside a variable are removed; keep each value short and on one line.\n\nThe response `body` is the final text with your variables filled in - store it with the `unique` as your copy of what the customer received." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, your order 4711 was received. We will let you know when it ships.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - variable count mismatch (reason 17)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "One `bodyVariableN` per `{{n}}` in the template body - here two. The count must match exactly (reason 17), so never leave one empty. Tabs and line breaks inside a variable are removed; keep each value short and on one line.\n\nThe response `body` is the final text with your variables filled in - store it with the `unique` as your copy of what the customer received." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 17\n}" } ] }, { "name": "Hebrew template with Hebrew variables", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_hebrew}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"דנה\",\n \"bodyVariable2\": \"4711\",\n \"quickReply1_id\": \"TRACK\",\n \"quickReply2_id\": \"TALK\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Variables are plain UTF-8, so Hebrew (or Arabic, Russian...) values work as-is. The template's language is fixed when it was created - there is no language field when sending.\n\n`quickReply1_id` / `quickReply2_id` are your own ids for the two quick reply buttons; when the customer taps *מעקב משלוח* you get a `type: button` webhook with `caption: \"TRACK\"` and `template` = the template name." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_hebrew}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"דנה\",\n \"bodyVariable2\": \"4711\",\n \"quickReply1_id\": \"TRACK\",\n \"quickReply2_id\": \"TALK\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Variables are plain UTF-8, so Hebrew (or Arabic, Russian...) values work as-is. The template's language is fixed when it was created - there is no language field when sending.\n\n`quickReply1_id` / `quickReply2_id` are your own ids for the two quick reply buttons; when the customer taps *מעקב משלוח* you get a `type: button` webhook with `caption: \"TRACK\"` and `template` = the template name." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"שלום דנה, ההזמנה שלך מספר 4711 התקבלה בהצלחה. נעדכן אותך כשהיא תישלח.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Image header", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_image}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 3` + `headerLink` = the picture shown above the text. Public https URL, jpg or png, up to 5MB. WhatsApp downloads it from your server at send time - the URL must not require a login and should serve the correct `Content-Type`.\n\nThe website button of this template is static, so nothing else to pass." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_image}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 3` + `headerLink` = the picture shown above the text. Public https URL, jpg or png, up to 5MB. WhatsApp downloads it from your server at send time - the URL must not require a login and should serve the correct `Content-Type`.\n\nThe website button of this template is static, so nothing else to pass." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, this week only: 20% off everything in the summer collection. Tap below to shop.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Image header - localStorage (we upload the media)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_image}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"localStorage\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Some media servers (WAF, geo-blocking, private CDNs) refuse WhatsApp's download. With `localStorage: 1` **we** download the file first (browser-like request, 10s timeout, 2 retries), upload it to WhatsApp and send the resulting media id instead of your link.\n\nCosts a few hundred milliseconds. If the download or upload fails you get reason **24** synchronously instead of a failed webhook later. Works for image, video and document headers." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_image}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"localStorage\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Some media servers (WAF, geo-blocking, private CDNs) refuse WhatsApp's download. With `localStorage: 1` **we** download the file first (browser-like request, 10s timeout, 2 retries), upload it to WhatsApp and send the resulting media id instead of your link.\n\nCosts a few hundred milliseconds. If the download or upload fails you get reason **24** synchronously instead of a failed webhook later. Works for image, video and document headers." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, this week only: 20% off everything in the summer collection. Tap below to shop.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - media could not be fetched (reason 24)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_image}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"localStorage\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Some media servers (WAF, geo-blocking, private CDNs) refuse WhatsApp's download. With `localStorage: 1` **we** download the file first (browser-like request, 10s timeout, 2 retries), upload it to WhatsApp and send the resulting media id instead of your link.\n\nCosts a few hundred milliseconds. If the download or upload fails you get reason **24** synchronously instead of a failed webhook later. Works for image, video and document headers." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 24\n}" } ] }, { "name": "Video header + quick reply ids", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_video}}\",\n \"headerType\": 4,\n \"headerLink\": \"{{sample_video_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 4` = video header (mp4, up to 16MB, public https URL).\n\n`quickReplyN_id` is optional but strongly recommended: it is the value you get back as `caption` on the `type: button` webhook when the customer taps button N, so your code can branch on `MORE_INFO` instead of on the translated button text. Any string up to ~240 chars." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_video}}\",\n \"headerType\": 4,\n \"headerLink\": \"{{sample_video_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 4` = video header (mp4, up to 16MB, public https URL).\n\n`quickReplyN_id` is optional but strongly recommended: it is the value you get back as `caption` on the `type: button` webhook when the customer taps button N, so your code can branch on `MORE_INFO` instead of on the translated button text. Any string up to ~240 chars." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, watch our new espresso machine in action. Interested? Pick an option below.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Document header + file name + dynamic URL", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_document}}\",\n \"headerType\": 5,\n \"headerLink\": \"{{sample_document_url}}\",\n \"pdfFilename\": \"Invoice 4711 - August 2026\",\n \"bodyVariable1\": \"Dana Levi\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"350 USD\",\n \"websiteVariable\": \"inv-4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 5` = document header (PDF up to 100MB). `pdfFilename` is the name the customer sees on the attachment (extension optional); without it we use the file name from the URL.\n\nThe template's *Pay online* button is a **dynamic** URL, so `websiteVariable` is mandatory: it is appended to the stored URL -> `https://www.example.com/pay/inv-4711`. Pass it raw (no URL-encoding); `?`, `=` and `&` are allowed." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_document}}\",\n \"headerType\": 5,\n \"headerLink\": \"{{sample_document_url}}\",\n \"pdfFilename\": \"Invoice 4711 - August 2026\",\n \"bodyVariable1\": \"Dana Levi\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"350 USD\",\n \"websiteVariable\": \"inv-4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 5` = document header (PDF up to 100MB). `pdfFilename` is the name the customer sees on the attachment (extension optional); without it we use the file name from the URL.\n\nThe template's *Pay online* button is a **dynamic** URL, so `websiteVariable` is mandatory: it is appended to the stored URL -> `https://www.example.com/pay/inv-4711`. Pass it raw (no URL-encoding); `?`, `=` and `&` are allowed." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Dear Dana Levi, your invoice for August 2026 is attached. The total amount is 350 USD. Thank you for your business.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Call + website + quick replies", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_buttons}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"Sunday 14 September\",\n \"bodyVariable3\": \"10:30\",\n \"quickReply1_id\": \"CONFIRM\",\n \"quickReply2_id\": \"RESCHEDULE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Call buttons and static website buttons need nothing at send time - they are part of the approved template. Only quick replies (optional ids) and dynamic URLs (`websiteVariable`) carry per-message data." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_buttons}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"Sunday 14 September\",\n \"bodyVariable3\": \"10:30\",\n \"quickReply1_id\": \"CONFIRM\",\n \"quickReply2_id\": \"RESCHEDULE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Call buttons and static website buttons need nothing at send time - they are part of the approved template. Only quick replies (optional ids) and dynamic URLs (`websiteVariable`) carry per-message data." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, this is a reminder of your appointment on Sunday 14 September at 10:30. Please arrive 10 minutes early.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Two website buttons - second one dynamic", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_two_sites}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"Friday 20:00\",\n \"websiteVariable2\": \"bk-88213\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`websiteVariable` feeds the **first** URL button of the template and `websiteVariable2` the **second**, counting URL buttons only (call and quick reply buttons in between do not shift the numbering). Here the first URL is static, so only `websiteVariable2` is passed -> `https://www.example.com/booking/bk-88213`." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_two_sites}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"Friday 20:00\",\n \"websiteVariable2\": \"bk-88213\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`websiteVariable` feeds the **first** URL button of the template and `websiteVariable2` the **second**, counting URL buttons only (call and quick reply buttons in between do not shift the numbering). Here the first URL is static, so only `websiteVariable2` is passed -> `https://www.example.com/booking/bk-88213`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, your table for Friday 20:00 is booked. You can view the menu or manage your booking below.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Coupon code + expiration", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\",\n \"couponCode\": \"SAVE20\",\n \"couponExpiration\": \"{{coupon_expiration}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`couponCode` (<=15 chars) is what the *Copy code* button copies. `couponExpiration` is a UNIX timestamp in **seconds, UTC** - the offer banner shows a countdown to it. This sample's pre-request script sets `{{coupon_expiration}}` to 7 days from now.\n\nBoth are optional on the API level, but a coupon template sent without `couponCode` will be rejected by WhatsApp (failed status on the webhook)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\",\n \"couponCode\": \"SAVE20\",\n \"couponExpiration\": \"{{coupon_expiration}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`couponCode` (<=15 chars) is what the *Copy code* button copies. `couponExpiration` is a UNIX timestamp in **seconds, UTC** - the offer banner shows a countdown to it. This sample's pre-request script sets `{{coupon_expiration}}` to 7 days from now.\n\nBoth are optional on the API level, but a coupon template sent without `couponCode` will be rejected by WhatsApp (failed status on the webhook)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, as a VIP customer here is 20% off your next order. Copy the code and use it at checkout before it expires.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - couponCode longer than 15 chars (reason 20)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\",\n \"couponCode\": \"SAVE20\",\n \"couponExpiration\": \"{{coupon_expiration}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`couponCode` (<=15 chars) is what the *Copy code* button copies. `couponExpiration` is a UNIX timestamp in **seconds, UTC** - the offer banner shows a countdown to it. This sample's pre-request script sets `{{coupon_expiration}}` to 7 days from now.\n\nBoth are optional on the API level, but a coupon template sent without `couponCode` will be rejected by WhatsApp (failed status on the webhook)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 20\n}" } ], "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// couponExpiration is UNIX seconds (UTC). Here: 7 days from now.", "pm.collectionVariables.set('coupon_expiration', String(Math.floor(Date.now() / 1000) + 7 * 24 * 3600));" ] } } ] }, { "name": "Authentication (OTP)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_auth}}\",\n \"headerType\": 1,\n \"otp\": \"{{otp_code}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "For an authentication template the **only** content field is `otp` (mandatory, <=15 chars) - it fills both the message text and the *Copy code* button. `bodyVariableX` is ignored for this category. The pre-request script generates a random 6-digit `{{otp_code}}`.\n\nAuthentication messages are billed per message, are delivered to phones only (not WhatsApp Web) and require the account's daily limit to be at least 1000." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_auth}}\",\n \"headerType\": 1,\n \"otp\": \"{{otp_code}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "For an authentication template the **only** content field is `otp` (mandatory, <=15 chars) - it fills both the message text and the *Copy code* button. `bodyVariableX` is ignored for this category. The pre-request script generates a random 6-digit `{{otp_code}}`.\n\nAuthentication messages are billed per message, are delivered to phones only (not WhatsApp Web) and require the account's daily limit to be at least 1000." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"482913 is your verification code. For your security, do not share this code. This code expires in 5 minutes.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - otp missing (reason 23)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_auth}}\",\n \"headerType\": 1,\n \"otp\": \"{{otp_code}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "For an authentication template the **only** content field is `otp` (mandatory, <=15 chars) - it fills both the message text and the *Copy code* button. `bodyVariableX` is ignored for this category. The pre-request script generates a random 6-digit `{{otp_code}}`.\n\nAuthentication messages are billed per message, are delivered to phones only (not WhatsApp Web) and require the account's daily limit to be at least 1000." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 23\n}" } ], "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// A fresh 6-digit one-time code for every run - replace with your own code.", "pm.collectionVariables.set('otp_code', String(Math.floor(100000 + Math.random() * 900000)));" ] } } ] }, { "name": "Carousel - image cards, dynamic URL + quick reply", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_bodyVariable\": \"Travel mug\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "A carousel template is sent with **`headerType: 1`** (the cards replace the header) plus one set of fields per card, `X` = the card number in the template:\n\n| Card field | When | Rules |\n|---|---|---|\n| `carouselCardX_headerLink` | always | Public https image / video URL (the card media type is fixed by the template) -> 31 |\n| `carouselCardX_bodyVariable` | card body has `{{1}}` | Body after substitution <=160 chars -> 30 |\n| `carouselCardX_websiteVariable` | card URL button is dynamic | Appended to the card URL -> 32 (`_websiteVariable2` for a second dynamic URL) |\n| `carouselCardX_quickReply1_id` / `_quickReply2_id` | optional | Your id, returned as `caption` on tap -> 33 |\n\nYou must send exactly the cards the template has (numbered from 1); an index the template does not have -> 29. `bodyVariable1` still fills the `{{1}}` of the shared body above the cards." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_bodyVariable\": \"Travel mug\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "A carousel template is sent with **`headerType: 1`** (the cards replace the header) plus one set of fields per card, `X` = the card number in the template:\n\n| Card field | When | Rules |\n|---|---|---|\n| `carouselCardX_headerLink` | always | Public https image / video URL (the card media type is fixed by the template) -> 31 |\n| `carouselCardX_bodyVariable` | card body has `{{1}}` | Body after substitution <=160 chars -> 30 |\n| `carouselCardX_websiteVariable` | card URL button is dynamic | Appended to the card URL -> 32 (`_websiteVariable2` for a second dynamic URL) |\n| `carouselCardX_quickReply1_id` / `_quickReply2_id` | optional | Your id, returned as `caption` on tap -> 33 |\n\nYou must send exactly the cards the template has (numbered from 1); an index the template does not have -> 29. `bodyVariable1` still fills the `{{1}}` of the shared body above the cards." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, here are this week's picks for you - swipe to see them all.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Failure - card media URL missing (reason 31)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_bodyVariable\": \"Travel mug\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "A carousel template is sent with **`headerType: 1`** (the cards replace the header) plus one set of fields per card, `X` = the card number in the template:\n\n| Card field | When | Rules |\n|---|---|---|\n| `carouselCardX_headerLink` | always | Public https image / video URL (the card media type is fixed by the template) -> 31 |\n| `carouselCardX_bodyVariable` | card body has `{{1}}` | Body after substitution <=160 chars -> 30 |\n| `carouselCardX_websiteVariable` | card URL button is dynamic | Appended to the card URL -> 32 (`_websiteVariable2` for a second dynamic URL) |\n| `carouselCardX_quickReply1_id` / `_quickReply2_id` | optional | Your id, returned as `caption` on tap -> 33 |\n\nYou must send exactly the cards the template has (numbered from 1); an index the template does not have -> 29. `bodyVariable1` still fills the `{{1}}` of the shared body above the cards." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 31\n}" }, { "name": "Failure - card website variable missing (reason 32)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_bodyVariable\": \"Travel mug\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "A carousel template is sent with **`headerType: 1`** (the cards replace the header) plus one set of fields per card, `X` = the card number in the template:\n\n| Card field | When | Rules |\n|---|---|---|\n| `carouselCardX_headerLink` | always | Public https image / video URL (the card media type is fixed by the template) -> 31 |\n| `carouselCardX_bodyVariable` | card body has `{{1}}` | Body after substitution <=160 chars -> 30 |\n| `carouselCardX_websiteVariable` | card URL button is dynamic | Appended to the card URL -> 32 (`_websiteVariable2` for a second dynamic URL) |\n| `carouselCardX_quickReply1_id` / `_quickReply2_id` | optional | Your id, returned as `caption` on tap -> 33 |\n\nYou must send exactly the cards the template has (numbered from 1); an index the template does not have -> 29. `bodyVariable1` still fills the `{{1}}` of the shared body above the cards." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 32\n}" } ] }, { "name": "Carousel - video cards + localStorage", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel_video}}\",\n \"headerType\": 1,\n \"localStorage\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_video_url}}\",\n \"carouselCard1_quickReply1_id\": \"JOIN_SUN\",\n \"carouselCard1_quickReply2_id\": \"DETAILS_SUN\",\n \"carouselCard2_headerLink\": \"{{sample_video_url}}\",\n \"carouselCard2_quickReply1_id\": \"JOIN_TUE\",\n \"carouselCard2_quickReply2_id\": \"DETAILS_TUE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Video cards work the same way - `carouselCardX_headerLink` points at an mp4. With `localStorage: 1` every card's media is downloaded and uploaded by us before sending (one upload per card); a card that cannot be fetched returns reason **34** and nothing is sent.\n\nThis template has no card bodies, so no `_bodyVariable`; its buttons are two quick replies per card, so the ids are optional." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_carousel_video}}\",\n \"headerType\": 1,\n \"localStorage\": 1,\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_headerLink\": \"{{sample_video_url}}\",\n \"carouselCard1_quickReply1_id\": \"JOIN_SUN\",\n \"carouselCard1_quickReply2_id\": \"DETAILS_SUN\",\n \"carouselCard2_headerLink\": \"{{sample_video_url}}\",\n \"carouselCard2_quickReply1_id\": \"JOIN_TUE\",\n \"carouselCard2_quickReply2_id\": \"DETAILS_TUE\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Video cards work the same way - `carouselCardX_headerLink` points at an mp4. With `localStorage: 1` every card's media is downloaded and uploaded by us before sending (one upload per card); a card that cannot be fetched returns reason **34** and nothing is sent.\n\nThis template has no card bodies, so no `_bodyVariable`; its buttons are two quick replies per card, so the ids are optional." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, two short clips from our workshop - which one would you like to join?\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "Text header (template with a text header)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"your_template_with_text_header\",\n \"headerType\": 2,\n \"headerVariable\": \"Order 4711\",\n \"bodyVariable1\": \"Dana\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`headerType: 2` is for templates whose header is a **text line with a `{{1}}` variable** - `headerVariable` fills it. `createTemplate` does not build text headers, so this applies to templates created in Meta Business Manager or by our team; replace `name` with yours.\n\nA template with a fixed text header (no variable) is sent with `headerType: 1`." }, "response": [] }, { "name": "Send to a user id (username feature)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Customers who hide their phone number behind a WhatsApp **username** reach you with a user id instead of a number: two-letter country code, a dot and 16 digits (`IL.1605856887361213`, the `from_id` of your incoming webhook). Put it in `to` exactly as received - every send endpoint accepts it. You cannot address a `@username` directly, and the id is scoped to your business." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to_user_id}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "Customers who hide their phone number behind a WhatsApp **username** reach you with a user id instead of a number: two-letter country code, a dot and 16 digits (`IL.1605856887361213`, the `from_id` of your incoming webhook). Put it in `to` exactly as received - every send endpoint accepts it. You cannot address a `@username` directly, and the id is scoped to your business." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"IL.1605856887361213\",\n \"body\": \"Hi Dana, your order 4711 was received. We will let you know when it ships.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "With showRequest (debug echo)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\",\n \"showRequest\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`showRequest: 1` adds `originalRequest` to the response - the request as we understood it (without `apiKey`, empty fields removed). Handy while integrating to verify that your variables landed where you think." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\",\n \"showRequest\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendTemplate" ] }, "description": "`showRequest: 1` adds `originalRequest` to the response - the request as we understood it (without `apiKey`, empty fields removed). Handy while integrating to verify that your variables landed where you think." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, your order 4711 was received. We will let you know when it ships.\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1,\n \"originalRequest\": {\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"name\": \"postman_welcome_text\",\n \"headerType\": 1,\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n }\n}" } ] } ] }, { "name": "sendMultiTemplate", "description": "`POST /whatsapp/v2/sendMultiTemplate` - send the **same template to many recipients in one call**, each with their own variables. Built for campaigns and bulk notifications - thousands of destinations in one call are fine.\n\nEverything that is identical for all recipients (`name`, `headerType`, `headerLink`, `pdfFilename`, `couponExpiration`, carousel card fields) is **top-level**; everything personal (`to`, `bodyVariableN`, `websiteVariable`, `couponCode`, `quickReplyN_id`) goes **inside each `destinations[]` object**.\n\nRules per destination are the same as *sendTemplate*. A bad destination is **rejected individually** (it appears in the response with its own `reason`) while the good ones are still sent - the call fails as a whole only when nothing was valid. Authentication (OTP) templates are not available here.\n\n> ⚠️ **Two different header code tables.** `createTemplate` uses `header` (1 none, 2 image, 3 video, 4 document, 5 carousel) while `sendTemplate` / `sendMultiTemplate` use `headerType` (1 none *or carousel*, 2 text, 3 image, 4 video, 5 document). The same picture header is `header: 2` when you create and `headerType: 3` when you send.\n\n**Delivery is asynchronous** - one `unique` per accepted destination, statuses on your webhook exactly like a single *sendTemplate*.\n\n| Field | Where | Mandatory | Rules |\n|---|---|---|---|\n| `from` | top | yes | Your WhatsApp number |\n| `name` | top | yes | Template name -> 12 |\n| `headerType` | top | yes (ignored for carousel) | 1 none, 2 text, 3 image, 4 video, 5 document -> 14 |\n| `headerVariable` | top | `headerType` 2 | Text header value |\n| `headerLink` | top | `headerType` 3/4/5 | Public https media URL, same file for everyone |\n| `pdfFilename` | top | no | Document name shown in the chat |\n| `couponExpiration` | top | no | UNIX seconds (UTC) |\n| `localStorage` | top | no | 1 = we download + upload the media **once** and send it by id to everyone. If that fails we fall back to your link |\n| `showBody` | top | no | 1 = add the rendered `body` to every accepted destination (adds ~1KB per recipient - avoid on big lists) |\n| `showRequest` | top | no | 1 = echo the request |\n| `carouselCardX_*` | top | carousel templates | `_headerLink`, `_websiteVariable`, `_quickReplyN_id` - same for all recipients -> 29-33 |\n| `destinations` | top | yes | Array of objects, at least one -> 23 |\n| `destinations[].to` | each | yes | Number without `+` or user id -> 26 |\n| `destinations[].bodyVariable1..10` | each | per template | One per `{{n}}`, never empty |\n| `destinations[].websiteVariable` / `websiteVariable2` | each | dynamic URL buttons | Appended to the button URL |\n| `destinations[].couponCode` | each | coupon templates | <=15 chars -> 27 |\n| `destinations[].quickReply1_id..10_id` | each | no | Strings -> 28 |\n| `destinations[].carouselCardX_bodyVariable` | each | carousel card body has `{{1}}` | Personal card text -> 30 |\n\n**Response.** `accepted` + `rejected` + `failed` = the number of destinations you sent. `destinations[]` keeps your order: an accepted entry has `unique` (+ `body` with `showBody`), a rejected one has `to` + `reason` (25-28) and a failed one `to` + `reason: 22` (queueing problem - resend only those).\n\n| reason | Meaning |\n|---|---|\n| 1 | OK - see `accepted` / `rejected` / `failed` and the per-destination list |\n| 2 | `from` does not exist, body is not valid JSON, `couponExpiration` not numeric, or an internal error |\n| 3 | Wrong `apiKey` header |\n| 12 | `name` is not one of your templates |\n| 14 | `headerType` missing or not 1-5 |\n| 22 | *per destination*: could not be queued - nothing was sent to it, re-send just these |\n| 23 | `destinations` missing, not an array, or empty |\n| 25 | *per destination*: the entry is not a JSON object |\n| 26 | *per destination*: `to` missing or invalid (also the top-level reason when no destination was valid) |\n| 27 | *per destination*: `couponCode` longer than 15 chars |\n| 28 | *per destination*: a `quickReplyN_id` is not a string or too long |\n| 29 | Carousel: a `carouselCardX_` index does not exist in the template |\n| 30 | Carousel: `carouselCardX_bodyVariable` missing or card body >160 chars after substitution |\n| 31 | Carousel: `carouselCardX_headerLink` missing or not an http(s) URL |\n| 32 | Carousel: `carouselCardX_websiteVariable` missing for a dynamic URL card button |\n| 33 | Carousel: a `carouselCardX_quickReplyN_id` is not a string or too long |", "item": [ { "name": "Text template - personal variables per recipient", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"showBody\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"4712\"\n },\n {\n \"to\": \"0501234\",\n \"bodyVariable1\": \"Broken\",\n \"bodyVariable2\": \"0000\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Three destinations: a phone number, a user id and - on purpose - an invalid number, so you can see the mixed response: two `unique` ids and one `reason: 26` entry, `accepted: 2`, `rejected: 1`. The valid ones are sent regardless.\n\n`showBody: 1` returns each recipient's final text - useful to store per recipient, but leave it off for large campaigns." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"showBody\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"4712\"\n },\n {\n \"to\": \"0501234\",\n \"bodyVariable1\": \"Broken\",\n \"bodyVariable2\": \"0000\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Three destinations: a phone number, a user id and - on purpose - an invalid number, so you can see the mixed response: two `unique` ids and one `reason: 26` entry, `accepted: 2`, `rejected: 1`. The valid ones are sent regardless.\n\n`showBody: 1` returns each recipient's final text - useful to store per recipient, but leave it off for large campaigns." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"accepted\": 2,\n \"rejected\": 1,\n \"failed\": 0,\n \"destinations\": [\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"972501234567\",\n \"body\": \"Hi Dana, your order 4711 was received. We will let you know when it ships.\"\n },\n {\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"to\": \"IL.1605856887361213\",\n \"body\": \"Hi Yossi, your order 4712 was received. We will let you know when it ships.\"\n },\n {\n \"to\": \"0501234\",\n \"reason\": 26\n }\n ],\n \"reason\": 1\n}" }, { "name": "Failure - destinations missing (reason 23)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"showBody\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"4712\"\n },\n {\n \"to\": \"0501234\",\n \"bodyVariable1\": \"Broken\",\n \"bodyVariable2\": \"0000\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Three destinations: a phone number, a user id and - on purpose - an invalid number, so you can see the mixed response: two `unique` ids and one `reason: 26` entry, `accepted: 2`, `rejected: 1`. The valid ones are sent regardless.\n\n`showBody: 1` returns each recipient's final text - useful to store per recipient, but leave it off for large campaigns." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 23\n}" }, { "name": "Failure - no valid destination at all (reason 26)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text_vars}}\",\n \"headerType\": 1,\n \"showBody\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"4712\"\n },\n {\n \"to\": \"0501234\",\n \"bodyVariable1\": \"Broken\",\n \"bodyVariable2\": \"0000\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Three destinations: a phone number, a user id and - on purpose - an invalid number, so you can see the mixed response: two `unique` ids and one `reason: 26` entry, `accepted: 2`, `rejected: 1`. The valid ones are sent regardless.\n\n`showBody: 1` returns each recipient's final text - useful to store per recipient, but leave it off for large campaigns." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 26,\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"destinations\": [\n {\n \"to\": \"0501234\",\n \"reason\": 26\n },\n {\n \"to\": \"abc\",\n \"reason\": 26\n }\n ]\n}" } ] }, { "name": "Image header shared by all + quick reply ids", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_video}}\",\n \"headerType\": 4,\n \"headerLink\": \"{{sample_video_url}}\",\n \"localStorage\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "The media header is top-level (`headerType: 4` + `headerLink`) - one file for everyone. With `localStorage: 1` we fetch and upload it **once** and every recipient gets the same media id, which is the recommended setting for campaigns (WhatsApp does not re-download your file per recipient).\n\nQuick reply ids are per destination, so you may vary them per recipient if you need to." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_video}}\",\n \"headerType\": 4,\n \"headerLink\": \"{{sample_video_url}}\",\n \"localStorage\": 1,\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"espresso machine\",\n \"quickReply1_id\": \"MORE_INFO\",\n \"quickReply2_id\": \"BOOK_DEMO\",\n \"quickReply3_id\": \"NOT_INTERESTED\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "The media header is top-level (`headerType: 4` + `headerLink`) - one file for everyone. With `localStorage: 1` we fetch and upload it **once** and every recipient gets the same media id, which is the recommended setting for campaigns (WhatsApp does not re-download your file per recipient).\n\nQuick reply ids are per destination, so you may vary them per recipient if you need to." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"accepted\": 2,\n \"rejected\": 0,\n \"failed\": 0,\n \"destinations\": [\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"972501234567\"\n },\n {\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"to\": \"IL.1605856887361213\"\n }\n ],\n \"reason\": 1\n}" } ] }, { "name": "Document header + personal dynamic URL", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_document}}\",\n \"headerType\": 5,\n \"headerLink\": \"{{sample_document_url}}\",\n \"pdfFilename\": \"Invoice August 2026\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana Levi\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"350 USD\",\n \"websiteVariable\": \"inv-4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi Cohen\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"120 USD\",\n \"websiteVariable\": \"inv-4712\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "`websiteVariable` lives inside each destination, so every customer gets their own link (`https://www.example.com/pay/inv-4711`, `.../inv-4712`). The PDF itself (`headerLink`) and its display name are shared. If every customer needs a different PDF, use *sendTemplate* in a loop instead." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_document}}\",\n \"headerType\": 5,\n \"headerLink\": \"{{sample_document_url}}\",\n \"pdfFilename\": \"Invoice August 2026\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana Levi\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"350 USD\",\n \"websiteVariable\": \"inv-4711\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi Cohen\",\n \"bodyVariable2\": \"August 2026\",\n \"bodyVariable3\": \"120 USD\",\n \"websiteVariable\": \"inv-4712\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "`websiteVariable` lives inside each destination, so every customer gets their own link (`https://www.example.com/pay/inv-4711`, `.../inv-4712`). The PDF itself (`headerLink`) and its display name are shared. If every customer needs a different PDF, use *sendTemplate* in a loop instead." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"accepted\": 2,\n \"rejected\": 0,\n \"failed\": 0,\n \"destinations\": [\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"972501234567\"\n },\n {\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"to\": \"IL.1605856887361213\"\n }\n ],\n \"reason\": 1\n}" } ] }, { "name": "Coupon - personal code, shared expiration", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"couponExpiration\": \"{{coupon_expiration}}\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\",\n \"couponCode\": \"DANA20\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"15%\",\n \"couponCode\": \"YOSSI15\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "`couponCode` is per destination (<=15 chars, else that destination is rejected with 27); `couponExpiration` is one UNIX timestamp for the whole campaign (pre-request script: 7 days from now)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_coupon}}\",\n \"headerType\": 3,\n \"headerLink\": \"{{sample_image_url}}\",\n \"couponExpiration\": \"{{coupon_expiration}}\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"bodyVariable2\": \"20%\",\n \"couponCode\": \"DANA20\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"bodyVariable2\": \"15%\",\n \"couponCode\": \"YOSSI15\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "`couponCode` is per destination (<=15 chars, else that destination is rejected with 27); `couponExpiration` is one UNIX timestamp for the whole campaign (pre-request script: 7 days from now)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"accepted\": 2,\n \"rejected\": 0,\n \"failed\": 0,\n \"destinations\": [\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"972501234567\"\n },\n {\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"to\": \"IL.1605856887361213\"\n }\n ],\n \"reason\": 1\n}" } ], "event": [ { "listen": "prerequest", "script": { "type": "text/javascript", "exec": [ "// couponExpiration is UNIX seconds (UTC). Here: 7 days from now.", "pm.collectionVariables.set('coupon_expiration', String(Math.floor(Date.now() / 1000) + 7 * 24 * 3600));" ] } } ] }, { "name": "Carousel - shared cards, personal body variable", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard3_bodyVariable\": \"Travel mug\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard3_bodyVariable\": \"Travel mug\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Card media, card URL variables and card quick-reply ids are top-level (same cards for everyone). The shared body's `bodyVariable1` and each card's `carouselCardX_bodyVariable` are per destination. `headerType` is always 1 for a carousel." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_carousel}}\",\n \"headerType\": 1,\n \"carouselCard1_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard1_websiteVariable\": \"wallet-01\",\n \"carouselCard1_quickReply1_id\": \"WANT_WALLET\",\n \"carouselCard2_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard2_websiteVariable\": \"backpack-02\",\n \"carouselCard2_quickReply1_id\": \"WANT_BACKPACK\",\n \"carouselCard3_headerLink\": \"{{sample_image_url}}\",\n \"carouselCard3_websiteVariable\": \"mug-03\",\n \"carouselCard3_quickReply1_id\": \"WANT_MUG\",\n \"destinations\": [\n {\n \"to\": \"{{to}}\",\n \"bodyVariable1\": \"Dana\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard3_bodyVariable\": \"Travel mug\"\n },\n {\n \"to\": \"{{to_user_id}}\",\n \"bodyVariable1\": \"Yossi\",\n \"carouselCard1_bodyVariable\": \"Leather wallet\",\n \"carouselCard2_bodyVariable\": \"Canvas backpack\",\n \"carouselCard3_bodyVariable\": \"Travel mug\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/sendMultiTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "sendMultiTemplate" ] }, "description": "Card media, card URL variables and card quick-reply ids are top-level (same cards for everyone). The shared body's `bodyVariable1` and each card's `carouselCardX_bodyVariable` are per destination. `headerType` is always 1 for a carousel." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"timestamp\": 1789900000,\n \"from\": \"{{from}}\",\n \"accepted\": 2,\n \"rejected\": 0,\n \"failed\": 0,\n \"destinations\": [\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"972501234567\"\n },\n {\n \"unique\": \"5ec46920d615hh3-x3c15a2dff350a1-3SIZZq8h9JVdA53\",\n \"to\": \"IL.1605856887361213\"\n }\n ],\n \"reason\": 1\n}" } ] } ] }, { "name": "getTemplates", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTemplates", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTemplates" ] }, "description": "`POST /whatsapp/v2/getTemplates` - every template of your account with its approval status and full structure. Use it to check that a new template is `approved` before sending it, and to read the exact components (variables, buttons, header format) you must fill in.\n\n| Field in `list[]` | Meaning |\n|---|---|\n| `name` | The name you pass to `sendTemplate` |\n| `language` | Meta language code (`he`, `en_US`, `ar`, ...) |\n| `category` | 1 utility, 2 marketing, 3 authentication |\n| `status` | `approved` (sendable), `pending` (in review), `rejected`, `paused` (too many reports, ~10h), `disabled` |\n| `template` | The components: `HEADER` (`format`), `BODY` (`text` with `{{n}}`), `FOOTER`, `BUTTONS` (`URL` with `{{1}}` = dynamic, `QUICK_REPLY`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`), `CAROUSEL` (`cards`) |\n\nNo filters or paging - the whole list comes back in one call (it is cached on our side; the first call after onboarding can take ~5 seconds).\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTemplates", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTemplates" ] }, "description": "`POST /whatsapp/v2/getTemplates` - every template of your account with its approval status and full structure. Use it to check that a new template is `approved` before sending it, and to read the exact components (variables, buttons, header format) you must fill in.\n\n| Field in `list[]` | Meaning |\n|---|---|\n| `name` | The name you pass to `sendTemplate` |\n| `language` | Meta language code (`he`, `en_US`, `ar`, ...) |\n| `category` | 1 utility, 2 marketing, 3 authentication |\n| `status` | `approved` (sendable), `pending` (in review), `rejected`, `paused` (too many reports, ~10h), `disabled` |\n| `template` | The components: `HEADER` (`format`), `BODY` (`text` with `{{n}}`), `FOOTER`, `BUTTONS` (`URL` with `{{1}}` = dynamic, `QUICK_REPLY`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`), `CAROUSEL` (`cards`) |\n\nNo filters or paging - the whole list comes back in one call (it is cached on our side; the first call after onboarding can take ~5 seconds).\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"list\": [\n {\n \"name\": \"postman_welcome_text\",\n \"language\": \"en_US\",\n \"category\": 1,\n \"status\": \"approved\",\n \"template\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Hi {{1}}, your order {{2}} was received. We will let you know when it ships.\"\n },\n {\n \"type\": \"FOOTER\",\n \"text\": \"Thank you for shopping with us\"\n }\n ]\n },\n {\n \"name\": \"postman_invoice_pdf\",\n \"language\": \"en_US\",\n \"category\": 1,\n \"status\": \"pending\",\n \"template\": [\n {\n \"type\": \"BODY\",\n \"text\": \"Dear {{1}}, your invoice for {{2}} is attached. The total amount is {{3}}. Thank you for your business.\"\n },\n {\n \"type\": \"HEADER\",\n \"format\": \"DOCUMENT\"\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"URL\",\n \"text\": \"Pay online\",\n \"url\": \"https://www.example.com/pay/{{1}}\"\n }\n ]\n }\n ]\n },\n {\n \"name\": \"postman_login_code\",\n \"language\": \"en_US\",\n \"category\": 3,\n \"status\": \"approved\",\n \"template\": [\n {\n \"type\": \"BODY\",\n \"add_security_recommendation\": true\n },\n {\n \"type\": \"FOOTER\",\n \"code_expiration_minutes\": 5\n },\n {\n \"type\": \"BUTTONS\",\n \"buttons\": [\n {\n \"type\": \"OTP\",\n \"otp_type\": \"COPY_CODE\"\n }\n ]\n }\n ]\n }\n ]\n}" }, { "name": "Failure - wrong apiKey header (reason 3)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTemplates", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTemplates" ] }, "description": "`POST /whatsapp/v2/getTemplates` - every template of your account with its approval status and full structure. Use it to check that a new template is `approved` before sending it, and to read the exact components (variables, buttons, header format) you must fill in.\n\n| Field in `list[]` | Meaning |\n|---|---|\n| `name` | The name you pass to `sendTemplate` |\n| `language` | Meta language code (`he`, `en_US`, `ar`, ...) |\n| `category` | 1 utility, 2 marketing, 3 authentication |\n| `status` | `approved` (sendable), `pending` (in review), `rejected`, `paused` (too many reports, ~10h), `disabled` |\n| `template` | The components: `HEADER` (`format`), `BODY` (`text` with `{{n}}`), `FOOTER`, `BUTTONS` (`URL` with `{{1}}` = dynamic, `QUICK_REPLY`, `PHONE_NUMBER`, `COPY_CODE`, `OTP`), `CAROUSEL` (`cards`) |\n\nNo filters or paging - the whole list comes back in one call (it is cached on our side; the first call after onboarding can take ~5 seconds).\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 3\n}" } ] }, { "name": "deleteTemplate", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/deleteTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "deleteTemplate" ] }, "description": "`POST /whatsapp/v2/deleteTemplate` - delete a template by `name` (all language versions of that name). Deleting is the only way to \"edit\": create the corrected template under a **new** name first, switch your sending code, then delete the old one.\n\nThe name stays blocked for 30 days after a delete, so it cannot be reused right away. Names starting with `reserved_` are protected and return 7.\n\n| reason | Meaning |\n|---|---|\n| 1 | Deleted |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `name` missing, not one of your templates, or WhatsApp refused the delete |\n| 7 | Protected template (`reserved_` prefix) |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/deleteTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "deleteTemplate" ] }, "description": "`POST /whatsapp/v2/deleteTemplate` - delete a template by `name` (all language versions of that name). Deleting is the only way to \"edit\": create the corrected template under a **new** name first, switch your sending code, then delete the old one.\n\nThe name stays blocked for 30 days after a delete, so it cannot be reused right away. Names starting with `reserved_` are protected and return 7.\n\n| reason | Meaning |\n|---|---|\n| 1 | Deleted |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `name` missing, not one of your templates, or WhatsApp refused the delete |\n| 7 | Protected template (`reserved_` prefix) |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"name\": \"postman_simple_notice\",\n \"reason\": 1\n}" }, { "name": "Failure - template not found (reason 4)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/deleteTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "deleteTemplate" ] }, "description": "`POST /whatsapp/v2/deleteTemplate` - delete a template by `name` (all language versions of that name). Deleting is the only way to \"edit\": create the corrected template under a **new** name first, switch your sending code, then delete the old one.\n\nThe name stays blocked for 30 days after a delete, so it cannot be reused right away. Names starting with `reserved_` are protected and return 7.\n\n| reason | Meaning |\n|---|---|\n| 1 | Deleted |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `name` missing, not one of your templates, or WhatsApp refused the delete |\n| 7 | Protected template (`reserved_` prefix) |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 4\n}" }, { "name": "Failure - protected template (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"name\": \"{{tpl_text}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/deleteTemplate", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "deleteTemplate" ] }, "description": "`POST /whatsapp/v2/deleteTemplate` - delete a template by `name` (all language versions of that name). Deleting is the only way to \"edit\": create the corrected template under a **new** name first, switch your sending code, then delete the old one.\n\nThe name stays blocked for 30 days after a delete, so it cannot be reused right away. Names starting with `reserved_` are protected and return 7.\n\n| reason | Meaning |\n|---|---|\n| 1 | Deleted |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `name` missing, not one of your templates, or WhatsApp refused the delete |\n| 7 | Protected template (`reserved_` prefix) |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" } ] } ] }, { "name": "3 - Account & profile", "description": "Read and manage your number: business profile, the 24-hour timers, chat history, contacts and the block list. All calls here are **synchronous** - the response is the result.", "item": [ { "name": "Profile", "description": "Read and update the business profile customers see when they open your number's info page. The **display name** itself cannot be changed here - contact support. Numbers connected in *coexistence* mode manage their profile in the WhatsApp Business app; API changes are not possible for them.", "item": [ { "name": "getProfile", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getProfile" ] }, "description": "`POST /whatsapp/v2/getProfile` - every profile field plus two live counters.\n\n| Field | Meaning |\n|---|---|\n| `displayName` | The verified name shown to customers |\n| `address`, `description`, `email`, `website`, `about` | Profile texts |\n| `type` | Business category, see table below |\n| `conversations` | Conversations opened this month (resets on the 1st, 04:00 Israel time) |\n| `dailyLimit` | Business-initiated conversations allowed per rolling 24h (250 / 1000 / 2000 / 10000 / 100000 / 1000000 = unlimited) |\n| `profilePic` | A fresh copy of the current profile picture |\n| `isVerifiedBusiness` | `true` when Meta verified the business |\n\n| `type` | Business category |\n|---|---|\n| 1 | Automotive |\n| 2 | Beauty, spa and salon |\n| 3 | Clothing and apparel |\n| 4 | Education |\n| 5 | Entertainment |\n| 6 | Event planning and service |\n| 7 | Finance and banking |\n| 8 | Food and grocery |\n| 9 | Public service / government |\n| 10 | Hotel and lodging |\n| 11 | Medical and health |\n| 12 | Non-profit |\n| 13 | Professional services |\n| 14 | Shopping and retail |\n| 15 | Travel and transportation |\n| 16 | Restaurant |\n| 17 | Other |\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or the profile could not be read |\n| 3 | Wrong `apiKey` header |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getProfile" ] }, "description": "`POST /whatsapp/v2/getProfile` - every profile field plus two live counters.\n\n| Field | Meaning |\n|---|---|\n| `displayName` | The verified name shown to customers |\n| `address`, `description`, `email`, `website`, `about` | Profile texts |\n| `type` | Business category, see table below |\n| `conversations` | Conversations opened this month (resets on the 1st, 04:00 Israel time) |\n| `dailyLimit` | Business-initiated conversations allowed per rolling 24h (250 / 1000 / 2000 / 10000 / 100000 / 1000000 = unlimited) |\n| `profilePic` | A fresh copy of the current profile picture |\n| `isVerifiedBusiness` | `true` when Meta verified the business |\n\n| `type` | Business category |\n|---|---|\n| 1 | Automotive |\n| 2 | Beauty, spa and salon |\n| 3 | Clothing and apparel |\n| 4 | Education |\n| 5 | Entertainment |\n| 6 | Event planning and service |\n| 7 | Finance and banking |\n| 8 | Food and grocery |\n| 9 | Public service / government |\n| 10 | Hotel and lodging |\n| 11 | Medical and health |\n| 12 | Non-profit |\n| 13 | Professional services |\n| 14 | Shopping and retail |\n| 15 | Travel and transportation |\n| 16 | Restaurant |\n| 17 | Other |\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or the profile could not be read |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"displayName\": \"My Business Ltd\",\n \"address\": \"Herzl 1, Tel Aviv\",\n \"description\": \"Online store for gadgets\",\n \"email\": \"info@example.com\",\n \"type\": 14,\n \"website\": \"https://www.example.com\",\n \"about\": \"Available Sun-Thu 09:00-17:00\",\n \"conversations\": 123,\n \"dailyLimit\": 1000,\n \"profilePic\": \"https://storage.99digital.online/files/1789900000aB3dE9fGh1.jpg\",\n \"isVerifiedBusiness\": true,\n \"reason\": 1\n}" }, { "name": "Failure - wrong apiKey header (reason 3)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getProfile" ] }, "description": "`POST /whatsapp/v2/getProfile` - every profile field plus two live counters.\n\n| Field | Meaning |\n|---|---|\n| `displayName` | The verified name shown to customers |\n| `address`, `description`, `email`, `website`, `about` | Profile texts |\n| `type` | Business category, see table below |\n| `conversations` | Conversations opened this month (resets on the 1st, 04:00 Israel time) |\n| `dailyLimit` | Business-initiated conversations allowed per rolling 24h (250 / 1000 / 2000 / 10000 / 100000 / 1000000 = unlimited) |\n| `profilePic` | A fresh copy of the current profile picture |\n| `isVerifiedBusiness` | `true` when Meta verified the business |\n\n| `type` | Business category |\n|---|---|\n| 1 | Automotive |\n| 2 | Beauty, spa and salon |\n| 3 | Clothing and apparel |\n| 4 | Education |\n| 5 | Entertainment |\n| 6 | Event planning and service |\n| 7 | Finance and banking |\n| 8 | Food and grocery |\n| 9 | Public service / government |\n| 10 | Hotel and lodging |\n| 11 | Medical and health |\n| 12 | Non-profit |\n| 13 | Professional services |\n| 14 | Shopping and retail |\n| 15 | Travel and transportation |\n| 16 | Restaurant |\n| 17 | Other |\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist or the profile could not be read |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 3\n}" } ] }, { "name": "setProfile - update texts", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"address\": \"Herzl 1, Tel Aviv\",\n \"description\": \"Online store for gadgets. Free delivery over 200 NIS.\",\n \"email\": \"info@example.com\",\n \"website\": \"https://www.example.com\",\n \"about\": \"Available Sun-Thu 09:00-17:00\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "`POST /whatsapp/v2/setProfile` - every field is optional; send only what you want to change.\n\n| Field | Rules |\n|---|---|\n| `address` | Up to 256 chars -> 4 |\n| `description` | Up to 256 chars -> 5 |\n| `email` | Valid address, up to 128 chars -> 6 |\n| `type` | 1-17, see the table in getProfile -> 7 |\n| `website` | Full URL with `https://`, up to 256 chars (one website) -> 8 |\n| `profilePic` | Public https URL of a square jpg/png, up to 640x640, 5MB -> 10 |\n| `about` | Up to 139 chars -> 11 |\n\nTo **clear** `address`, `description`, `email` or `website` send a single space `\" \"`. `type`, `about` and `profilePic` cannot be cleared.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `address` too long |\n| 5 | `description` too long |\n| 6 | `email` invalid or too long |\n| 7 | `type` not 1-17 |\n| 8 | `website` invalid or too long |\n| 10 | `profilePic` not a valid URL, or the picture could not be downloaded / uploaded |\n| 11 | `about` too long |\n| 12 | WhatsApp rejected the update - contact support |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"address\": \"Herzl 1, Tel Aviv\",\n \"description\": \"Online store for gadgets. Free delivery over 200 NIS.\",\n \"email\": \"info@example.com\",\n \"website\": \"https://www.example.com\",\n \"about\": \"Available Sun-Thu 09:00-17:00\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "`POST /whatsapp/v2/setProfile` - every field is optional; send only what you want to change.\n\n| Field | Rules |\n|---|---|\n| `address` | Up to 256 chars -> 4 |\n| `description` | Up to 256 chars -> 5 |\n| `email` | Valid address, up to 128 chars -> 6 |\n| `type` | 1-17, see the table in getProfile -> 7 |\n| `website` | Full URL with `https://`, up to 256 chars (one website) -> 8 |\n| `profilePic` | Public https URL of a square jpg/png, up to 640x640, 5MB -> 10 |\n| `about` | Up to 139 chars -> 11 |\n\nTo **clear** `address`, `description`, `email` or `website` send a single space `\" \"`. `type`, `about` and `profilePic` cannot be cleared.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `address` too long |\n| 5 | `description` too long |\n| 6 | `email` invalid or too long |\n| 7 | `type` not 1-17 |\n| 8 | `website` invalid or too long |\n| 10 | `profilePic` not a valid URL, or the picture could not be downloaded / uploaded |\n| 11 | `about` too long |\n| 12 | WhatsApp rejected the update - contact support |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"reason\": 1,\n \"returnedData\": {\n \"address\": \"Herzl 1, Tel Aviv\",\n \"description\": \"Online store for gadgets. Free delivery over 200 NIS.\",\n \"email\": \"info@example.com\",\n \"website\": \"https://www.example.com\",\n \"about\": \"Available Sun-Thu 09:00-17:00\"\n }\n}" }, { "name": "Failure - email invalid (reason 6)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"address\": \"Herzl 1, Tel Aviv\",\n \"description\": \"Online store for gadgets. Free delivery over 200 NIS.\",\n \"email\": \"info@example.com\",\n \"website\": \"https://www.example.com\",\n \"about\": \"Available Sun-Thu 09:00-17:00\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "`POST /whatsapp/v2/setProfile` - every field is optional; send only what you want to change.\n\n| Field | Rules |\n|---|---|\n| `address` | Up to 256 chars -> 4 |\n| `description` | Up to 256 chars -> 5 |\n| `email` | Valid address, up to 128 chars -> 6 |\n| `type` | 1-17, see the table in getProfile -> 7 |\n| `website` | Full URL with `https://`, up to 256 chars (one website) -> 8 |\n| `profilePic` | Public https URL of a square jpg/png, up to 640x640, 5MB -> 10 |\n| `about` | Up to 139 chars -> 11 |\n\nTo **clear** `address`, `description`, `email` or `website` send a single space `\" \"`. `type`, `about` and `profilePic` cannot be cleared.\n\nText formatting: `*bold*`, `_italic_`, `~strikethrough~`, ```` ```monospace``` ```` and a real line break (`\\n` inside the JSON string).\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `address` too long |\n| 5 | `description` too long |\n| 6 | `email` invalid or too long |\n| 7 | `type` not 1-17 |\n| 8 | `website` invalid or too long |\n| 10 | `profilePic` not a valid URL, or the picture could not be downloaded / uploaded |\n| 11 | `about` too long |\n| 12 | WhatsApp rejected the update - contact support |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 6\n}" } ] }, { "name": "setProfile - business type", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"type\": 14\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "Only the category. Integer 1-17 (see getProfile)." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"type\": 14\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "Only the category. Integer 1-17 (see getProfile)." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"reason\": 1,\n \"returnedData\": {\n \"type\": 14\n }\n}" } ] }, { "name": "setProfile - profile picture", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"profilePic\": \"{{sample_image_url}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "We download the picture from your URL and upload it to WhatsApp. Square jpg/png, at least 192x192, at most 640x640 and 5MB. Takes a second or two." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"profilePic\": \"{{sample_image_url}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "We download the picture from your URL and upload it to WhatsApp. Square jpg/png, at least 192x192, at most 640x640 and 5MB. Takes a second or two." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"reason\": 1,\n \"returnedData\": {\n \"profilePic\": \"https://storage.99digital.online/samples/hello.png\"\n }\n}" }, { "name": "Failure - picture could not be fetched (reason 10)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"profilePic\": \"{{sample_image_url}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "We download the picture from your URL and upload it to WhatsApp. Square jpg/png, at least 192x192, at most 640x640 and 5MB. Takes a second or two." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 10\n}" } ] }, { "name": "setProfile - clear fields", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"address\": \" \",\n \"website\": \" \"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "A single space clears a text field (`address`, `description`, `email`, `website`). An empty string `\"\"` is ignored, so use the space." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"address\": \" \",\n \"website\": \" \"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setProfile", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setProfile" ] }, "description": "A single space clears a text field (`address`, `description`, `email`, `website`). An empty string `\"\"` is ignored, so use the space." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"reason\": 1,\n \"returnedData\": {\n \"address\": \"\",\n \"website\": \"\"\n }\n}" } ] } ] }, { "name": "getTimers - minutes left in the 24h window", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"number\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTimers", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTimers" ] }, "description": "`POST /whatsapp/v2/getTimers` - how many minutes are left in the 24-hour window with one customer, without sending anything. `0` = closed, a template is required.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `number` | yes | The customer's number exactly as it appears in your webhook (international, no `+`) or their user id -> missing 4 |\n\n`conversationTimeLeft` is deprecated and always 0.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 4 | `number` missing |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"number\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTimers", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTimers" ] }, "description": "`POST /whatsapp/v2/getTimers` - how many minutes are left in the 24-hour window with one customer, without sending anything. `0` = closed, a template is required.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `number` | yes | The customer's number exactly as it appears in your webhook (international, no `+`) or their user id -> missing 4 |\n\n`conversationTimeLeft` is deprecated and always 0.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 4 | `number` missing |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"templateTimeLeft\": 1372,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" }, { "name": "Window closed (still OK, templateTimeLeft 0)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"number\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getTimers", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getTimers" ] }, "description": "`POST /whatsapp/v2/getTimers` - how many minutes are left in the 24-hour window with one customer, without sending anything. `0` = closed, a template is required.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `number` | yes | The customer's number exactly as it appears in your webhook (international, no `+`) or their user id -> missing 4 |\n\n`conversationTimeLeft` is deprecated and always 0.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 4 | `number` missing |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"templateTimeLeft\": 0,\n \"conversationTimeLeft\": 0,\n \"reason\": 1\n}" } ] }, { "name": "getHistory - whole account, page 1", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getHistory", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getHistory" ] }, "description": "`POST /whatsapp/v2/getHistory` - your chat history, newest first, **50 messages per page**. We keep messages for 1 year; media links inside them expire after 7 days, so download files you need.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `page` | yes | 1 = messages 1-50, 2 = 51-100, ... -> 11 |\n| `to` | no | One customer (phone or user id) - omit for the whole account |\n\n**The response is a bare JSON array** (an object only on failure):\n\n| Field | Meaning |\n|---|---|\n| `unique` | Message id - the same `unique` as in the send response / webhooks |\n| `timestamp` | UNIX seconds |\n| `direction` | 1 incoming (customer -> you), 2 outgoing |\n| `from`, `to` | Phone numbers; `from_id` / `to_id` carry the user id when the phone is hidden |\n| `type` | `text`, `image`, `video`, `audio`, `ptt`, `document`, `location`, ... |\n| `state` | Outgoing only: 0 failed, 1 sent, 2 delivered, 3 read |\n| `message` | Text, caption or media URL |\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 11 | `page` missing or not a number |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getHistory", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getHistory" ] }, "description": "`POST /whatsapp/v2/getHistory` - your chat history, newest first, **50 messages per page**. We keep messages for 1 year; media links inside them expire after 7 days, so download files you need.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `page` | yes | 1 = messages 1-50, 2 = 51-100, ... -> 11 |\n| `to` | no | One customer (phone or user id) - omit for the whole account |\n\n**The response is a bare JSON array** (an object only on failure):\n\n| Field | Meaning |\n|---|---|\n| `unique` | Message id - the same `unique` as in the send response / webhooks |\n| `timestamp` | UNIX seconds |\n| `direction` | 1 incoming (customer -> you), 2 outgoing |\n| `from`, `to` | Phone numbers; `from_id` / `to_id` carry the user id when the phone is hidden |\n| `type` | `text`, `image`, `video`, `audio`, `ptt`, `document`, `location`, ... |\n| `state` | Outgoing only: 0 failed, 1 sent, 2 delivered, 3 read |\n| `message` | Text, caption or media URL |\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 11 | `page` missing or not a number |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"direction\": 2,\n \"from\": \"{{from}}\",\n \"from_id\": null,\n \"to\": \"972501234567\",\n \"to_id\": null,\n \"type\": \"text\",\n \"state\": 3,\n \"message\": \"Hi Dana, your order 4711 was received. We will let you know when it ships.\"\n },\n {\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"timestamp\": 1789899000,\n \"direction\": 1,\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"to\": \"{{from}}\",\n \"to_id\": null,\n \"type\": \"image\",\n \"state\": 0,\n \"message\": \"https://storage.99digital.online/files/1789899000Ab3dE9fGh1.jpg\"\n }\n]" }, { "name": "Failure - page missing (reason 11)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getHistory", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getHistory" ] }, "description": "`POST /whatsapp/v2/getHistory` - your chat history, newest first, **50 messages per page**. We keep messages for 1 year; media links inside them expire after 7 days, so download files you need.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `page` | yes | 1 = messages 1-50, 2 = 51-100, ... -> 11 |\n| `to` | no | One customer (phone or user id) - omit for the whole account |\n\n**The response is a bare JSON array** (an object only on failure):\n\n| Field | Meaning |\n|---|---|\n| `unique` | Message id - the same `unique` as in the send response / webhooks |\n| `timestamp` | UNIX seconds |\n| `direction` | 1 incoming (customer -> you), 2 outgoing |\n| `from`, `to` | Phone numbers; `from_id` / `to_id` carry the user id when the phone is hidden |\n| `type` | `text`, `image`, `video`, `audio`, `ptt`, `document`, `location`, ... |\n| `state` | Outgoing only: 0 failed, 1 sent, 2 delivered, 3 read |\n| `message` | Text, caption or media URL |\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 11 | `page` missing or not a number |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 11\n}" } ] }, { "name": "getHistory - one customer", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getHistory", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getHistory" ] }, "description": "Add `to` to get the conversation with a single customer (phone number or user id, exactly as stored). Same paging." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"to\": \"{{to}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getHistory", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getHistory" ] }, "description": "Add `to` to get the conversation with a single customer (phone number or user id, exactly as stored). Same paging." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"timestamp\": 1789900000,\n \"direction\": 2,\n \"from\": \"{{from}}\",\n \"from_id\": null,\n \"to\": \"972501234567\",\n \"to_id\": null,\n \"type\": \"text\",\n \"state\": 2,\n \"message\": \"Yes, that item is in stock.\"\n }\n]" } ] }, { "name": "getContacts - page 1", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getContacts", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getContacts" ] }, "description": "`POST /whatsapp/v2/getContacts` - everyone who wrote to your number, most recent first, **50 per page** (`page` defaults to 1).\n\n**The response is a bare JSON array:**\n\n| Field | Meaning |\n|---|---|\n| `contact_phone` | The customer's number (or user id when the phone is hidden) |\n| `contact_phone_id` | The customer's user id when known, else `null` |\n| `contact_name` | Their WhatsApp profile name |\n| `update_time` | UNIX seconds of the last update |\n| `online_contact_id`, `online_conversation_id` | Ids in the 99digital omni-channel inbox, 0 if not used |\n| `contact_profilePic` | Profile picture URL or `null` |\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 11 | `page` is not a number |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"page\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getContacts", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getContacts" ] }, "description": "`POST /whatsapp/v2/getContacts` - everyone who wrote to your number, most recent first, **50 per page** (`page` defaults to 1).\n\n**The response is a bare JSON array:**\n\n| Field | Meaning |\n|---|---|\n| `contact_phone` | The customer's number (or user id when the phone is hidden) |\n| `contact_phone_id` | The customer's user id when known, else `null` |\n| `contact_name` | Their WhatsApp profile name |\n| `update_time` | UNIX seconds of the last update |\n| `online_contact_id`, `online_conversation_id` | Ids in the 99digital omni-channel inbox, 0 if not used |\n| `contact_profilePic` | Profile picture URL or `null` |\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |\n| 11 | `page` is not a number |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "[\n {\n \"contact_phone\": \"972501234567\",\n \"contact_phone_id\": null,\n \"contact_name\": \"Dana Cohen\",\n \"update_time\": 1789900000,\n \"online_contact_id\": 0,\n \"online_conversation_id\": 0,\n \"contact_profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\"\n },\n {\n \"contact_phone\": \"IL.1605856887361213\",\n \"contact_phone_id\": \"IL.1605856887361213\",\n \"contact_name\": \"Yossi\",\n \"update_time\": 1789890000,\n \"online_contact_id\": 0,\n \"online_conversation_id\": 0,\n \"contact_profilePic\": null\n }\n]" } ] }, { "name": "Block list", "description": "Block a customer so they can no longer message your number (and you cannot message them). Useful for unsubscribe flows and for stopping spam from triggering your bot. Up to **64,000** numbers; a customer can be blocked only if they wrote to you in the last 24 hours.", "item": [ { "name": "block", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"whatsapp\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/block", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "block" ] }, "description": "`POST /whatsapp/v2/block`\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `whatsapp` | yes | The number to block, international without `+` -> 4 |\n\n| reason | Meaning |\n|---|---|\n| 1 | Blocked |\n| 2 | `from` does not exist or WhatsApp refused |\n| 3 | Wrong `apiKey` header |\n| 4 | `whatsapp` missing or not a valid international number |\n| 6 | WhatsApp refused (e.g. your own number, or too many requests) |\n| 7 | This customer did not message you in the last 24 hours |\n| 8 | Block list limit reached |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"whatsapp\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/block", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "block" ] }, "description": "`POST /whatsapp/v2/block`\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `whatsapp` | yes | The number to block, international without `+` -> 4 |\n\n| reason | Meaning |\n|---|---|\n| 1 | Blocked |\n| 2 | `from` does not exist or WhatsApp refused |\n| 3 | Wrong `apiKey` header |\n| 4 | `whatsapp` missing or not a valid international number |\n| 6 | WhatsApp refused (e.g. your own number, or too many requests) |\n| 7 | This customer did not message you in the last 24 hours |\n| 8 | Block list limit reached |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"whatsapp\": \"972501234567\",\n \"reason\": 1\n}" }, { "name": "Failure - no message from them in 24h (reason 7)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"whatsapp\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/block", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "block" ] }, "description": "`POST /whatsapp/v2/block`\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `whatsapp` | yes | The number to block, international without `+` -> 4 |\n\n| reason | Meaning |\n|---|---|\n| 1 | Blocked |\n| 2 | `from` does not exist or WhatsApp refused |\n| 3 | Wrong `apiKey` header |\n| 4 | `whatsapp` missing or not a valid international number |\n| 6 | WhatsApp refused (e.g. your own number, or too many requests) |\n| 7 | This customer did not message you in the last 24 hours |\n| 8 | Block list limit reached |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 7\n}" } ] }, { "name": "unblock", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"whatsapp\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/unblock", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "unblock" ] }, "description": "`POST /whatsapp/v2/unblock` - same field as `block`.\n\n| reason | Meaning |\n|---|---|\n| 1 | Unblocked |\n| 2 | `from` does not exist or WhatsApp refused |\n| 3 | Wrong `apiKey` header |\n| 4 | `whatsapp` missing or not a valid international number |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"whatsapp\": \"{{to}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/unblock", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "unblock" ] }, "description": "`POST /whatsapp/v2/unblock` - same field as `block`.\n\n| reason | Meaning |\n|---|---|\n| 1 | Unblocked |\n| 2 | `from` does not exist or WhatsApp refused |\n| 3 | Wrong `apiKey` header |\n| 4 | `whatsapp` missing or not a valid international number |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"whatsapp\": \"972501234567\",\n \"reason\": 1\n}" } ] }, { "name": "blockedList", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/blockedList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "blockedList" ] }, "description": "`POST /whatsapp/v2/blockedList` - all blocked numbers. Note: the success response has **no `reason` key**.\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist or the list could not be read |\n| 3 | Wrong `apiKey` header |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/blockedList", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "blockedList" ] }, "description": "`POST /whatsapp/v2/blockedList` - all blocked numbers. Note: the success response has **no `reason` key**.\n\n| reason | Meaning |\n|---|---|\n| 2 | `from` does not exist or the list could not be read |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"from\": \"{{from}}\",\n \"numbers\": [\n \"972501234567\",\n \"972521234567\"\n ]\n}" } ] } ] } ] }, { "name": "4 - Webhook settings", "description": "Tell us where to POST incoming messages, delivery statuses and system events. Folder *5* shows every payload you will receive. Changes take effect immediately.\n\nWebhook calls come from IP **34.165.99.212**; if you allow-list our API host for outgoing calls, it is **130.211.28.127**.", "item": [ { "name": "setWebhook - URL + all notifications", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"url\": \"{{your_webhook_url}}\",\n \"readStatus\": 1,\n \"system\": 1,\n \"retry\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "`POST /whatsapp/v2/setWebhook` - the recommended production setup: incoming messages, delivery statuses, system events and retries all on.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `url` | no | Your https endpoint. A single space `\" \"` disables the webhook. Omitted = unchanged -> not http(s): 9 |\n| `readStatus` | no | 1 = also send delivery statuses of your messages (`hook: update`, ack 1/2/3/0). Default 0 -> 6 |\n| `system` | no | 1 = also send system messages (`hook: system`: template approved / rejected, daily-limit changes, account issues, failed messages with a reason). Default 0 -> 4 |\n| `systemPhoneAlert` | no | Up to 5 phone numbers, comma separated, digits only (`972501234567,972521234567`) that receive the system alerts as WhatsApp messages from us, in Hebrew. A space clears -> 5 |\n| `retry` | no | 1 = retry failed deliveries: a second attempt right away, then after 5 min, 20 min, 1 h, 4 h and 24 h. Default 0 = one attempt -> 7 |\n\nIncoming messages (`hook: new`), contact updates and coexistence echoes are sent whenever a `url` is set. Your endpoint must answer **2xx within 5 seconds**; anything else counts as a failure.\n\n| reason | Meaning |\n|---|---|\n| 1 | Saved |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `system` is not 0 or 1 |\n| 5 | `systemPhoneAlert` contains something other than digits and commas |\n| 6 | `readStatus` is not 0 or 1 |\n| 7 | `retry` is not 0 or 1 |\n| 9 | `url` does not start with http:// or https:// |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"url\": \"{{your_webhook_url}}\",\n \"readStatus\": 1,\n \"system\": 1,\n \"retry\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "`POST /whatsapp/v2/setWebhook` - the recommended production setup: incoming messages, delivery statuses, system events and retries all on.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `url` | no | Your https endpoint. A single space `\" \"` disables the webhook. Omitted = unchanged -> not http(s): 9 |\n| `readStatus` | no | 1 = also send delivery statuses of your messages (`hook: update`, ack 1/2/3/0). Default 0 -> 6 |\n| `system` | no | 1 = also send system messages (`hook: system`: template approved / rejected, daily-limit changes, account issues, failed messages with a reason). Default 0 -> 4 |\n| `systemPhoneAlert` | no | Up to 5 phone numbers, comma separated, digits only (`972501234567,972521234567`) that receive the system alerts as WhatsApp messages from us, in Hebrew. A space clears -> 5 |\n| `retry` | no | 1 = retry failed deliveries: a second attempt right away, then after 5 min, 20 min, 1 h, 4 h and 24 h. Default 0 = one attempt -> 7 |\n\nIncoming messages (`hook: new`), contact updates and coexistence echoes are sent whenever a `url` is set. Your endpoint must answer **2xx within 5 seconds**; anything else counts as a failure.\n\n| reason | Meaning |\n|---|---|\n| 1 | Saved |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `system` is not 0 or 1 |\n| 5 | `systemPhoneAlert` contains something other than digits and commas |\n| 6 | `readStatus` is not 0 or 1 |\n| 7 | `retry` is not 0 or 1 |\n| 9 | `url` does not start with http:// or https:// |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"url\": \"https://your-server.example.com/99digital/whatsapp-webhook\",\n \"system\": 1,\n \"systemPhoneAlert\": null,\n \"readStatus\": 1,\n \"retry\": 1,\n \"reason\": 1\n}" }, { "name": "Failure - url not http(s) (reason 9)", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"url\": \"{{your_webhook_url}}\",\n \"readStatus\": 1,\n \"system\": 1,\n \"retry\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "`POST /whatsapp/v2/setWebhook` - the recommended production setup: incoming messages, delivery statuses, system events and retries all on.\n\n| Field | Mandatory | Rules |\n|---|---|---|\n| `url` | no | Your https endpoint. A single space `\" \"` disables the webhook. Omitted = unchanged -> not http(s): 9 |\n| `readStatus` | no | 1 = also send delivery statuses of your messages (`hook: update`, ack 1/2/3/0). Default 0 -> 6 |\n| `system` | no | 1 = also send system messages (`hook: system`: template approved / rejected, daily-limit changes, account issues, failed messages with a reason). Default 0 -> 4 |\n| `systemPhoneAlert` | no | Up to 5 phone numbers, comma separated, digits only (`972501234567,972521234567`) that receive the system alerts as WhatsApp messages from us, in Hebrew. A space clears -> 5 |\n| `retry` | no | 1 = retry failed deliveries: a second attempt right away, then after 5 min, 20 min, 1 h, 4 h and 24 h. Default 0 = one attempt -> 7 |\n\nIncoming messages (`hook: new`), contact updates and coexistence echoes are sent whenever a `url` is set. Your endpoint must answer **2xx within 5 seconds**; anything else counts as a failure.\n\n| reason | Meaning |\n|---|---|\n| 1 | Saved |\n| 2 | `from` does not exist / invalid JSON |\n| 3 | Wrong `apiKey` header |\n| 4 | `system` is not 0 or 1 |\n| 5 | `systemPhoneAlert` contains something other than digits and commas |\n| 6 | `readStatus` is not 0 or 1 |\n| 7 | `retry` is not 0 or 1 |\n| 9 | `url` does not start with http:// or https:// |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"FAIL\",\n \"reason\": 9\n}" } ] }, { "name": "setWebhook - system alerts to my phone", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"system\": 1,\n \"systemPhoneAlert\": \"972501234567,972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "Besides (or instead of) the webhook, we can WhatsApp you when something happens to the account or a template - up to 5 numbers, digits and commas only. Messages are in Hebrew. Fields you do not send stay as they are." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"system\": 1,\n \"systemPhoneAlert\": \"972501234567,972521234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "Besides (or instead of) the webhook, we can WhatsApp you when something happens to the account or a template - up to 5 numbers, digits and commas only. Messages are in Hebrew. Fields you do not send stay as they are." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"url\": null,\n \"system\": 1,\n \"systemPhoneAlert\": \"972501234567,972521234567\",\n \"readStatus\": null,\n \"retry\": null,\n \"reason\": 1\n}" } ] }, { "name": "setWebhook - disable the webhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"url\": \" \"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "A single space as `url` switches the webhook off; nothing is POSTed until you set a URL again. The same trick clears `systemPhoneAlert`." }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\",\n \"url\": \" \"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/setWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "setWebhook" ] }, "description": "A single space as `url` switches the webhook off; nothing is POSTed until you set a URL again. The same trick clears `systemPhoneAlert`." }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"url\": \" \",\n \"system\": null,\n \"systemPhoneAlert\": null,\n \"readStatus\": null,\n \"retry\": null,\n \"reason\": 1\n}" } ] }, { "name": "getWebhook", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getWebhook" ] }, "description": "`POST /whatsapp/v2/getWebhook` - the current settings. `url` is empty when no webhook is configured.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |" }, "response": [ { "name": "Success", "originalRequest": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"from\": \"{{from}}\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{base_url}}/whatsapp/v2/getWebhook", "host": [ "{{base_url}}" ], "path": [ "whatsapp", "v2", "getWebhook" ] }, "description": "`POST /whatsapp/v2/getWebhook` - the current settings. `url` is empty when no webhook is configured.\n\n| reason | Meaning |\n|---|---|\n| 1 | OK |\n| 2 | `from` does not exist |\n| 3 | Wrong `apiKey` header |" }, "status": "OK", "code": 200, "_postman_previewlanguage": "json", "header": [ { "key": "Content-Type", "value": "application/json" } ], "cookie": [], "body": "{\n \"status\": \"OK\",\n \"url\": \"https://your-server.example.com/99digital/whatsapp-webhook\",\n \"system\": 1,\n \"systemPhoneAlert\": \"972501234567,972521234567\",\n \"retry\": 1,\n \"readStatus\": 1,\n \"reason\": 1\n}" } ] } ] }, { "name": "5 - Webhooks (what we send you)", "description": "These are **not** API endpoints - they are samples of what our platform POSTs at **your** server, so you can point `{{your_webhook_url}}` at your own handler and test it end to end. Configure the URL with `setWebhook` (folder 4).\n\n**Rules of the road**\n\n- Every call is a `POST` with a JSON body and `Content-Type: application/json`, from IP **34.165.99.212**. There is no signature header - restrict by IP and keep the URL secret.\n- Answer **HTTP 2xx within 5 seconds**; do your processing afterwards. Anything else counts as a failed delivery.\n- With `retry: 1` a failed delivery is retried right away and then after 5 min, 20 min, 1 h, 4 h and 24 h (same payload, same `timestamp`). Without it we try once. Make your handler **idempotent** on `hook` + `unique` (+ `ack`).\n- Order is not guaranteed between calls.\n- The top-level `hook` tells you what arrived: `new` (incoming message), `update` (delivery status), `system` (failures / templates / account), `contact` and `outgoing` (coexistence numbers).\n- Files we host for you (`media: true`) are deleted after **7 days** - download what you need.", "item": [ { "name": "hook: new - incoming messages", "description": "One POST per message a customer sends you. Common keys:\n\n| Key | Meaning |\n|---|---|\n| `unique` | Id of the incoming message - use it for `replyTo` and `sendReaction` |\n| `from` | The customer's phone number - or their user id when the phone is hidden |\n| `from_id` | The customer's user id (`IL.…`) when known, else `null` |\n| `phone` | The phone number, `null` when hidden |\n| `country` | Two-letter country of the user id, else `null` |\n| `to` | Your WhatsApp number |\n| `senderName` | Their WhatsApp profile name |\n| `type` | `text`, `image`, `video`, `audio`, `ptt` (voice note), `document`, `location`, `contacts`, `button`, `list`, `reaction`, `order`, `phone` |\n| `body` / `caption` | Depend on `type` - see each sample |\n| `template` | Template name when the customer tapped a template quick-reply button |\n| `media` | `true` when `body` is a file we host for you (**download it - files are deleted after 7 days**) |\n| `quote` / `quoteUnique` | `true` + the `unique` of the quoted message when they replied to one |\n| `isForwarded` | The message was forwarded |\n| `timestamp` | UNIX seconds (string) |\n| `profilePic` | Their profile picture, when their privacy allows |\n| `conversationTimeLeft` | Minutes left in the 24-hour window (a fresh message = 1435) |\n| `isNewConversation` | 1 when this message opened a new 24-hour window |\n| `referral` | `ref_type: none`, or `post` / `ad` with the Facebook / Instagram source |\n\nStickers and unsupported message kinds are not forwarded.", "item": [ { "name": "Text", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"text\",\n \"body\": \"Hi, is the store open today?\",\n \"caption\": \"\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A plain text message. `body` is the text, `caption` is empty.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Image with caption", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"image\",\n \"body\": \"https://storage.99digital.online/files/1789900000Ab3dE9fGh1.jpg\",\n \"caption\": \"My receipt\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": true,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "`body` is the URL of the file on our storage (jpg/png), `caption` the text under it. Video (`.mp4`), audio / voice note `ptt` (`.ogg`) and `document` (`.pdf`, `.docx`, ...) look the same. Download the file - we delete it after 7 days.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Document", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"document\",\n \"body\": \"https://storage.99digital.online/files/1789900000Zx9Yw8Vu7T.pdf\",\n \"caption\": \"signed-contract.pdf\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": true,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A file the customer sent. `caption` carries the caption or the original file name.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Location", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"location\",\n \"body\": \"32.0853,34.7818\",\n \"caption\": \"Azrieli Center - Menachem Begin 132, Tel Aviv\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "`body` = `latitude,longitude`; `caption` = place name and address when the customer picked a place (also the answer to `requestLocation`).", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Contact card", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"contacts\",\n \"body\": \"972521112233\",\n \"caption\": \"Yossi Levi\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A shared contact: `body` = the phone number, `caption` = the name.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Template quick-reply button tapped", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"button\",\n \"body\": \"Confirm\",\n \"caption\": \"CONFIRM\",\n \"template\": \"postman_reminder_full\",\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": true,\n \"quoteUnique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "The customer tapped a quick reply of a **template** you sent: `body` = the button label, `caption` = the `quickReplyN_id` you passed, `template` = the template name, `quoteUnique` = the `unique` of your template message.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Reply button tapped (sendButtons / sendCarousel)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"button\",\n \"body\": \"Track my order\",\n \"caption\": \"TRACK_ORDER\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": true,\n \"quoteUnique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A tap on a reply button of `sendButtons` or `sendCarousel`: `body` = the label, `caption` = the `buttonN_id` / `cardX_buttonNID` you gave it, `template` stays `null`.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "List option selected", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"list\",\n \"body\": \"Support\",\n \"caption\": \"SUPPORT\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": true,\n \"quoteUnique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A pick from a `sendList` menu: `body` = the option title, `caption` = its `itemIDN`.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Reaction to your message", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"reaction\",\n \"body\": \"👍\",\n \"caption\": \"\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": true,\n \"quoteUnique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "`body` = the emoji, `quoteUnique` = the `unique` of the message they reacted to. An empty `body` means the reaction was removed.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Order from a WhatsApp catalogue", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"order\",\n \"body\": \"Please deliver after 18:00\",\n \"caption\": \"1234567890123456\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n },\n \"order\": [\n {\n \"product_retailer_id\": \"SKU-001\",\n \"quantity\": 2,\n \"item_price\": 49.9,\n \"currency\": \"ILS\"\n },\n {\n \"product_retailer_id\": \"SKU-014\",\n \"quantity\": 1,\n \"item_price\": 199,\n \"currency\": \"ILS\"\n }\n ]\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A cart sent from your WhatsApp catalogue: `order` lists the items, `caption` is the catalogue id, `body` the customer's note.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Phone number revealed (answer to requestPhone)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"IL.1605856887361213\",\n \"from_id\": \"IL.1605856887361213\",\n \"username\": null,\n \"country\": \"IL\",\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"phone\",\n \"body\": \"972501234567\",\n \"caption\": \"Dana Cohen\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "The customer tapped the button of `requestPhone`: `body` = their phone number, `caption` / `senderName` = the name they shared. From now on you may address them by number or by user id.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Message from a hidden number (user id only)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"IL.1605856887361213\",\n \"from_id\": \"IL.1605856887361213\",\n \"username\": null,\n \"country\": \"IL\",\n \"phone\": null,\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"text\",\n \"body\": \"Hi, I saw your ad\",\n \"caption\": \"\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"none\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A customer using a WhatsApp username: `phone` is `null` and `from` carries the user id. Reply with `to: `; use `requestPhone` if you need the number.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "Click-to-WhatsApp ad referral", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"new\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUM0E3QjNDRTBGMkM4RjVBRDg1QzYA\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"username\": null,\n \"country\": null,\n \"phone\": \"972501234567\",\n \"to\": \"{{from}}\",\n \"senderName\": \"Dana Cohen\",\n \"type\": \"text\",\n \"body\": \"I would like to know more about the offer\",\n \"caption\": \"\",\n \"template\": null,\n \"isForwarded\": false,\n \"timestamp\": \"1789900000\",\n \"timestampMS\": 483921,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false,\n \"profilePic\": \"https://storage.99digital.online/profilePic/972501234567_1789900000_ab12cd34.jpg\",\n \"conversationTimeLeft\": 1435,\n \"isNewConversation\": 1,\n \"referral\": {\n \"ref_type\": \"ad\",\n \"ref_title\": \"Summer sale\",\n \"ref_body\": \"20% off everything\",\n \"ref_id\": \"120210000000000000\",\n \"ref_link\": \"https://fb.me/xyz123\",\n \"ref_image\": \"https://storage.99digital.online/files/1789900000Zx9Yw8Vu7T.jpg\"\n }\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "When the conversation started from a Facebook / Instagram ad or post, `referral` tells you which one (`ref_type` `ad` or `post`). `ref_image` is a copy of the creative, deleted after 7 days.", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "hook: update - delivery statuses", "description": "Sent for every status change of a message **you** sent (needs `readStatus: 1` in setWebhook). Match it to your send by `unique`.\n\n| Key | Meaning |\n|---|---|\n| `unique` | The `unique` you got from the send endpoint |\n| `to` | Your number; `from` = the customer (phone or user id) |\n| `ack` | 1 sent (one grey tick), 2 delivered (two grey), 3 read (two blue), 0 failed |\n| `conversationTimeLeft` | Minutes left in the customer's 24-hour window |\n| `isBilledTemplate` | 1 on the first delivered/read of a **billed** template conversation, else 0 |\n| `newTemplateType` | With `isBilledTemplate: 1`: 1 utility / authentication, 2 marketing |\n| `isNewConversation`, `newConversationType` | Legacy, always 0 |\n\nStatuses may arrive out of order (a `delivered` before a `sent`) - keep the highest `ack`. Read receipts depend on the customer's privacy settings.", "item": [ { "name": "ack 1 - sent", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"update\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"{{from}}\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"country\": null,\n \"timestamp\": \"1789900061\",\n \"conversationTimeLeft\": 1380,\n \"isBilledTemplate\": 0,\n \"newTemplateType\": 0,\n \"isNewConversation\": 0,\n \"newConversationType\": 0,\n \"ack\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "One grey tick: WhatsApp accepted the message.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "ack 2 - delivered (billed template)", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"update\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"{{from}}\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"country\": null,\n \"timestamp\": \"1789900061\",\n \"conversationTimeLeft\": 0,\n \"isBilledTemplate\": 1,\n \"newTemplateType\": 2,\n \"isNewConversation\": 0,\n \"newConversationType\": 0,\n \"ack\": 2\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Two grey ticks. Here the message was a marketing template that opened a billed conversation: `isBilledTemplate: 1`, `newTemplateType: 2`. This pair is sent once per billed template.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "ack 3 - read", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"update\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"{{from}}\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"country\": null,\n \"timestamp\": \"1789900061\",\n \"conversationTimeLeft\": 1380,\n \"isBilledTemplate\": 0,\n \"newTemplateType\": 0,\n \"isNewConversation\": 0,\n \"newConversationType\": 0,\n \"ack\": 3\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Two blue ticks. Only when the customer's privacy settings allow read receipts.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "ack 0 - failed", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"update\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"to\": \"{{from}}\",\n \"from\": \"972501234567\",\n \"from_id\": null,\n \"country\": null,\n \"timestamp\": 1789900061,\n \"conversationTimeLeft\": 1380,\n \"isBilledTemplate\": 0,\n \"newTemplateType\": 0,\n \"isNewConversation\": 0,\n \"newConversationType\": 0,\n \"ack\": 0\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "The message could not be delivered. The reason arrives separately as a `hook: system`, `type: messages` webhook (needs `system: 1`) with the same `unique`.", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "hook: system - failures, templates, account", "description": "System events (need `system: 1` in setWebhook). The sub-type is in `type`; the other keys are filled only when relevant and are `\"\"` otherwise.\n\n| `type` | When | Filled keys |\n|---|---|---|\n| `messages` | One of your messages failed | `unique`, `messageUpdate` (reason), `messageTo` |\n| `template` | A template was approved / rejected / paused / changed | `template`, `templateUpdate`, `templateCategory` |\n| `update` | Your daily conversation limit changed | `update` (the new limit) |\n| `issues` | Account quality / status changed | `issues` |", "item": [ { "name": "type: messages - a message failed", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"system\",\n \"type\": \"messages\",\n \"to\": \"{{from}}\",\n \"timestamp\": \"1789900061\",\n \"update\": \"\",\n \"issues\": \"\",\n \"template\": \"\",\n \"templateUpdate\": \"\",\n \"unique\": \"19545c3deca25da-0a504082ac7ad12-oiksAeQWvDMRtBQ\",\n \"messageUpdate\": 8,\n \"messageTo\": \"972501234567\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Why a message failed. `unique` matches your send, `messageTo` is the customer, `messageUpdate` the reason:\n\n| `messageUpdate` | Meaning |\n|---|---|\n| 1 | Server error - try to send again |\n| 2 | Billing issue - contact support |\n| 3 | The attached file is invalid - fix the file and resend |\n| 4 | The account is blocked for sending (or the customer blocked you) |\n| 5 | Daily limit of new conversations reached |\n| 6 | `to` equals `from` - you cannot message yourself |\n| 7 | The number cannot receive WhatsApp messages (old app / terms not accepted) |\n| 8 | More than 24 hours since the customer's last message - use a template |\n| 9 | Unknown error - contact support |\n| 10 | Variables / parameters problem (template body or header link) |\n| 12 | The template is not approved, paused or disabled |\n| 13 | The customer is in a Meta test group and cannot receive this template |\n| 14 | Marketing limit: no more marketing templates to this customer for now |\n| 15 | The template does not exist |\n| 16 | Too many messages in a short time - slow down |\n| 17 | Permission / server issue - contact support |", "auth": { "type": "noauth" } }, "response": [] }, { "name": "type: template - approved", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"system\",\n \"type\": \"template\",\n \"to\": \"{{from}}\",\n \"timestamp\": 1789900000,\n \"update\": \"\",\n \"issues\": \"\",\n \"template\": \"postman_welcome_text\",\n \"templateUpdate\": 1,\n \"unique\": \"\",\n \"messageUpdate\": \"\",\n \"messageTo\": \"\",\n \"templateCategory\": 1\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Your template passed review - you can send it now. `templateCategory`: 1 utility, 2 marketing, 3 authentication (present on approval and on a category change).\n\n| `templateUpdate` | Meaning |\n|---|---|\n| 1 | Approved - ready to send (`templateCategory` tells 1 utility / 2 marketing / 3 authentication) |\n| 2 | Rejected - wrong format / too many variables / too similar to an existing template |\n| 3 | Rejected - violates WhatsApp policy |\n| 4 | Rejected - marked as spam |\n| 5 | Rejected - other reason |\n| 6 | Paused for a few hours after too many reports |\n| 7 | Disabled permanently after too many reports |\n| 8 | Category changed by Meta (`templateCategory` = the new one) |\n| 9 | Deleted |\n| 10 | Flagged - high number of negative reports, be careful |\n| 11 | No longer flagged |", "auth": { "type": "noauth" } }, "response": [] }, { "name": "type: template - rejected", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"system\",\n \"type\": \"template\",\n \"to\": \"{{from}}\",\n \"timestamp\": 1789900000,\n \"update\": \"\",\n \"issues\": \"\",\n \"template\": \"postman_offer_image\",\n \"templateUpdate\": 2,\n \"unique\": \"\",\n \"messageUpdate\": \"\",\n \"messageTo\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "The template was rejected. Templates cannot be edited: fix the text and submit it again under a **new** name.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "type: update - daily limit changed", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"system\",\n \"type\": \"update\",\n \"to\": \"{{from}}\",\n \"timestamp\": 1789900000,\n \"update\": 10000,\n \"issues\": \"\",\n \"template\": \"\",\n \"templateUpdate\": \"\",\n \"unique\": \"\",\n \"messageUpdate\": \"\",\n \"messageTo\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Your number's tier changed; `update` is the new number of business-initiated conversations per 24 hours (250 / 1000 / 2000 / 10000 / 100000 / 1000000 = unlimited).", "auth": { "type": "noauth" } }, "response": [] }, { "name": "type: issues - account flagged", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"system\",\n \"type\": \"issues\",\n \"to\": \"{{from}}\",\n \"timestamp\": 1789900000,\n \"update\": \"\",\n \"issues\": 1,\n \"template\": \"\",\n \"templateUpdate\": \"\",\n \"unique\": \"\",\n \"messageUpdate\": \"\",\n \"messageTo\": \"\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Account quality / status events:\n\n| `issues` | Meaning |\n|---|---|\n| 1 | The account is flagged for spam - be careful |\n| 2 | The account is no longer flagged |\n| 3 | The account was blocked by WhatsApp |\n| 4 | The account is active again after a block / review |\n| 5 | The phone number was removed from the business manager - contact support |\n| 6 | The account was deleted - contact support |\n| 7 | Access to the account was removed by the client - contact support |\n| 8 | The account was sent to review by Meta |", "auth": { "type": "noauth" } }, "response": [] } ] }, { "name": "hook: contact / outgoing - coexistence numbers", "description": "Only for numbers connected in **coexistence** mode (the WhatsApp Business app keeps working next to the API). Sent whenever a `url` is set.", "item": [ { "name": "hook: contact - contact saved on the phone", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"contact\",\n \"type\": \"coexistence\",\n \"to\": \"{{from}}\",\n \"contact\": \"972501234567\",\n \"timestamp\": \"1789900000\",\n \"coexistence\": \"add\",\n \"contact_name\": \"Dana Cohen\"\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "A contact was added or edited in the WhatsApp Business app on the phone. `coexistence` is `add` (also for edits); `contact_name` is the name as saved on the phone.", "auth": { "type": "noauth" } }, "response": [] }, { "name": "hook: outgoing - message sent from the phone app", "request": { "method": "POST", "header": [ { "key": "Content-Type", "value": "application/json" } ], "body": { "mode": "raw", "raw": "{\n \"status\": \"OK\",\n \"hook\": \"outgoing\",\n \"unique\": \"HBgMOTcyNTAxMjM0NTY3FQIAEhgUOEY0QzE2N0E5RDNCMDA5RkQ1QjIA\",\n \"from\": \"{{from}}\",\n \"to\": \"972501234567\",\n \"type\": \"text\",\n \"body\": \"Sure, we are open until 20:00\",\n \"caption\": \"\",\n \"isForwarded\": false,\n \"timestamp\": \"1789900120\",\n \"timestampMS\": 102938,\n \"media\": false,\n \"quote\": false,\n \"quoteUnique\": false\n}", "options": { "raw": { "language": "json" } } }, "url": { "raw": "{{your_webhook_url}}", "host": [ "{{your_webhook_url}}" ] }, "description": "Someone answered the customer from the phone app (or WhatsApp Web) instead of the API - show it as an outgoing message in your system. `type` / `body` / `caption` follow the same rules as `hook: new`; media is re-hosted on our storage for 7 days. Messages sent through the API never produce this hook; later delivery statuses arrive as `hook: update` with the same `unique`.", "auth": { "type": "noauth" } }, "response": [] } ] } ] } ] }