Send an approved WhatsApp template in a conversation

POST 
/api/conversations/:conversationId/whatsapp/template

Sends one of the channel's approved message templates to the customer — the only message WhatsApp delivers once the 24-hour service window has closed. It LEAVES the workspace and cannot be taken back. 201 means stored and handed to WhatsApp; the delivery outcome arrives later on the message's status. Allowed to whoever may reply in the conversation.

The template's structure is read from the channel's synced copy, never from the request: only the send-time values are accepted here (body and header variables, a media or location header, a coupon, dynamic link values, carousel cards, product and flow parameters). A value the template's shape needs and the request lacks is a 422 before anything is sent.

Meta's per-user marketing limit. If the template's category is MARKETING and the contact's last marketing message on this WhatsApp number failed with Meta error 131049 less than 24 hours ago — and the contact has not written since — the send is refused with a 409 (error: marketing_limit_cooldown) carrying retry_after, the moment the warning lifts. Sending again inside that window can make Meta close delivery to that person for a whole day. To send anyway, repeat the request with confirm_marketing_cooldown: true; the message then records who insisted under meta.marketing_cooldown_override. Utility and authentication templates are never held back.

Request

Responses

201

Created message.

401

Not authenticated. code: account_disabled means the member's seat was deactivated in this workspace: the session is over even though the token was not revoked (clients sign out and clean up).

403

Authenticated but not allowed.

404

Resource not found (or not visible to the current tenant).

409

A MARKETING template to a contact still inside Meta's per-user marketing limit on this number. Nothing was stored or sent. Repeat with confirm_marketing_cooldown: true to send anyway.

422

Not a WhatsApp conversation, an unknown template, or a send-time value the template's shape needs is missing or too long.