Sending messages

Discover the template

Templates are listed as Meta holds them, with the placeholders each one expects, so your code can discover what to send without opening WhatsApp Manager. The list is cached for five minutes.

curl https://tawked.com/v1/whatsapp/templates \
  -H "Authorization: Bearer $TAWKED_KEY"

{
  "data": [
    {
      "id": "7000",
      "name": "order_received_v1",
      "language": "ar",
      "category": "UTILITY",
      "status": "APPROVED",
      "placeholders": {
        "kind": "named",
        "header": [],
        "body": ["name", "order"],
        "buttons": [{ "index": 0, "type": "url" }]
      },
      "managed": false
    }
  ]
}

id is Meta’s id of that language of the template: GET /v1/whatsapp/templates/{template_id} reads it in full. managed is false for a key you create.

Send

Every placeholder the template declares is required, extra keys are refused, and values are strings of 1 to 1024 characters without newlines or control characters. Give lang when the template exists in more than one language.

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-received" \
  -d '{
    "to": "0551234567",
    "template": "order_received_v1",
    "lang": "ar",
    "params": { "name": "أحمد", "order": "1042" },
    "buttons": [{ "index": 0, "parameter": "1042" }],
    "reference": "order-1042"
  }'

const res = await fetch('https://tawked.com/v1/whatsapp/messages', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.TAWKED_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': 'order-1042-received',
  },
  body: JSON.stringify({
    to: '0551234567',
    template: 'order_received_v1',
    lang: 'ar',
    params: { name: 'أحمد', order: '1042' },
    buttons: [{ index: 0, parameter: '1042' }],
    reference: 'order-1042',
  }),
});
const message = await res.json(); // keep message.id next to the order

$res = Http::withToken(env('TAWKED_KEY'))
    ->withHeaders(['Idempotency-Key' => 'order-1042-received'])
    ->post('https://tawked.com/v1/whatsapp/messages', [
        'to' => '0551234567',
        'template' => 'order_received_v1',
        'lang' => 'ar',
        'params' => ['name' => 'أحمد', 'order' => '1042'],
        'buttons' => [['index' => 0, 'parameter' => '1042']],
        'reference' => 'order-1042',
    ]);
$id = $res->json('id'); // keep the id next to the order

import os, requests

res = requests.post(
    "https://tawked.com/v1/whatsapp/messages",
    headers={
        "Authorization": f"Bearer {os.environ['TAWKED_KEY']}",
        "Idempotency-Key": "order-1042-received",
    },
    json={
        "to": "0551234567",
        "template": "order_received_v1",
        "lang": "ar",
        "params": {"name": "أحمد", "order": "1042"},
        "buttons": [{"index": 0, "parameter": "1042"}],
        "reference": "order-1042",
    },
)
message_id = res.json()["id"]  # keep the id next to the order

The answer is 202 Accepted. Meta has taken the message; the status arrives afterwards.

{
  "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
  "status": "accepted",
  "to": "+966551234567",
  "template": "order_received_v1",
  "lang": "ar",
  "reference": "order-1042",
  "price_halalas": 0,
  "created_at": "2026-09-06T12:00:00+03:00"
}

Field	Notes
`to`	A Saudi mobile in any accepted format, stored as E.164.
`template`	The name exactly as WhatsApp Manager lists it.
`lang`	Meta’s language code (`ar`, `en`, `en_US`). Required when the template has several.
`params`	Placeholder values, keyed by name for a named template or `"1"`, `"2"` for a positional one. An authentication template takes `{ "code": "..." }` only.
`header`	`{ "text": "..." }` when the template has a text header placeholder; refused otherwise (see Text headers). For a template that opens with an image, `{ "image": { "link": "https://..." } }` (see Image headers); with a document, `{ "document": { "link": "https://...", "filename": "..." } }` (see Document headers).
`buttons`	`[{ "index": 0, "parameter": "..." }]`, one entry per URL button with a placeholder. Refused for an authentication template.
`reference`	Your own reference, 1 to 64 printable characters, echoed back and searchable on Notifications → Messages.

