Skip to content
Developers

Endpoints

Messages

Send messages and WhatsApp templates as your business, and read message history.

Paths are relative to the base URL. Each card lists the permission the call needs and every parameter, with its type and limits.

POST
/conversations/:id/messages

Send a message to the customer on the conversation's channel, as your business.

Permission: inbox

Path parameters

  • idrequiredinteger

    Conversation ID.

JSON body

  • textoptionalstring

    Up to 4,096 characters. Send text, media_url, or both.

  • media_urloptionalstring (URL)

    Public https:// URL of a file to attach, up to 2,048 characters.

  • media_typeoptionalenum

    Required with media_url.

    Allowed values:imagevideoaudiodocument

  • pause_aioptionalboolean

    Also pause AI replies on the conversation. Default false.

  • Answers 201 with the message.
  • 422 outside_messaging_window when the channel does not allow a free-form message right now (for example after WhatsApp's 24-hour window — send a template instead).
  • 422 channel_not_supported or invalid_media_url; 502 channel_send_failed when the channel rejected the message (the error details include the stored message).
POST
/conversations/:id/whatsapp-template

Send an approved WhatsApp template. Works outside the 24-hour window.

Permission: inbox

Path parameters

  • idrequiredinteger

    Conversation ID.

JSON body

  • template_namerequiredstring

    Template name from GET /whatsapp-templates, up to 512 characters.

  • languagerequiredstring

    Template language code, e.g. "en_US" (2–15 characters).

  • componentsoptionalarray of objects

    WhatsApp Cloud API template components (header/body/button parameters), up to 20. A JSON string is accepted too.

  • pause_aioptionalboolean

    Also pause AI replies on the conversation. Default false.

  • 422 not_whatsapp for a non-WhatsApp conversation; 422 whatsapp_not_connected when WhatsApp is not connected.
GET
/messages

List the messages of a conversation, newest first.

Permission: inbox
Paginated

Query parameters

  • conversation_idrequiredinteger

    The conversation to read.

GET
/messages/:id

Retrieve a message.

Permission: inbox

Path parameters

  • idrequiredinteger

    Message ID.

GET
/whatsapp-templates

List the workspace's WhatsApp message templates.

Permission: inbox

Query parameters

  • statusoptionalstring

    A template status such as APPROVED, PENDING or REJECTED, or "all". Default APPROVED.

  • 422 whatsapp_not_connected when WhatsApp is not connected; 502 whatsapp_unavailable when WhatsApp did not answer.