Skip to main content
POST
Send a WhatsApp message
One endpoint for every outbound WhatsApp message, driven from your own platform. Pick the shape with type; the rest of the body is that type’s fields plus the shared phone_number_id, contact, reference_id and idempotency_key. The contact must have a phone number: an unknown phone number creates the contact, while an id or email must point at an existing contact that has one.

Templates and sessions

A template is the only type that can go out at any time. What happens to it depends on whether the contact already has an open session on that number:
  • No open session: the template is sent and no session opens. Nothing shows in the inbox. When the customer replies, their session opens carrying every template sent to them that has not yet appeared on a session, oldest first, before the reply. The response says "delivery": "hidden".
  • Open session: by default the template is added to it, visibly ("delivery": "session"). Send "when_session_open": "hidden" to keep it off the timeline until the customer’s next reply, which then pulls it in before the reply.
Templates to a contact on the outbound blocklist for WhatsApp are refused with 422 and "error": "recipient_blocked". A customer who stops marketing messages from you on their device is added to that blocklist automatically.

Every other type

Text, media, location, location requests, buttons, lists and link buttons are replies: WhatsApp only delivers them inside the contact’s 24-hour reply window, and they land on the contact’s open session.
  • Window closed → 422 with "error": "reply_window_closed". Send a template instead.
  • Window open but the session is closed → 422 with "error": "no_open_session". Send a template instead; the customer’s reply opens a new session.
On the timeline, buttons, lists, link buttons and locations read as text (Do you approve?\n[Approve] [Decline]), with the full request kept on the message. Media URLs must be public; links into private networks are refused.

Errors from WhatsApp

When WhatsApp refuses the message, the answer carries a stable error code and WhatsApp’s own explanation in message:

Retries

Send the same idempotency_key on a retry and you get the first result back without a second message going out. Keys are permanent per organization and the body is not compared, so key on the message (order id + event), not on the order alone.
  • A key whose send WhatsApp refused is released: the retry sends.
  • A key whose outcome is unknown stays taken and keeps answering 502 send_outcome_unknown; use a new key to send again.
  • A retry that overlaps the first request gets 409 with "error": "idempotency_key_in_flight". A first request that never finished on our side stops blocking after 10 minutes: its key then answers 502 send_outcome_unknown like any other unknown outcome.
reference_id is yours (an order id, for example): it is stored and echoed back in the response.

Delivery

The response confirms WhatsApp accepted the message (whatsapp_message_id). Delivery, read and failure receipts are kept on the send for the inbox and the timeline; they are not yet readable through the API.

Authorizations

Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Body

application/json
phone_number_id
string
required

The WhatsApp number to send from. GET /whatsapp/senders lists them.

Minimum string length: 1
contact
object
required

Who receives it, by id, email or phone number. An unknown phone number creates the contact; an id or email must be an existing contact that has a phone number.

type
string
required
Allowed value: "template"
template_id
string
required
Minimum string length: 1
variables
string[]
required

Positional values: header placeholders, then body, then buttons.

reference_id
string

Your own id for this message (an order id). Stored and echoed back.

Required string length: 1 - 255
idempotency_key
string

Send the same key on a retry and the first result comes back without a second message going out. Keys are permanent per organization and the body is not compared, so key on the message (order id + event), not on the order. A key whose send WhatsApp refused is released; one whose outcome is unknown stays taken.

Required string length: 1 - 255
header_document_filename
string

Name the recipient sees on a DOCUMENT header.

Minimum string length: 1
when_session_open
enum<string>
default:append

When the contact already has an open session on this number: append (default) puts the template in it, visibly; hidden keeps it off the timeline until the customer replies.

Available options:
append,
hidden

Response

Default Response

id
string<uuid>
required

Our id for this send.

Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
whatsapp_message_id
string
required
reference_id
string | null
required
delivery
string
required

The message is on a session timeline now.

Allowed value: "session"
opencx_session_id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$
opencx_message_id
string<uuid>
required
Pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$