Send an Idempotency-Key per business event and retry a 502 or a network error with the same key. A replay returns the original 202 with Idempotent-Replayed: true and sends nothing. See Reliability and limits.

Text headers

A template whose text header has a placeholder lists it under placeholders.header:

{
  "name": "order_shipped_v1",
  "language": "ar",
  "category": "UTILITY",
  "status": "APPROVED",
  "placeholders": {
    "kind": "named",
    "header": ["store"],
    "body": ["name", "order"],
    "buttons": []
  }
}

Its value goes in header.text, not in params. A header has one placeholder at most, and its value follows the same rules as a body value: 1 to 1024 characters, no newline.

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-shipped" \
  -d '{
    "to": "0551234567",
    "template": "order_shipped_v1",
    "lang": "ar",
    "header": { "text": "متجر النخبة" },
    "params": { "name": "أحمد", "order": "1042" },
    "reference": "order-1042"
  }'

A header for a template without a header placeholder answers 422 invalid_params, and so does a missing one for a template that has it.

Image headers

A template can open with an image (its header is an image Meta reviewed with the template). Each message carries its own: give the image’s public link in header.image.link. Meta fetches it when it sends, so it must answer at once with a JPG or a PNG of at most 5 MB.

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: autumn-sale-0551234567" \
  -d '{
    "to": "0551234567",
    "template": "autumn_sale_v1",
    "lang": "ar",
    "params": { "name": "أحمد" },
    "header": { "image": { "link": "https://example.com/autumn-sale.jpg" } }
  }'

The link must be https, at most 2048 characters, without spaces. A template that opens with an image and a send without header.image.link answers 422 invalid_params (`header.image.link` is required: this template opens with an image); an image for a template that does not open with one answers 422 invalid_params too. The field is optional for every other template, so existing integrations are unchanged.

Document headers

A template can open with a document, a PDF attachment: an invoice, a contract, an attendance sheet, a ticket (see Send a PDF attachment). Each message carries its own file: give its link in header.document.link and, optionally, the name the customer sees in header.document.filename. Meta downloads the file from the link when it sends, so the link must open without a sign-in at that moment; for a file that holds personal data, a signed link that lives a few minutes is enough.

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: contract-1042" \
  -d '{
    "to": "0551234567",
    "template": "document_attached",
    "lang": "ar",
    "params": { "name": "سارة", "document": "عقد الاشتراك" },
    "header": { "document": { "link": "https://example.com/files/contract-1042.pdf", "filename": "Contract-1042.pdf" } }
  }'

