Skip to main content
POST
Send Message

Authorizations

Authorization
string
header
required

Your API key (ta_live_…) from Settings → API keys, sent as Authorization: Bearer <key>. Keep it on a server: it can message every customer you have. A key is full, build or read-only; a request its level does not allow is refused with 403.

Headers

Idempotency-Key
string

Any unique string. A retry with the same key within 24 hours returns the first request's answer instead of acting twice.

Maximum string length: 255
Thinnest-Workspace
string

Developers only: the customer workspace this request acts in — its org_… id from POST /customers. Leave it out to act in your own workspace. Refused with 404 (Workspace not found.) when the id is unknown, is not one of your customers, or is not an org_… id; 410 when that customer was deleted (restore it with POST /customers/{id}/restore until it is erased); 403 when the key belongs to one customer workspace (it cannot act as another); 400 when your workspace is not a developer workspace. /customers/* and GET /customers/usage are your own workspace's and refuse the header with 400: call them without it.

Example:

"org_3fKq9TzQ1mN8vB2xR7cLpA"

Body

application/json
to
string
required

The customer's number. Include the + and the country code (a leading 00 works too); spaces are fine. A number without its country code is refused: nothing is assumed to be Indian or anywhere else.

Example:

"+91 98765 43210"

template
string
required

The name of an approved template in your workspace. Templates are named, not given by id, so the name stays stable across edits.

Example:

"order_confirmation_v1"

language
string

Which approved language version to send, exactly as approved — en, hi, en_US. Leave it out for the oldest approved version, so adding a language in the console never changes what a working integration sends.

Example:

"en"

variables
string[]

Values for the body's {{1}}, {{2}} … in order. Numbers are sent as text. For an authentication template, the code goes here once — it is copied into the copy-code button for you.

Example:
buttonVariables
string[]

The value for a link button's placeholder. Separate from variables because WhatsApp addresses the button on its own. Leave it out on an authentication template.

Example:
headerMediaUrl
string<uri>

A public link to the picture, video or document for a template with a media header. WhatsApp needs one on every send; leave it out and the template's own stored file is used.

Example:

"https://kaapico.in/parcels/10432.jpg"

formData
object

Pre-fills a WhatsApp form the template's button opens. Only fields the form marked pre-fillable reach the screen; other keys are ignored rather than refused. Values are sent as text.

Example:
idempotencyKey
string

Same as the Idempotency-Key header, for clients that cannot set headers. The header wins when both are sent.

Response

WhatsApp accepted the message — not yet that it arrived; delivery and read are reported afterwards. A replay of an Idempotency-Key that already succeeded answers the same with deduplicated: true and an Idempotent-Replayed: true header.

ok
boolean
required

WhatsApp accepted the message.

messageRef
string | null
required

WhatsApp's own receipt for the message — what delivery and read reports refer to, and what to quote when asking what happened to one.

deduplicated
boolean

Present, and true, only on a replay of an Idempotency-Key that already succeeded: nothing was sent this time.