Skip to content

Conversations

Start a conversation

Finds the one-to-one conversation for a phone number on the workspace’s active connection, or creates it. If you include body, the text is sent right away. Calling it again for the same number returns the existing conversation.

POST/api/conversations
  • Bearer API key
  • Scope: write
  • or app session
  • Workspace: X-Tenant-ID (optional with a key)

Headers

  • Authorizationstringrequired

    Your API key as Bearer <key>. The word Bearer and the space are case-sensitive. Browser clients signed in to the app use the session cookie instead.

    Constraints
    Keys start with pk_live_ and are 56 characters long.
    Example
    Bearer pk_live_…
  • X-Tenant-IDuuidoptional

    Workspace id. Optional with an API key (a key always acts in its own workspace); if you send it, it must match the key’s workspace. Required with a session cookie. You can pass ?tenant=<id> instead.

    Example
    8d0f6c2e-3b1a-4c55-9a7e-2f4b6d1e9c30

Body

application/json
  • phonestringrequired

    Phone number with country code. Spaces, + and other non-digit characters are removed.

    Constraints
    8–15 digits after cleaning.
    Example
    +15550100123
  • bodystringoptional

    Optional first message (text). Leave it out to only open the conversation.

    Constraints
    On numbers linked by QR code, at most 4096 bytes.
    Example
    Hi Jordan, your order is ready for pickup.
  • channel_iduuidoptional

    Cloud API only: the Meta channel (phone number) to use. Defaults to the workspace’s primary Meta number.

Response

200 OKapplication/json

  • conversationConversation

    The conversation.

    Show child attributesHide child attributes16
    • iduuid

      Conversation id. Use it in /api/conversations/{id} paths.

    • workspace_iduuid

      Workspace the conversation belongs to.

    • whatsapp_jidstring

      WhatsApp chat id (JID), for example 15551234567@s.whatsapp.net for a person or …@g.us for a group.

    • channel_providerenum

      How the number is connected: scan (linked by QR code) or meta (WhatsApp Business Platform, Cloud API).

    • channel_iduuidmay be absent

      The Meta channel (phone number) the chat belongs to. Left out for QR-linked chats.

    • phone_number_idstringmay be absent

      Meta phone number id of the channel. Left out for QR-linked chats.

    • namestring

      Display name: the contact or group name, or +<digits> for a chat started by phone number.

    • typeenum

      individual or group.

    • phonestringmay be absent

      Phone number as digits only, without +.

    • group_subjectstringmay be absent

      Group subject, for group chats.

    • avatar_urlstringmay be absent

      Profile picture URL, when one has been downloaded.

    • last_messagestringnullable

      Preview of the newest message: its text, Photo for an image, or the file name (or Document) for a document. null when the chat has no messages.

    • last_message_attimestampnullable

      Time of the newest message as an RFC 3339 string in UTC. null when the chat has no messages.

    • unread_countinteger

      Unread incoming messages. 0 after the chat is marked as read.

    • assignee_iduuidmay be absent

      User id of the assigned teammate (a user id, not a membership id). Left out when unassigned.

    • assignee_namestringmay be absent

      Name of the assigned teammate.

  • messageMessagemay be absent

    The sent message. Left out when no body was given.

    Show child attributesHide child attributes15
    • iduuid

      Message id in whatsappx.si.

    • whatsapp_message_idstring

      Message id assigned by WhatsApp.

    • conversation_iduuid

      Conversation the message belongs to.

    • sender_jidstring

      WhatsApp id (JID) of the sender. For your own messages, the connected number.

    • sender_namestring

      Sender display name, when WhatsApp provides one (may be empty).

    • contentstring

      Message text. On numbers linked by QR code, images and documents carry their caption here. On the Cloud API, non-text messages are stored as a placeholder such as [image message].

    • message_typestring

      text, image or document on numbers linked by QR code. Non-text messages received through the Cloud API keep the type name Meta sends (for example image or audio) and have no downloadable media.

    • media_urlstringmay be absent

      Path of the downloaded media file, for example /api/media/<workspace>/<file>. Prefix it with https://whatsappx.si and send your API key to download it.

    • mime_typestringmay be absent

      MIME type of the media file.

    • file_namestringmay be absent

      Original file name of a document.

    • file_sizeintegermay be absent

      Media size in bytes.

    • timestamptimestamp

      When the message was sent on WhatsApp (RFC 3339).

    • from_meboolean

      true for messages sent from the connected number (by your team, the API or an automation).

    • statusenum

      received for incoming messages, sent for outgoing ones. Delivered and read receipts are not tracked.

    • created_attimestamp

      When whatsappx.si stored the message (RFC 3339).

Status codes

  • 200OK. The conversation, plus the sent message when body was given.
  • 400Bad request. Invalid input (enter a valid international phone number, invalid channel_id, invalid request body), or an agent signed in to the app tried to open a new chat (agents can only open chats assigned to them).
  • 401Unauthorized. The API key is unknown, revoked or expired (invalid or expired API key), or there is no key and no signed-in session (unauthorized).
  • 402Payment required. Only when subscriptions are enforced and the workspace has no active subscription. The body includes code: "payment_required".
  • 403Forbidden. The API key has the read scope, which only allows GET requests (API key is read-only). A key in another workspace gets API key belongs to a different workspace.
  • 409Conflict. No WhatsApp connection is ready to send (whatsapp is not connected).
  • 502Bad gateway. The conversation was found or created, but the first message could not be sent (for example message body too long, or WhatsApp rejected it). The response includes the conversation, so you can fix the text and retry with the send-message endpoint.

Things to know

  • Only one-to-one chats can be started this way; group conversations appear when the linked number receives or syncs them.
  • The new conversation’s name is the phone number (+<digits>) until WhatsApp provides a contact name.
  • Sessions with the agent role cannot start chats; API keys can.