Field	Rule
`header.document.link`	Required for a template that opens with a document. `https`, at most 2048 characters, no spaces, a PDF. Meta’s limit for a document is 100 MB.
`header.document.filename`	Optional. 1 to 240 characters, no control characters, no `/` or `\`. Without it, WhatsApp shows a generic name: pass the file’s own name, ending in `.pdf`.

A template that opens with a document and a send without header.document.link answers 422 invalid_params, and so does a link that is not https or is too long, a document for a template that does not open with one, or an image for a template that opens with a document. A header of another shape (document that is not an object, a link that is not a string, extra keys, text beside document) answers 400 invalid_request. The message is charged and recorded like any other send, with the link and the file name it carried. The whole flow, from the template to the send, is in Send a PDF attachment. Video and location headers are not sent yet: such a template answers 422 unsupported_template with message media_header. A named placeholder is at most 20 characters at send time: Meta approves a template with a longer name, such as {{subscription_start_date}}, then refuses every message from it. Such a template answers 422 unsupported_template with message long_placeholder_name, and nothing is sent or charged. Rename the placeholder ({{start_date}}) in a new template or an edit.

Marketing and opt-outs

A customer who turns off your offers inside WhatsApp is opted out the first time Meta refuses a marketing message to them (Meta’s error 131050). From then on a template whose category is MARKETING to that number answers 422 consent_opted_out, and nothing is sent or charged. Utility and authentication templates still go: order news and codes are the service the customer asked for.

Authentication templates

An authentication template sends a one-time code from your own number (see Templates). It takes exactly one value, params.code: 4 to 15 letters or digits. Tawked puts the code in Meta’s text and on the button, so send no buttons and no header. The listing shows the template as "placeholders": { "kind": "named", "header": [], "body": ["code"], "buttons": [] }.

curl -X POST https://tawked.com/v1/whatsapp/messages \
  -H "Authorization: Bearer $TAWKED_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: login-5521-code-1" \
  -d '{
    "to": "0551234567",
    "template": "login_code",
    "lang": "ar",
    "params": { "code": "482913" },
    "reference": "login-5521"
  }'

The answer is the same 202 Accepted as any send:

{
  "id": "5b1e7c2a-3f4d-4e8a-9b6c-2d1f0a9e8c7b",
  "status": "accepted",
  "to": "+966551234567",
  "template": "login_code",
  "lang": "ar",
  "reference": "login-5521",
  "price_halalas": 0,
  "created_at": "2026-09-28T12:00:00+03:00"
}

A code outside 4 to 15 letters or digits, any other key in params, buttons or header answers 422 invalid_params with message naming the field. Tawked does not check the code: comparing what the customer types is your code’s job. Only Meta receives the code; Notifications → Messages and its Tawked Chat conversation show •••••• in its place. For codes by SMS, with the check done for you, use Tawked Verify.

Statuses and webhooks

accepted then sent, delivered, read, or failed from any of the first three. Statuses arrive from Meta within about a minute, are applied in order and never go backwards. A message stops being tracked 48 hours after the send and keeps its last status. Read the current state with GET /v1/whatsapp/messages/{id}:

{
  "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
  "status": "failed",
  "to": "+966551234567",
  "template": "order_received_v1",
  "lang": "ar",
  "reference": "order-1042",
  "price_halalas": 0,
  "error": { "code": "131026", "message": "Message undeliverable" },
  "created_at": "2026-09-06T12:00:00+03:00",
  "sent_at": null,
  "delivered_at": null,
  "read_at": null,
  "failed_at": "2026-09-06T12:00:03+03:00"
}

Or receive one webhook per status change, at each of the application’s webhook endpoints that chose the message.* events, signed and retried exactly like verification.* events. Only the status reached is announced: a message that jumps straight to read gets one message.read. to is masked in webhooks the way the console shows it, so keep your own copy of the destination next to the returned id or your reference.

{
  "event": "message.delivered",
  "data": {
    "id": "0f4c9c0e-6d2b-4b8a-9c3e-7a1d2e3f4a5b",
    "status": "delivered",
    "application_id": "c2a10f3e-8b7a-4d2e-9c1a-1a2b3c4d5e6f",
    "to": "+9665•• ••• 000",
    "template": "order_received_v1",
    "lang": "ar",
    "reference": "order-1042",
    "price_halalas": 0,
    "error": null,
    "occurred_at": "2026-09-06T09:00:04.512Z",
    "created_at": "2026-09-06T09:00:01.087Z"
  },
  "sent_at": "1788685205201"
}

Signature verification is the same as for verification events: see Webhooks.

Get started

Verify

Notifications

Email

Webhooks and errors

Partners

Build with AI

Sending messages

Discover the template

Send

Text headers

Image headers

Document headers

Marketing and opt-outs

Authentication templates

Statuses and webhooks

​Discover the template

​Send

​Text headers

​Image headers

​Document headers

​Marketing and opt-outs

​Authentication templates

​Statuses and webhooks

Discover the template

Send

Text headers

Image headers

Document headers

Marketing and opt-outs

Authentication templates

Statuses and webhooks