Skip to main content
The conversation tools let a coding agent triage, read, and act on conversations. They split across two scopes: conversations:read for listing and reading, conversations:write for replying and changing state. A key that lacks a scope gets an auth error naming the missing capability — that is an enforced boundary, not a bug.
Conversations are addressed by their display id — the per-account number shown in the dashboard URL and UI — not the global database id. Every tool below takes conversation_id as that display id.
Lists page at 25 per page (page is 1-based). Messages are cursor-paginated by message id (newest ~20 by default). Counts in list/search/filter results come back under meta.

​
Read tools

Scope: conversations:read.

​
list_conversations

List conversations in the account, newest activity first (25 per page). Returns {data:{meta:{...counts}, payload:[conversation,...]}}.

​
count_conversations

Return only the conversation counts for a filter, without the conversation list. Use this when you only need totals. Returns {meta:{mine_count, assigned_count, unassigned_count, all_count}}.

​
search_conversations

Full-text search conversations by message content. Returns {meta:{...counts}, payload:[conversation,...]}.

​
filter_conversations

Advanced conversation filtering with structured predicates. Each predicate is shaped like:
Returns {meta:{...counts}, payload:[conversation,...]}.

​
get_conversation

Fetch a single conversation by its display id. Returns the full conversation object — meta.sender/assignee/team, status, labels, priority, and the most recent message.

​
get_conversation_messages

List messages in a conversation (cursor-paginated by message id, newest ~20 by default). Returns {meta:{contact, assignee, ...}, payload:[message,...]}.

​
Write tools

Scope: conversations:write.

​
reply_to_conversation

Post a message to a conversation — a customer-visible reply or an internal note. Returns the created message object.
reply_to_conversation is customer-visible and immediate — with private=false (the default) the message is sent to the customer the moment the tool succeeds. Show the draft text to the human and reply only when asked. Use private=true for an internal note.

​
assign_conversation

Assign a conversation to an agent and/or a team. Provide at least one of assignee_id / team_id. Returns the assigned agent/team object (or {} when unassigned). Calling with neither argument raises an error.

​
set_conversation_status

Resolve, reopen, mark pending, or snooze a conversation. Returns {payload:{success, conversation_id, current_status, snoozed_until}}.
status is always required. Unlike the dashboard’s toggle, this tool never infers the target state — sending no status would silently flip open ↔ resolved, so it is mandatory.

​
set_conversation_priority

Set (or clear) a conversation’s priority. Returns {} on success.

​
add_conversation_labels

Set the labels on a conversation. Returns {payload:[label,...]}.
add_conversation_labels replaces the conversation’s entire label set — it is not additive. To add one label, first read the existing labels (via get_conversation) and send the union; otherwise you will drop every label not in your list.

Authentication & Scopes

How agent keys authenticate and the default-deny scope model.

Contact Tools

Find, create, update, and label contacts.

REST API

Call the same endpoints directly with a scoped token.