Start a WhatsApp conversation
Start (or reuse) the WhatsApp conversation with a contact from one of your WhatsApp numbers. An organization can connect several numbers: each number has its own conversation with the contact, and messages always go out from the conversation's number.
Endpoint
POST/conversation-initiate-whatsapp
Body
| Name | Type | Required | Description |
|---|---|---|---|
organization_id | integer | Yes | Your organization ID. |
contact_id | integer | Yes | Contact to write to. Needs a WhatsApp ID, a phone with country code (phone + phone_country_code), or a WhatsApp Business-Scoped User ID. |
whatsapp_channel_id | integer | No | Number to write from: an id from List WhatsApp numbers. Must be an active number of the organization. |
whatsapp_number | string | No | Alternative to whatsapp_channel_id: the number's ID, internal name (label, e.g. "Ventas"), verified name, or phone number (at least 6 digits, any format). |
Which number is used: whatsapp_channel_id, else whatsapp_number, else the oldest active number of the organization (lowest id).
Request
Response
The conversation object. If the contact already has a conversation on that number it is returned instead of creating a new one.
json
Behavior
- A new conversation is assigned to the API key's user (
assigned_user_id). - When the contact has a phone but no WhatsApp ID, the contact's
channel_whatsapp_wa_idis filled fromphone_country_code+phone. - Then send a WhatsApp template (required to open a chat outside the 24-hour window) or a regular message.
- Members restricted to some numbers (channel access rules) cannot start conversations from numbers they cannot see.
Errors
| Status | When |
|---|---|
400 Bad Request | organization_id or contact_id missing; the number is not an active number of the organization; no number matches whatsapp_number; the organization has no active WhatsApp number; the contact has no phone or WhatsApp ID. |
403 Forbidden | The API key's user has no access to that WhatsApp number. |
Report an issue with this documentation
Please log in to report issues with our documentation.