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

NameTypeRequiredDescription
organization_idintegerYesYour organization ID.
contact_idintegerYesContact 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_idintegerNoNumber to write from: an id from List WhatsApp numbers. Must be an active number of the organization.
whatsapp_numberstringNoAlternative 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_id is filled from phone_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

StatusWhen
400 Bad Requestorganization_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 ForbiddenThe 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.