Conversations
A conversation is one chat thread between your organization and a contact on one channel (WhatsApp, Instagram, Messenger, webchat, SMS or the AI assistant playground). Use it to list and filter your inbox, assign owners and AI assistants, move threads through pipelines, and close or reopen them. Messages live in Conversation messages.
Endpoints
| Method | Path | Description |
|---|---|---|
GET | /conversations | List conversations |
GET | /conversations/:id | Get a conversation |
POST | /conversations | Create a conversation |
PATCH | /conversations/:id | Update a conversation |
DELETE | /conversations/:id | Delete a conversation |
POST | /conversation-initiate-whatsapp | Start a WhatsApp conversation |
POST | /conversations-bulk-actions | Run a bulk action |
GET | /conversations-bulk-actions | List bulk actions |
GET | /conversations-bulk-actions/:id | Get a bulk action |
The conversation object
json
Fields
| Field | Type | Description |
|---|---|---|
id | integer | Read-only. Unique ID. |
organization_id | integer | Organization that owns the conversation. Required on create. |
channel | string | One of whatsapp, instagram, messenger, webchat, playground, sms. Required on create. Decides which message service holds its messages. |
contact_id | integer | Contact on the other side. Required on create. |
whatsapp_channel_id | integer | null | WhatsApp conversations: the WhatsApp number the thread belongs to. Messages always go out from this number. |
contact_phone | string | null | SMS conversations: the contact's phone number. |
our_phone_number | string | null | SMS conversations: your phone number used in the thread. |
voice_phone_number_id | integer | null | SMS conversations: ID of your phone number record used in the thread. |
status | string | One of open, closed. Default open. |
assigned_user_id | integer | null | Human owner (a member of the organization). null = unassigned. |
assigned_ai_assistant_id | integer | null | AI assistant answering the thread. null = no AI. Must belong to the same organization. |
pipeline_id | integer | null | Conversation pipeline (type conversation). |
pipeline_stage_id | integer | null | Stage inside pipeline_id. null = the pipeline's Incoming column. |
unread_count | integer | Unread incoming messages. Default 0. Set 0 to mark read, 1 to mark unread. |
blocked | boolean | When true, incoming messages of the thread are ignored. Default false. |
meta_contact_first_name | string | Contact first name copied onto the conversation (used by list and search). |
meta_contact_last_name | string | Contact last name copied onto the conversation. |
meta_contact_channel_wa_id | string | null | WhatsApp: the contact's WhatsApp phone ID (digits with country code). |
meta_contact_channel_wa_user_id | string | null | WhatsApp: the contact's Business-Scoped User ID when Meta sends one instead of a phone number. |
meta_contact_channel_wa_username | string | null | WhatsApp: the contact's WhatsApp username, when known. |
meta_contact_channel_wa_profile_name | string | null | WhatsApp: the contact's WhatsApp profile name. |
meta_contact_channel_instagram_profile_name | string | null | Instagram: the contact's Instagram profile name. |
meta_contact_avatar_url | string | null | Contact avatar URL. |
meta_contact_tags | array | Read-only copy of the contact's tags: { "id", "name", "color" }. Filter with tag_id on List. |
last_message_received | string (date-time) | Read-only. Time of the last incoming message. |
last_message_sent | string (date-time) | Read-only. Time of the last outgoing message. |
last_message_system | string (date-time) | Read-only. Time of the last system message. |
last_interaction_at | string (date-time) | Read-only. Time of the last message in any direction. Sort the inbox by this field. |
last_message_sent_preview | string | null | Read-only. Preview text of the last message. |
ai_context_cut | string (date-time) | null | The AI assistant only reads messages after this time. Send any non-empty value in a PATCH to cut the context now (see Update). |
ai_resume_instruction | string | null | Read-only. Instruction the AI assistant follows on its next reply, set when an assistant is reassigned with a resume instruction in the app. |
ai_resume_instruction_set_at | string (date-time) | null | Read-only. When ai_resume_instruction was set. |
handoff_reason | string | null | Why the AI assistant handed the thread to a human. Cleared when the AI context is cut. |
next_follow_up_rule_id | string | null | Read-only. AI follow-up rule scheduled next. |
next_follow_up_date_time | string | null | When the next AI follow-up message is scheduled. Setting it schedules the follow-up. |
follow_up_count | integer | Read-only. AI follow-ups already sent in the current cycle. Default 0. |
last_ai_response_at | string (date-time) | null | Read-only. Time of the last AI assistant reply. |
token_limit_reached_at | string (date-time) | null | Read-only. When the AI safeguards stopped the assistant on this thread. Reset when you assign an AI assistant. |
token_limit_reason | string | null | Read-only. Why the AI safeguards stopped the assistant. |
ai_auto_assignment_disabled | boolean | When true, automatic AI assignment rules skip this thread. Default false. Assigning an AI assistant resets it to false. |
ai_auto_assignment_disabled_reason | string | null | Reason stored with ai_auto_assignment_disabled. |
conversation_summary | string | null | Read-only. AI summary of older messages. Cleared when the AI context is cut. |
conversation_summary_updated_at | string (date-time) | null | Read-only. When conversation_summary was last written. |
pinned_messages | array | Up to 3 pinned messages: { "message_id", "message_type", "preview", "destination", "pinned_at", "pinned_by_user_id" }. Default []. |
created_at | string (date-time) | Read-only. Creation time. |
updated_at | string (date-time) | Read-only. Last update time. |
deleted_at | string (date-time) | null | Read-only. Set when the conversation is deleted. |
Reads are limited to your API key's organization.
Related
- Conversation messages: list, send and delete messages
- Conversation files: attachments
- Predefined messages: canned replies
- WhatsApp numbers and WhatsApp templates
- Automation executions: run an automation on a conversation
- Pipelines and Pipeline stages (type
conversation)
Report an issue with this documentation
Please log in to report issues with our documentation.