Skip to content

Sending messages

WhatsApp does not let a business message a customer freely. What you may send depends on whether the customer has messaged you recently.

When a customer sends a message, a 24-hour window opens. Inside it a business may reply with free text. Outside it, only a template that Meta has approved in advance may be sent.

This is Meta’s rule, not ours.

Give exactly one of template or text on a send. A template works at any time; free text works only while the window is open.

Terminal window
curl -s -X POST "$TKANA_API/messages" \
-H "Authorization: Bearer $TKANA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": { "phone": "+966501234567" },
"channel": "whatsapp",
"template": {
"name": "booking_reminder",
"language": "ar",
"variables": { "customer_name": "Sara", "time": "14:30" }
}
}'

You get 202 with the provider’s message id:

{
"id": "wamid.HBgMOTY2NTAxMjM0NTY3...",
"conversationId": null,
"status": "sent",
"sentAt": "2026-09-22T21:30:00.000Z"
}

An unknown phone creates the customer, so you do not have to look one up first. Give to.customerId instead when you already know them — one or the other, never both. A send that is refused creates nobody.

The Idempotency-Key is required here, unlike elsewhere in this API: a retried send that went through twice is a message your customer received twice. Without one you get 422.

You cannot choose the conversation a message lands in. It joins the customer’s WhatsApp conversation when it is delivered, so conversationId is refused rather than quietly ignored.

Bind every variable the template declares, by name:

  • A named template ({{customer_name}}) takes those names as keys.
  • A positional template ({{1}}, {{2}}) takes the numbers as keys: {"1": "Sara"}.

The names come from your template as Meta holds it, not from anything you send, so a key we do not recognise does not silently replace one we do. A missing one is missing_variables, and every missing name is listed in errors — Meta rejects a template with an empty parameter rather than sending it with a gap.

A template is also per language: booking_reminder in Arabic and in English are two separate approved templates, so name the language explicitly.

Code Status What to do
channel_not_connected 409 The organization has no connected WhatsApp number. Connect one in the portal under Channels.
template_not_approved 422 No template by that name and language, or Meta has not approved it yet. detail carries the status.
missing_variables 422 Bind the names listed in errors.
provider_error 502 Meta refused the send; detail carries their code and message, for example 131047 re-engagement message.

Inside the window, reply in plain text — no approved template needed:

Terminal window
curl -s -X POST "$TKANA_API/messages" \
-H "Authorization: Bearer $TKANA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": { "customerId": "0d2f6a7e-4c3b-4b1a-9c58-2f1e8b6a9d10" },
"channel": "whatsapp",
"text": "Your technician is on the way and will arrive by 4 pm."
}'

Unlike a template, the reply is recorded in the conversation immediately, so the response carries a real conversationId and the message appears in the portal thread at once, labelled with your API key’s name.

Outside the window you get 422 outside_service_window, with the moment it closed in detail, and nothing is sent — so falling back to a template is safe.

Only the customer’s own messages open the window. Your replies do not extend it, which is why a busy thread can still be closed to free text. If you are unsure, send the text and fall back to a template on outside_service_window; that costs one refused call and is more reliable than tracking the clock yourself.

Inside the same window you can send a photo, document, video or voice note. Give media in place of text, with a public HTTPS link to the file:

Terminal window
curl -s -X POST "$TKANA_API/messages" \
-H "Authorization: Bearer $TKANA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": { "customerId": "0d2f6a7e-4c3b-4b1a-9c58-2f1e8b6a9d10" },
"channel": "whatsapp",
"media": {
"type": "document",
"url": "https://files.example.com/invoice-1042.pdf",
"fileName": "invoice-1042.pdf",
"caption": "Your invoice for order 1042"
}
}'
Field Rules
type image, document, video or audio.
url HTTPS, reachable from the internet. WhatsApp downloads the file from it, so it must stay available until the message is delivered.
caption Optional, up to 1,024 characters. Not allowed on audio.
fileName Optional, documents only. The name the customer sees.

WhatsApp limits each type’s format and size. See Meta’s supported media types.

The file is recorded in the conversation at once, like a text reply, and the message’s media lists it with its url. Outside the window you get 422 outside_service_window with errors naming media, and nothing is sent.

If WhatsApp cannot fetch the link, the send is still accepted, and GET /messages/{id} later reads failed with WhatsApp’s reason in failureReason.

Inside the window you can also ask the customer to choose. Give interactive in place of text, with up to three reply buttons:

Terminal window
curl -s -X POST "$TKANA_API/messages" \
-H "Authorization: Bearer $TKANA_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: $(uuidgen)" \
-d '{
"to": { "customerId": "0d2f6a7e-4c3b-4b1a-9c58-2f1e8b6a9d10" },
"channel": "whatsapp",
"interactive": {
"type": "buttons",
"body": "Confirm your booking on Thursday at 4 pm?",
"buttons": [
{ "id": "confirm-1042", "title": "Confirm" },
{ "id": "move-1042", "title": "Pick another time" }
]
}
}'

Or a list, which the customer opens with one button:

{
"type": "list",
"body": "Pick a time for Thursday",
"button": "See times",
"sections": [
{
"title": "Afternoon",
"rows": [
{ "id": "slot-16", "title": "4 pm", "description": "With Sara" },
{ "id": "slot-17", "title": "5 pm" }
]
}
]
}
Field Limit
body 1,024 characters. Required.
header, footer 60 characters each. Optional.
buttons 1 to 3. Each title is up to 20 characters, and titles must differ.
button The list’s button label, up to 20 characters.
sections Up to 10 rows across all sections. With more than one section, each needs a title of up to 24 characters.
rows title up to 24 characters, description up to 72.
every id A button id up to 256 characters, a row id up to 200. Unique within the message, and not starting with media_pick:, which tkana reserves.

A request over a limit is refused with 422, and errors names the field.

When the customer taps, you get message.received. Its message has buttonReply with the id you gave the button or row, and the title they saw:

{
"senderType": "customer",
"content": "Confirm",
"buttonReply": { "id": "confirm-1042", "title": "Confirm" }
}

Use the id to know which choice was made. The message you sent reads back with your interactive payload in richContent, and the portal thread shows its buttons.

Terminal window
curl -s "$TKANA_API/messages/$MESSAGE_ID" \
-H "Authorization: Bearer $TKANA_KEY"

status moves sent → delivered → read, or failed with the provider’s reason in failureReason — Meta reports a failure asynchronously, minutes after accepting the send.

Poll this endpoint for a template send. The message.sent webhook fires for messages that are in a conversation, and a template joins the conversation only once it is delivered, so it is not the event to wait on here.

conversationId is null until the message is confirmed delivered. The customer’s conversation shows what they actually received, so a message sits outside the thread until Meta says it arrived — then it appears, labelled with the name of the API key that sent it.