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

MethodPathDescription
GET/conversationsList conversations
GET/conversations/:idGet a conversation
POST/conversationsCreate a conversation
PATCH/conversations/:idUpdate a conversation
DELETE/conversations/:idDelete a conversation
POST/conversation-initiate-whatsappStart a WhatsApp conversation
POST/conversations-bulk-actionsRun a bulk action
GET/conversations-bulk-actionsList bulk actions
GET/conversations-bulk-actions/:idGet a bulk action

The conversation object

json

Fields

FieldTypeDescription
idintegerRead-only. Unique ID.
organization_idintegerOrganization that owns the conversation. Required on create.
channelstringOne of whatsapp, instagram, messenger, webchat, playground, sms. Required on create. Decides which message service holds its messages.
contact_idintegerContact on the other side. Required on create.
whatsapp_channel_idinteger | nullWhatsApp conversations: the WhatsApp number the thread belongs to. Messages always go out from this number.
contact_phonestring | nullSMS conversations: the contact's phone number.
our_phone_numberstring | nullSMS conversations: your phone number used in the thread.
voice_phone_number_idinteger | nullSMS conversations: ID of your phone number record used in the thread.
statusstringOne of open, closed. Default open.
assigned_user_idinteger | nullHuman owner (a member of the organization). null = unassigned.
assigned_ai_assistant_idinteger | nullAI assistant answering the thread. null = no AI. Must belong to the same organization.
pipeline_idinteger | nullConversation pipeline (type conversation).
pipeline_stage_idinteger | nullStage inside pipeline_id. null = the pipeline's Incoming column.
unread_countintegerUnread incoming messages. Default 0. Set 0 to mark read, 1 to mark unread.
blockedbooleanWhen true, incoming messages of the thread are ignored. Default false.
meta_contact_first_namestringContact first name copied onto the conversation (used by list and search).
meta_contact_last_namestringContact last name copied onto the conversation.
meta_contact_channel_wa_idstring | nullWhatsApp: the contact's WhatsApp phone ID (digits with country code).
meta_contact_channel_wa_user_idstring | nullWhatsApp: the contact's Business-Scoped User ID when Meta sends one instead of a phone number.
meta_contact_channel_wa_usernamestring | nullWhatsApp: the contact's WhatsApp username, when known.
meta_contact_channel_wa_profile_namestring | nullWhatsApp: the contact's WhatsApp profile name.
meta_contact_channel_instagram_profile_namestring | nullInstagram: the contact's Instagram profile name.
meta_contact_avatar_urlstring | nullContact avatar URL.
meta_contact_tagsarrayRead-only copy of the contact's tags: { "id", "name", "color" }. Filter with tag_id on List.
last_message_receivedstring (date-time)Read-only. Time of the last incoming message.
last_message_sentstring (date-time)Read-only. Time of the last outgoing message.
last_message_systemstring (date-time)Read-only. Time of the last system message.
last_interaction_atstring (date-time)Read-only. Time of the last message in any direction. Sort the inbox by this field.
last_message_sent_previewstring | nullRead-only. Preview text of the last message.
ai_context_cutstring (date-time) | nullThe 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_instructionstring | nullRead-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_atstring (date-time) | nullRead-only. When ai_resume_instruction was set.
handoff_reasonstring | nullWhy the AI assistant handed the thread to a human. Cleared when the AI context is cut.
next_follow_up_rule_idstring | nullRead-only. AI follow-up rule scheduled next.
next_follow_up_date_timestring | nullWhen the next AI follow-up message is scheduled. Setting it schedules the follow-up.
follow_up_countintegerRead-only. AI follow-ups already sent in the current cycle. Default 0.
last_ai_response_atstring (date-time) | nullRead-only. Time of the last AI assistant reply.
token_limit_reached_atstring (date-time) | nullRead-only. When the AI safeguards stopped the assistant on this thread. Reset when you assign an AI assistant.
token_limit_reasonstring | nullRead-only. Why the AI safeguards stopped the assistant.
ai_auto_assignment_disabledbooleanWhen true, automatic AI assignment rules skip this thread. Default false. Assigning an AI assistant resets it to false.
ai_auto_assignment_disabled_reasonstring | nullReason stored with ai_auto_assignment_disabled.
conversation_summarystring | nullRead-only. AI summary of older messages. Cleared when the AI context is cut.
conversation_summary_updated_atstring (date-time) | nullRead-only. When conversation_summary was last written.
pinned_messagesarrayUp to 3 pinned messages: { "message_id", "message_type", "preview", "destination", "pinned_at", "pinned_by_user_id" }. Default [].
created_atstring (date-time)Read-only. Creation time.
updated_atstring (date-time)Read-only. Last update time.
deleted_atstring (date-time) | nullRead-only. Set when the conversation is deleted.

Reads are limited to your API key's organization.

Related

Report an issue with this documentation

Please log in to report issues with our documentation.