Skip to content

Conversations

Assign a conversation

Assigns the conversation to a workspace member, or unassigns it. Only owners and admins signed in to the app can assign; API keys act as agents and always get 403.

PUT/api/conversations/{id}/assignee
  • Console only: owner or admin
  • Workspace: X-Tenant-ID

Path parameters

  • iduuidrequired

    Conversation id.

    Example
    6a1f3c52-8e0b-4d7a-b1f2-93c4d5e6f708

Headers

  • Cookiestringrequired

    The whatsappx_session cookie the app sets when you sign in. Browsers send it automatically; API keys are not accepted on this endpoint.

    Example
    whatsappx_session=…
  • X-Tenant-IDuuidrequired

    Workspace id. Required for session requests. You can pass ?tenant=<id> instead.

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

Body

application/json
  • assignee_iduuidoptional

    The teammate’s user id (user_id from the members list, not the membership id). Send null or "" to unassign.

    Example
    1c9e7b40-5d2a-4f8e-a3b6-0d7c8e9f1a2b

Response

200 OKapplication/json

  • 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.

Status codes

  • 200OK. The updated conversation with assignee_id and assignee_name (both left out after unassigning). In this response last_message is null.
  • 400Bad request. invalid assignee_id, assignee must be a workspace member, invalid request body or invalid conversation id.
  • 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).
  • 403Forbidden. The caller is not an owner or admin. API keys always get this response (a read key gets API key is read-only first).
  • 404Not found. The conversation does not exist in this workspace, belongs to the inactive connection (QR vs Cloud API), or (for agents signed in to the app) is not assigned to you.
  • 500Server error. Something went wrong on our side. Retry with backoff.