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.
The 24-hour service window
Section titled “The 24-hour service window”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.
Sending a template
Section titled “Sending a template”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.
Variables
Section titled “Variables”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.
When a send is refused
Section titled “When a send is refused”| 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. |
Replying in free text
Section titled “Replying in free text”Inside the window, reply in plain text — no approved template needed:
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.
Sending a file
Section titled “Sending a file”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:
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.
Sending buttons or a list
Section titled “Sending buttons or a list”Inside the window you can also ask the customer to choose. Give interactive in place of
text, with up to three reply buttons:
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.
Following delivery
Section titled “Following delivery”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.