Sales tools reference

Every tool the Sales-Management MCP exposes, with full parameters. These are the same tools an agent gets from the From your sales platform connectors (or the single Sales Platform tools toggle), and the same tools an external MCP client like Claude Code or Cursor sees when you connect a ?domain= server — see MCP & connectors for connecting and Connectors cheat sheet for the app walkthrough.

Each section below is one connector (?domain= value). Drop the domain query parameter to get every tool on one server.

Conventions

• Auth — every external call needs the Authorization: Bearer mcp_… access key from Connect AI tools. The account_id in the URL selects the account but never authorizes the request.
• title — every tool also accepts an optional title string (a short human-readable label like "Create WhatsApp channel"). Agents fill it in so the app can show what a tool call is doing; you can ignore it from your own MCP client.
• IDs — a client_id is the lead's UUID from list_clients/get_client. A chat_id is the small integer from list_chats. A chat also carries a per-channel external client id (client_id on the chat row) and the unified common_client_id (= the lead's UUID). These are different values — the tools' parameter descriptions say which one they want.
• Dates — where a tool takes since_date/to_date, RFC3339 (2026-07-01T00:00:00Z) is always safe. Some filters silently ignore plain YYYY-MM-DD values (noted per tool).
• Errors — validation problems come back as MCP tool errors with a plain-English message. A few read tools instead return a JSON body like {"error": "Order not found"} (noted per tool).
• Pagination — list tools default to modest page sizes and cap the maximum (noted per tool). Use offset to page where a tool lists one; list_chats has no offset and pages by keyset (pass the response's next_last_active_before and next_before_id back as last_active_before and before_id).

Two custom-data buckets: custom_lead_fields vs client_context

The lead card has two separate places for structured data, and the client tools accept them as two separate parameters. Don't mix them up:

	custom_lead_fields	client_context
What it is	Free-form business data you (or your systems) put on a lead	Facts the AI collected from the lead in conversation
Where it renders	The lead card's editable "Additional info" panel	The lead card's read-only "Collected Context" panel
Shape	Flat key → string map ({"invoice_number": "INV-7"}); non-string values are JSON-encoded, never dropped	Nested objects allowed, mirroring the assistant's client_context_schema; invoices[] entries merge by invoice_number
Schema	None — any keys (new keys are auto-registered so the panel shows them)	Defined per assistant: enable the feature and set the field list with assistant_toggle_client_context / assistant_update_client_context_schema
Merge semantics	Key-by-key overlay — an incoming key replaces that key, other keys survive	Recursive deep merge — nested objects merge, invoices[] merges by invoice_number, unrelated keys survive
Storage	metadata.custom_lead_fields (in Go code this bucket is called custom client fields)	metadata.client_context

Three tools accept both buckets, with identical semantics everywhere: client_create and client_update persist them inline, and client_context_merge merges them with an optional before/after preview. get_client returns both under metadata. Cross-reference client_context keys with the assistant's client_context_schema (from get_assistant) to render human-readable labels. export_clients exports neither bucket.

The related assistant-side settings live in the Assistants connector: assistant_toggle_client_context turns collection on/off and assistant_update_client_context_schema defines which fields the AI collects — the schema lives on the assistant, the collected values live on each lead.

Assistants (sales_assistants)

Create and configure sales assistants, their skills and toolkit toggles, and run synchronous test chats.

list_assistants

List all active sales assistants (bots) for this account. Returns id, name, status, language, model. No parameters.

get_assistant

Get detailed info about a specific assistant including instructions, welcome message, integrations, follow-ups, metadata, and skills. The metadata surfaces the toolkit settings — notably enable_contact_details, enable_client_context, and client_context_schema (the {key, label, description} fields the bot collects from clients). Use it to render collected client_context values from get_client responses.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID

assistant_create

Create a new assistant (sales bot) for this account. It is created switched on, attached to the account's default pipeline when one exists.

Param	Type	Required	Description
bot_name	string	yes	Name of the assistant
instructions	string	no	System prompt / instructions
welcome_message	string	no	Welcome message sent to new conversations
language	number	no	Language code (0 = auto)

assistant_update

Update assistant fields: name, welcome message, language, communication style, status, model.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
bot_name	string	no	New name
welcome_message	string	no	New welcome message
language	number	no	Language code
communication_style	number	no	Communication style enum
status	number	no	0 = off, 1 = on
model	string	no	Model override

Notes: empty strings are ignored — you can't clear a text field with this tool. At least one field must be provided. status must be a JSON number.

assistant_update_instructions

Update assistant instructions (system prompt). Runs a moderation check before saving; the saved version is tagged and the tag returned.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
instructions	string	yes	New instructions text

assistant_list_skills

List all skills for an assistant with name, description, is_always_active, and sort order.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID

assistant_create_skill

Create a new skill for an assistant. Skills are loadable instruction modules; the slug is generated from the name.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
name	string	yes	Skill name
description	string	no	Short description of what the skill does
instructions	string	no	Skill instructions content
is_always_active	boolean	no	If true, the skill is always injected into the system prompt

assistant_update_skill

Update an existing skill's name, description, instructions, or active status.

Param	Type	Required	Description
skill_id	string	yes	The skill ID
name	string	no	New name
description	string	no	New description
instructions	string	no	New instructions
is_always_active	boolean	no	Always-active flag
sort_order	number	no	Display order

Notes: empty strings are ignored; at least one field must be provided.

assistant_delete_skill

Delete a skill by ID.

Param	Type	Required	Description
skill_id	string	yes	The skill ID to delete

assistant_get_config_link

Generate a link to the web UI assistant configuration page.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID

get_assistant_available_tools

List all tools (functions) available to a specific assistant based on its connected integrations, knowledge bases, and feature toggles. Returns tool names and descriptions by default — useful when writing or reviewing the assistant's instructions, which should reference these tool names.

To inspect what inputs a tool expects, pass tool_name to get one tool's full parameters JSON schema (parameter names, types, descriptions, required/optional status, enum values), or include_schemas: true to include the schema for every tool in the listing.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
tool_name	string	no	Return only this tool, with its full parameters JSON schema. An unknown name errors with the list of available tool names
include_schemas	boolean	no	Include each tool's parameters JSON schema in the listing (default false — the listing can be large for assistants with many connected tools)

Example single-tool response:

{
  "assistant_id": "42",
  "tools_count": 1,
  "tools": [
    {
      "name": "search_product",
      "description": "Search products in the knowledge base",
      "parameters": {
        "type": "object",
        "properties": {
          "query": { "type": "string", "description": "search query for product name" },
          "filter": { "type": "string", "enum": ["startswith", "contains", "exact"] },
          "limit": { "type": "number", "description": "max results to return" }
        },
        "required": ["query"]
      }
    }
  ]
}

Tools that take no arguments omit the parameters key.

test_chat_start

Start a test chat session with an assistant. Clears any previous test chat history; the assistant_id is the session key for subsequent messages.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID to test

test_chat_send

Send a message in an active test chat session and get the assistant's AI response. Uses the assistant's current live instructions, skills, and toolkit toggles — the same pipeline as the web test chat. Synchronous: waits for the full response.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID (same as from test_chat_start)
message	string	yes	The message to send to the assistant

Returns JSON (not plain text):

{
  "assistant_id": "42",
  "response": "the assistant's reply text",
  "tool_calls": [
    {
      "name": "get_order",
      "arguments": "{\"order_id\":55}",
      "result_preview": "first 500 chars of the tool result…",
      "result_bytes": 4120
    }
  ]
}

Notes: tool_calls traces every tool the assistant invoked while answering. result_preview is capped at 500 characters — the full tool results stay in the stored history; read them with test_chat_get_history. Test-chat traffic is free: test replies are recorded as test-chat usage, not billed as messages.

test_chat_get_history

Read the stored test chat history for an assistant, including the assistant's internal tool calls — use it to debug which tools ran and what they returned.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID (same as from test_chat_start)
limit	number	no	Number of recent messages to return (default 50, max 200)
include_tool_details	boolean	no	false (default): tool calls listed by name only, tool-result content omitted. true: each tool call as {id, name, arguments} plus the tool-result message content
include_business_context	boolean	no	false (default): platform-injected business-knowledge (RAG) context messages are stripped from the history. true: keep them — role tool messages named __business_knowledge__, content capped by max_tool_result_chars. Business context is the knowledge the platform fed the assistant while it answered, not a tool the assistant called
max_tool_result_chars	number	no	Max characters of each included tool-result or business-context message's content (default 2000, 0 = full stored content)

Notes: the session is per-assistant — one stored history per assistant, keyed by assistant_id. History persists until test_chat_start or test_chat_end clears it. Tool results truncated by max_tool_result_chars carry content_truncated: true and content_full_chars alongside the capped content. Platform-injected context notes are excluded by default, so the tool calls you see are the assistant's own — pass include_business_context=true to see them too.

test_chat_end

End an active test chat session and clear the chat history.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID to end the test chat for

assistant_toggle_contact_details

Enable or disable the Contact Details collection toolkit feature. When enabled, the assistant proactively collects contact info (name, email, phone) from clients during conversations. Maps to the Contact Details toggle on the configuration page.

Param	Type	Required	Description
assistant_id	integer	yes	The assistant ID (number or numeric string)
enabled	boolean	yes	True to enable, false to disable

assistant_toggle_client_context

Enable or disable the Client Context toolkit feature — the AI-collected bucket described above. When enabling you may pass a schema array defining the fields to collect. Enabling also creates an always-active Client Context Collection skill that teaches the bot when to save context, and syncs the voice agent; disabling removes that skill.

Param	Type	Required	Description
assistant_id	integer	yes	The assistant ID (number or numeric string)
enabled	boolean	yes	True to enable, false to disable
schema	array	no	Fields to collect; omit to keep the existing schema. Each item is {key, label, description}
schema[].key	string	yes (per item)	Stable machine-readable key (e.g. company_size)
schema[].label	string	yes (per item)	Human-readable label (e.g. Company Size)
schema[].description	string	no	Hint describing what to collect / when

assistant_update_client_context_schema

Replace the list of Client Context fields without toggling the feature. The provided array fully replaces the stored schema — use it to add, remove, rename, or re-describe fields after Client Context is already enabled.

Param	Type	Required	Description
assistant_id	integer	yes	The assistant ID (number or numeric string)
schema	array	yes	Full replacement schema; each item is {key, label, description}, key and label required

assistant_toggle_strip_kb_history

Enable or disable Strip knowledge base results from history across all knowledge-base integrations attached to an assistant. When enabled, KB tool results are removed from conversation history before the next LLM call, reducing input tokens (full results remain in chat logs and the agent can re-search). Applied to every KB integration sharing the assistant's knowledge base; the response reports how many integrations were updated.

Param	Type	Required	Description
assistant_id	integer	yes	The assistant ID (number or numeric string)
enabled	boolean	yes	True to enable, false to disable

Clients, Leads & Pipelines (sales_clients)

Leads with their notes, tasks, and attachment records; labels; pipelines and funnel stages; CSV/JSON export.

list_clients

List clients (leads/customers) with filtering by funnel status, labels, search, and pagination.

Param	Type	Required	Description
funnel_status	string	no	Filter by funnel status
labels	string	no	Comma-separated labels to filter by
search	string	no	Search across name, email, phone
pipeline_id	string	no	Filter by pipeline ID
has_phone_number	boolean	no	Only clients with a phone number (false is ignored, it does not filter for absence)
has_email	boolean	no	Only clients with an email (false is ignored)
order_by	string	no	last_active_desc, last_active_asc, created_at_desc, created_at_asc
limit	number	no	Max results (default 20, max 100)
offset	number	no	Offset for pagination

get_client

Get detailed info about a specific client including contact info, funnel status, labels, and metadata. The response includes metadata.client_context (only populated when the assistant has Client Context enabled) and metadata.custom_lead_fields — see the two buckets. Cross-reference client_context keys with the assistant's client_context_schema from get_assistant for human-readable labels.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID) = clients.id. Same value as a chat's common_client_id, not a chat's per-channel client_id

client_create

Create a new client (lead/customer) in a validated pipeline. Pass extra data inline via custom_lead_fields and/or client_context — both persist with the client. Never put structured data in a note; notes are free text and are not displayed as fields.

Param	Type	Required	Description
full_name	string	yes	Client full name
email	string	no	Email address (normalized)
phone_number	string	no	Phone number (normalized)
company_name	string	no	Company name
funnel_status	string	no	Initial funnel status; must exist in the client's effective pipeline (matched case-insensitively, stored with the pipeline's casing)
labels	array of string	no	Labels to assign
pipeline_id	string	no	Pipeline ID; when omitted, new clients use the account default
custom_lead_fields	object	no	Flat key/value custom fields for the lead card's editable "Additional info" panel, e.g. {"invoice_number":"INV-7"}. Values stored as strings; non-string values JSON-encoded. Merged key-by-key
client_context	object	no	Structured context for the read-only "Collected Context" panel, mirroring the assistant's client_context_schema. Nested objects supported; invoices[] entries merge by invoice_number

Notes: if a client with the same normalized email or phone already exists, returns {"error":"DUPLICATE_CLIENT","existing_client_id":"…"} (plus match_reason) and does not modify the existing client — use client_update or client_context_merge instead.

client_update

Update client fields: name, contact info, funnel status, labels, manager. Also accepts custom_lead_fields and client_context, which are merged into the client's existing metadata — unrelated keys are preserved.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)
full_name	string	no	New name
email	string	no	New email
phone_number	string	no	New phone
company_name	string	no	New company
funnel_status	string	no	New funnel status (not validated on this path)
labels	array of string	no	Replaces the label set (not additive)
manager_id	string	no	Assigned manager ID
custom_lead_fields	object	no	Same contract as on client_create
client_context	object	no	Same contract as on client_create

Notes: empty strings are ignored — you can't clear a field with this tool.

client_context_merge

Merge data into a client's metadata.client_context and/or metadata.custom_lead_fields without wiping unrelated fields. Deep-merges nested objects; invoices[] entries merge by invoice_number (existing updated in place, new appended). Idempotent. With confirm=false (default) it returns a before/after preview without writing; with confirm=true it applies the merge and returns the updated client. Prefer client_create/client_update when creating or editing a client; use this when you want a preview or are only touching metadata.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)
custom_lead_fields	object	no*	Same contract as on client_create
client_context	object	no*	Same contract as on client_create
confirm	boolean	no	false (default) previews; true applies

*At least one of the two buckets must be non-empty.

client_delete

Delete a client and all associated chats.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)

client_list_notes / client_get_note / client_create_note / client_update_note / client_delete_note

Free-text notes on the lead card.

Tool	Params
client_list_notes	client_id (required), limit (default 20, max 100), offset
client_get_note	client_id, note_id (both required)
client_create_note	client_id, content (both required)
client_update_note	client_id, note_id, content (all required; content replaces the note)
client_delete_note	client_id, note_id (both required)

client_list_tasks / client_create_task / client_update_task / client_delete_task

To-dos on the lead card.

Tool	Params
client_list_tasks	client_id (required), limit (default 20, max 100), offset
client_create_task	client_id, title (required); description; priority (low, medium, high, urgent); due_date (RFC3339)
client_update_task	client_id, task_id (required); title; description; status (pending, in_progress, completed, cancelled); priority
client_delete_task	client_id, task_id (both required)

client_list_attachments / client_get_attachment

Read a client's attachment records (files, documents).

Tool	Params
client_list_attachments	client_id (required), limit (default 20, max 100), offset
client_get_attachment	client_id, attachment_id (both required)

client_create_attachment

Attach an existing file URL to a client. This creates an attachment record (metadata); it does not upload file bytes.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)
file_name	string	yes	Display file name
file_url	string	yes	Existing URL of the file; must be an absolute http(s) URL
file_size	integer	no	File size in bytes (non-negative)
file_type	string	no	MIME type
description	string	no	Description
folders	array of string	no	Document sections, e.g. internal, sent, received
metadata	object	no	Document context: source (origin, defaults to ai_agent), invoice_number, order_number, custom (string key/value map)

Notes: the server-owned origin fields (channel, chat, received time) and the send history are recorded automatically and cannot be set by the caller.

client_update_attachment

Update a client attachment's file metadata or referenced URL.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)
attachment_id	string	yes	The attachment ID
file_name	string	no	New display name (cannot be blanked)
file_url	string	no	New URL; absolute http(s) only
file_size	integer	no	New size in bytes; 0 resets the stored size
file_type	string	no	New MIME type (empty clears it)
description	string	no	New description (empty clears it)
folders	array of string	no	Replacement sections (empty array clears them)
metadata	object	no	Merged onto stored metadata; server-owned origin fields and send history are preserved

Notes: at least one field must be provided.

client_delete_attachment

Delete a client attachment record. Does not delete the file at its external URL.

Param	Type	Required	Description
client_id	string	yes	The client ID (UUID)
attachment_id	string	yes	The attachment ID

export_clients

Export clients (leads) to a CSV or JSON file uploaded to the static.mychatbot.app CDN. Returns a public download_url plus row_count. Use whenever the user asks to download, export, or back up leads — never paste large lists into chat. Hard cap: 200 000 rows.

Param	Type	Required	Description
format	string	no	csv (default) or json
columns	array of string	no	Defaults to id, full_name, email, phone_number, company_name, funnel_status, labels, pipeline_id, manager_id, created_at, updated_at, last_active. Also allowed: ad_id, ad_post_id, ad_title, crm_deal_id, crm_pipelines_card_id. Unknown columns error
funnel_status	string	no	Filter by funnel status
labels	string	no	Comma-separated labels
search	string	no	Search across name, email, phone
pipeline_id	string	no	Filter by pipeline ID
has_phone_number	boolean	no	Only clients with a phone (false ignored)
has_email	boolean	no	Only clients with an email (false ignored)
created_from / created_to	string	no	Bounds on created_at. RFC3339 or date-only YYYY-MM-DD (UTC start of day); a date-only created_to covers that entire day (UTC)
last_active_from / last_active_to	string	no	Bounds on the client's own last activity (clients.last_active), not chat activity. RFC3339 or date-only YYYY-MM-DD (UTC); a date-only last_active_to covers that entire day, so from=2026-07-25 to=2026-07-31 is the full week inclusive

Notes: the metadata blob (both custom-data buckets) and normalized email/phone are deliberately not exportable. Labels in CSV are joined with ;. The date bounds apply directly to the client rows, so filtered exports work on accounts of any size.

list_labels / label_create / label_delete

Labels (tags) for leads.

Tool	Params
list_labels	none
label_create	label_name (required)
label_delete	label_name (required) — also removes the label from every client that carries it

list_pipelines / get_pipeline

Tool	Params
list_pipelines	none — returns name, description, and default flag per pipeline
get_pipeline	pipeline_id (required) — returns the pipeline plus its funnel statuses (stages)

pipeline_create / pipeline_update / pipeline_delete

Tool	Params
pipeline_create	name (required), description — created non-default
pipeline_update	pipeline_id (required); name and/or description (at least one; empty strings can't clear)
pipeline_delete	pipeline_id (required) — rejected for the default pipeline, for pipelines that still have statuses, and for pipelines with assistants assigned

funnel_status_create / funnel_status_delete

Tool	Params
funnel_status_create	pipeline_id, status_name (required); color_index (optional UI color)
funnel_status_delete	pipeline_id, status_name (required) — no guard against deleting a status clients currently hold

Conversations (sales_conversations)

Read-only access to chats and their message history.

list_chats

List recent chats sorted by last_active descending (most recent first), max 100 per call: client name, channel, last active, unread count, operator-needed flag. A chat with communication_channel="Calls" is a phone call — its message history is the call transcript. Every filter is optional.

Param	Type	Required	Description
assistant_id	string	no	Filter by assistant ID
needs_operator	string	no	yes = only chats flagged for operator attention, no = only chats not needing one, any/omit = all
common_client_id	string	no	Filter by the unified client UUID (chats.common_client_id, = the lead's client_id from list_clients). NOT the per-channel id
external_client_id	string	no	Filter by the per-channel external client id (chats.client_id, e.g. a Telegram user id). In an app URL /chats/<external_client_id>/<page_id> this is the FIRST path segment
page_id	string	no	Filter by the channel page id — the SECOND segment of a pasted /chats/... app URL. Pair with external_client_id to resolve a chat from a URL
last_active_before	string	no	Only chats with last_active strictly before this time. RFC3339 (fractional seconds allowed) or date-only YYYY-MM-DD (= UTC start of day). Half of the pagination cursor — see below
last_active_after	string	no	Only chats with last_active strictly after this time. RFC3339 or date-only YYYY-MM-DD (= UTC start of day). Lower bound of a date window
before_id	number	no	The id half of the pagination cursor; only valid together with last_active_before. When both are set the bound is "older than that timestamp, or same timestamp with a smaller id"
limit	number	no	Max results (default 20, max 100)

Returns {chats: [...], count, next_last_active_before, next_before_id}. next_last_active_before is a full-precision RFC3339 timestamp (sub-second fraction included); next_before_id is the last row's chat id. Both are present whenever the page contains at least one chat with a known last_active.

Pagination: there is no offset — page by keyset. Pass both cursor fields from the previous response — next_last_active_before as last_active_before and next_before_id as before_id — and call again; repeat until a page comes back with fewer than limit rows. Always use the returned cursor fields — do not rebuild the cursor from a chat row's displayed last_active: that string is truncated to whole seconds, and feeding it back into the strict before-bound would skip same-second chats. Passing last_active_before alone (without before_id) also works for plain date-window queries. Both bounds are strict and a date-only value always means UTC start of day, so for the window 2026-07-25…2026-07-31 inclusive pass last_active_after=2026-07-25 and last_active_before=2026-08-01 (day + 1). Combine both bounds to fetch a specific date window.

get_chat

Get detailed info about a specific chat including metadata, follow-up state, and channel info. The response distinguishes three ids: id (the canonical chat id), client_id (per-channel external id), and common_client_id (the lead's UUID) — do not conflate them.

Param	Type	Required	Description
chat_id	string	yes	The chats.id integer returned by list_chats (e.g. 568507). NOT page_id or any channel-external id

get_chat_messages

Read a chat's message history: the last N messages with role, content, and timestamp. For Calls chats this is the call transcript — there is no separate transcript endpoint. Tool calls are collapsed to a list of tool names.

Param	Type	Required	Description
chat_id	string	yes	The chats.id integer returned by list_chats
limit	number	no	Number of recent messages (default 50, max 200)

Channels (sales_channels)

Connected messaging channels and their setup.

list_channels

List all connected channels (Telegram, WhatsApp, Instagram, …) with their status. Credentials are stripped; rows include communication_channel, page_id, description, assistant_id, is_on, created_at, and connection_type.

Param	Type	Required	Description
assistant_id	string	no	Filter by assistant ID

channel_toggle

Turn a channel on or off.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
page_id	string	yes	The channel page ID
communication_channel	string	yes	Channel type (telegram, whatsapp, …)
is_on	boolean	yes	True to enable, false to disable

channel_get_config_link

Generate a link to the web UI channel configuration page. Channels need the web UI for auth setup.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID
channel_type	string	yes	telegram, whatsapp, instagram, facebook, email, sms, widget, calls, olx, tiktok, chat2desk, personal_whatsapp

create_calls_channel_sdk

Create a new voice Calls channel with a WebSDK connection for an assistant. Returns the agent_id and embed snippets (HTML and npm) for a website. Created with sensible defaults (10-minute max call duration). One WebSDK Calls channel per assistant. Note: WebSDK channels can't place outbound calls — outbound_call needs a Twilio/SIP-trunk Calls channel.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID to attach the calls channel to
first_message	string	no	Greeting the agent says when a call starts; defaults to the assistant's welcome message
language	string	no	Language code (e.g. en, ru, uk); default en
voice_id	string	no	Voice ID; defaults to the platform default voice

create_website_widget

Create a Website Widget (chat bubble) channel for an assistant and turn it on. Returns the ready-to-paste embed snippet plus a hosted HTML page URL. Idempotent: reusing the same widget_id for the same assistant refreshes the config and returns the embed; a widget_id owned by a different assistant errors.

Param	Type	Required	Description
assistant_id	string	yes	The assistant ID to connect the widget to
widget_id	string	yes	Short unique identifier, no spaces (e.g. main-site); becomes the channel's page_id and shows in Active Chats
welcome_text	string	no	Heading above the contact options in the widget home tab
pop_up_text	string	no	Text shown in the bubble a few seconds after page load
website_url	string	no	Your site URL, used for previewing the widget in context
logo	string	no	Public URL to a brand logo image (~45×45)
color	string	no	Primary widget color hex (default #6F52E0)
language	string	no	Widget UI language: en, ru, or ua (default en)

Outreach & Follow-ups (sales_outreach)

Follow-up automations, immediate outreach campaigns, and single one-off calls and messages.

Which outreach tool?

• One lead, one message → send_one_off_message (any non-Calls channel)
• One lead, one voice call → outbound_call
• Many leads (campaign) → immediate_outreach_preview_audience, then immediate_outreach_create
• Recurring, condition-based chasing → follow-up automations (follow_up_*), best edited in the app UI

list_follow_ups

List follow-up automations (outreach campaigns).

Param	Type	Required	Description
type	string	no	postponed, immediate, or trigger
status	string	no	draft, active, paused, or done

get_follow_up

Get detailed info about a follow-up including steps, filters, and execution stats.

Param	Type	Required	Description
follow_up_id	string	yes	The follow-up ID

follow_up_create

Create a new postponed follow-up automation. It starts as a draft; steps are edited in the app UI.

Param	Type	Required	Description
name	string	yes	Follow-up name
target_status_name	string	no	Target funnel status for the audience
target_labels	array of string	no	Target labels for the audience (matched with OR)

follow_up_update

Update a follow-up's name, status, or targeting criteria. Empty strings are treated as "not provided".

Param	Type	Required	Description
follow_up_id	string	yes	The follow-up ID
name	string	no	New name
status	string	no	New status: draft, active, paused
target_status_name	string	no	Target funnel status
target_labels	array of string	no	Target labels

follow_up_delete

Delete a follow-up automation.

Param	Type	Required	Description
follow_up_id	string	yes	The follow-up ID

immediate_outreach_create

Create and schedule an immediate outreach campaign. Returns the matched audience count. Use immediate_outreach_preview_audience first to check the audience size. The campaign is created as scheduled immediately — there is no draft step on this path.

Param	Type	Required	Description
name	string	yes	Campaign name
client_source	string	yes	Audience source: withChats, allClients, or withoutChats
outreach_channels	array of string	yes	Channels to send through, format ChannelType__AssistantID (e.g. Email__123, WhatsAppBusiness__123). ChannelType is the exact communication_channel value shown by list_channels
schedule_mode	string	yes	now (runs in ~3 min) or later (requires schedule_run_at)
schedule_run_at	string	no	ISO datetime for the scheduled send (required when schedule_mode is later)
instructions	string	no	AI prompt for generating the outreach message
custom_message	string	no	Static message to send (used when use_custom_message is true)
use_custom_message	boolean	no	If true, send custom_message verbatim; if false, compose with AI from instructions
email_subject	string	no	Subject line for the outreach email; requires an Email channel in outreach_channels. Falls back to the Email integration's custom subject or an auto-generated one
email_attachments	array	no	Files to attach to every outreach email; requires an Email channel in outreach_channels. Each entry is {url, name} (name optional, derived from the URL) — bare URL strings are also accepted. All files normally arrive on one email (Gmail; Outlook and rare fallback cases deliver one email per file instead). On a mixed-channel campaign the non-Email channels deliver the same files as media/links
instruction_attachments	array of string	no	URLs appended to every AI-composed message (use_custom_message=false); delivered as attachments/media where the channel supports it
custom_message_attachments	array of string	no	URLs appended to custom_message (use_custom_message=true); same delivery
send_to_all_emails	boolean	no	Cc each lead's additional stored addresses (from the extra-emails custom field configured on the Email channel); requires an Email channel in outreach_channels — for invoices that must also reach accounting
omit_core_instructions	boolean	no	Omit the assistant's core instructions when generating the message
statuses	array of string	no	Filter audience by funnel statuses
include_no_status	boolean	no	Include clients with no funnel status
labels	array of string	no	Filter audience by labels
labels_operator	string	no	or (any label) or and (all labels)
include_no_labels	boolean	no	Include clients with no labels
manager_ids	array of string	no	Filter by assigned manager IDs
has_phone_number	boolean	no	Only clients with a phone number
has_email	boolean	no	Only clients with an email
last_active_cutoff_days	integer	no	Activity window in days for the withChats source (default 7)
audience_limit	integer	no	Max recipients (0 = unlimited)
interval_seconds	integer	no	Rate-limit window in seconds (e.g. 3600 = 1 hour)
chats_per_interval	integer	no	Max chats per rate-limit window
send_delay_seconds	integer	no	Delay between messages in seconds (default 7)

Notes: when the message is AI-composed, the assistant sees the full lead context — profile fields, both custom-data buckets, notes, tasks, and attachment names — so instructions like "mention their open invoice" work.

immediate_outreach_update_status

Pause, resume, or reset an immediate outreach campaign.

Param	Type	Required	Description
follow_up_id	string	yes	The immediate outreach follow-up ID
status	string	yes	user_paused to pause, scheduled to resume, draft to reset (clears all progress and stats)

immediate_outreach_preview_audience

Preview the matched audience count for an immediate outreach without creating it. Returns matched_count, missing_count (clients lacking the required contact info for the chosen channels), and a 5-lead sample.

Param	Type	Required	Description
client_source	string	yes	withChats, allClients, or withoutChats
statuses	array of string	no	Filter by funnel statuses
include_no_status	boolean	no	Include clients with no funnel status
labels	array of string	no	Filter by labels
labels_operator	string	no	or or and
include_no_labels	boolean	no	Include clients with no labels
manager_ids	array of string	no	Filter by manager IDs
has_phone_number	boolean	no	Only clients with a phone number
has_email	boolean	no	Only clients with an email
last_active_cutoff_days	integer	no	Activity window in days (default 7)
audience_limit	integer	no	Max recipients (0 = unlimited)

outbound_call

Initiate a single outbound voice call to a specific lead via a Twilio- or SIP-trunk-backed Calls channel. For multi-recipient call campaigns use immediate_outreach_create. WebSDK Calls channels (the kind create_calls_channel_sdk makes) can't be used — they need a browser to start the call. Calls are real and immediate: confirm the recipient and opening line with the user first. Returns the conversation id; the transcript lands on the chat record after the call.

Param	Type	Required	Description
client_id	string	yes	The lead's UUID, copied verbatim from a list_clients/get_client result. The lead must have a phone number on file
first_message	string	yes	The literal opening line the AI agent says when the call connects — the lead will hear it
assistant_id	string	no	Disambiguates when more than one assistant has a Calls channel; auto-picked when only one outbound-capable channel exists
page_id	string	no	Specific Calls channel page_id, when an assistant has several
manager	string	no	Manager attribution string

Notes: the voice agent receives the lead's full context on the call — profile, both custom-data buckets, notes, and tasks.

send_one_off_message

Send a single ad-hoc message to a specific lead through any connected non-Calls channel (WhatsApp, Telegram, Email, Instagram, Viber, …). For voice use outbound_call; for campaigns use immediate_outreach_create. The message is written to the lead's chat history like a normal AI reply. Messages are real and immediate: confirm recipient, channel, and text with the user first. If unsure which channel to use, call list_channels.

Param	Type	Required	Description
client_id	string	yes	The lead's UUID, copied verbatim from a list_clients/get_client result
assistant_id	string	yes	The assistant whose identity owns this message
communication_channel	string	yes	WhatsApp, WhatsAppBusiness, Telegram, TelegramAccount, PersonalWhatsApp, Viber, EChatViber, EChatTelegram, Instagram, Messenger, Email, SwWidget, OcWidget, MCBWebhooks, Chat2Desk, TikTok, OLXAccount, SMS, Ringostat, UniTalk. Calls is rejected — use outbound_call
message	string	yes	Plain-text message to send
subject	string	no	Email subject line (Email only)
to	array of string	no	Email only: primary recipients (max 20). Replaces the lead's own address — for reaching e.g. a billing address. Defaults to the lead's email. Outlook accepts only one To; use cc for the rest
include_client	boolean	no	Email only: with to, also add the lead's own address as the first To recipient
cc	array of string	no	Email only: Cc addresses (max 20)
include_all_emails	boolean	no	Email only: Cc every address stored on the lead's extra-emails field (configured on the Email channel) without having to know them
bcc	array of string	no	Email only: blind copies (max 20)
attachments	array of string	no	Public HTTP(S) URLs of files to send; multiple URLs supported. On Email each file becomes a real attachment, and all files normally arrive on one email (Gmail; Outlook and rare fallback cases deliver one email per file instead); on messaging channels files are delivered as media where supported
include_documents	boolean	no	Email only: staple the lead's card documents (up to 50) to the email. URLs are read server-side — the agent never sees them. Each stapled document's send history is updated
reply_to_message_id	string	no	ID of the message being replied to (threaded replies on supported channels)
manager	string	no	Manager attribution string
page_id	string	no	Specific channel page_id; auto-resolved when the assistant has exactly one channel of that type

Notes: to/cc/bcc on any non-Email channel is a hard error, not a silent drop; invalid addresses are hard errors too. Recipient resolution: the lead's email is the default To; to replaces it; include_client re-adds the lead; duplicates resolve To > Cc > Bcc. A lead with no email can still be mailed by passing to. The response echoes the real recipients, and they are also recorded in the chat history.

Knowledge Base (sales_knowledge)

FAQ knowledge bases, product feeds, and manually managed product catalogs. The knowledge_base parameter is a group name: use an existing one to add an integration to that group, or a new unique name to start one. Caps: max 3 Product Feed and 3 Products integrations per knowledge base.

create_faq_knowledge_base

Create a new FAQ knowledge base integration, optionally seeded with entries.

Param	Type	Required	Description
knowledge_base	string	yes	Knowledge base group name
name	string	yes	Human-readable name (e.g. Shipping FAQ)
language	string	no	Content language (english, russian, spanish, …); default english
entries	array	no	Initial entries; each is {id, question, answer} (id used for diffing on updates). Can be added later via update_faq_knowledge_base_entries

Notes: seeded entries are indexed synchronously; on indexing failure the integration still exists and the response reports created_but_indexing_failed.

list_faq_knowledge_base_entries

List all entries in a FAQ knowledge base integration: IDs, questions, answers.

Param	Type	Required	Description
integration_id	string	yes	The FAQ integration ID

update_faq_knowledge_base_entries

Modify entries in a FAQ knowledge base. Use any combination of the three operations; the backend reads current entries, applies changes (remove → update → add), re-uploads, and re-indexes.

Param	Type	Required	Description
integration_id	string	yes	The FAQ integration ID
add	array	no	New entries {id, question, answer}; an id that already exists is treated as an update
update	array	no	Existing entries matched by id; provide only the fields to change (question and/or answer)
remove	array of string	no	IDs of entries to delete

Notes: updates are serialized per integration — a concurrent update errors with "another update to this knowledge base is already in progress — retry in a moment". At least one effective change is required.

delete_faq_knowledge_base

Delete a FAQ knowledge base integration and all its indexed data. Irreversible.

Param	Type	Required	Description
integration_id	string	yes	The FAQ integration ID

create_product_feed_integration

Create a Product Feed integration that indexes products from a feed URL for semantic search (JSON, XML, Google Shopping, YML, …). Asynchronous — returns processing immediately; check status with get_integration.

Param	Type	Required	Description
knowledge_base	string	yes	Knowledge base group name
feed_url	string	yes	Publicly accessible feed URL (http/https)
language	string	yes	Content language
name	string	no	Unique name within the knowledge base; lowercase a–z and underscores only, max 20 chars
index_images	boolean	no	Index product images for visual search (slower); default false

create_products_integration

Create a Products integration — a manually managed product catalog, optionally seeded. Products can carry arbitrary attributes.

Param	Type	Required	Description
knowledge_base	string	yes	Knowledge base group name
name	string	yes	Catalog name (e.g. Summer Collection)
language	string	no	Content language; default english
products	array	no	Initial products; each object needs name, all other keys are arbitrary attributes. For image indexing use image_link, image_url, additional_images, or any key containing image/photo/picture/thumbnail/gallery/media
index_images	boolean	no	Index product images for visual search; default false

Notes: product ids are auto-generated when missing.

list_products

List all products in a Products integration with all attributes.

Param	Type	Required	Description
integration_id	string	yes	The Products catalog integration ID

update_products

Modify products in a Products integration: any combination of add / update / remove, applied in the order remove → update → add, then re-indexed.

Param	Type	Required	Description
integration_id	string	yes	The Products catalog integration ID
add	array of object	no	New products; each must have name, other keys arbitrary
update	array of object	no	Existing products matched by id; only provided fields are merged
remove	array of string	no	Product IDs to delete

Notes: same per-integration serialization as FAQ updates; at least one effective change required.

delete_products_integration

Delete a Products integration and all its indexed data. Irreversible.

Param	Type	Required	Description
integration_id	string	yes	The Products catalog integration ID

Integrations (sales_integrations)

Read-only view of the account's integrations.

list_integrations

List all integrations for this account: CRMs, knowledge bases, MCPs, automations. Returns a projection per row (id, integration, type, knowledge-base fields).

Param	Type	Required	Description
type	string	no	Filter by integration type; knowledge_base filters on the knowledge-base flag

get_integration

Get detailed info about a specific integration including metadata and configuration. Sensitive fields (secrets, passwords, headers) are stripped.

Param	Type	Required	Description
integration_id	string	yes	The integration ID

get_integration_config_link

Generate a link to the web UI integration configuration page.

Param	Type	Required	Description
integration_id	string	yes	The integration ID

Account & Usage (sales_account)

get_account_summary

High-level account summary: totals for assistants, clients, chats, integrations, follow-ups, pipelines, and orders, plus a business_profile (company name + website). No parameters.

get_subscription_info

Current subscription plan: tokens left, plan name, trial flag, expiry dates. Returns {"message": "no subscription found"} when there is no subscription. No parameters.

get_token_usage

Token usage statistics: prompt and completion tokens with per-model and per-assistant breakdowns.

Param	Type	Required	Description
since_date	string	no	Start date (RFC3339 or YYYY-MM-DD)
to_date	string	no	End date (RFC3339 or YYYY-MM-DD)
assistant_id	string	no	Filter by assistant ID

get_usage_summary

Combined usage summary for a date range: token counts, order count, chat count, and client count. The response may include an errors map keyed by source when a sub-query fails — that counter is unreliable; re-fetch, often by narrowing the date range.

Param	Type	Required	Description
since_date	string	no	Start date — prefer RFC3339; plain YYYY-MM-DD is silently ignored by the client-count filter
to_date	string	no	End date — prefer RFC3339; plain YYYY-MM-DD is silently ignored by the chat- and client-count filters

Orders (sales_orders)

list_orders

List orders with optional filtering.

Param	Type	Required	Description
since_date	string	no	Start date (RFC3339 or YYYY-MM-DD)
to_date	string	no	End date (RFC3339 or YYYY-MM-DD)
client_id	string	no	Filter by client ID (channel-specific)
status	string	no	pending, awaiting_payment, paid, in_progress, completed, cancelled
source	string	no	native, spreadsheet, etc.
order_ref	string	no	Exact order reference (e.g. MCB-A7F3C2)
assistant_id	number	no	Filter by assistant/agent ID
limit	number	no	Max results (default 50, max 200)
offset	number	no	Offset for pagination

get_order

Full details of a single order.

Param	Type	Required	Description
order_ref	string	no*	Order reference (e.g. MCB-A7F3C2); takes precedence when both are given
order_id	number	no*	Numeric order ID

*One of the two is required. A missing order returns {"error": "Order not found"} as JSON.

get_order_stats

Order statistics: total count, total revenue, breakdown by channel and status. Revenue per order is total_amount, falling back to product_price × product_amount.

Param	Type	Required	Description
since_date	string	no	Start date (RFC3339 or YYYY-MM-DD)
to_date	string	no	End date (RFC3339 or YYYY-MM-DD)

delete_test_orders

Delete test orders that have no communication channel (created during testing, not from real conversations). Returns the deleted count. No parameters.

Calendar (sales_calendar)

All calendar tools require a Calendar integration on the account; without one they return {"error": "Calendar integration not found"} as JSON.

list_events

List calendar events.

Param	Type	Required	Description
since_date	string	no	Start date (RFC3339 or YYYY-MM-DD), matched against event start time
to_date	string	no	End date (RFC3339 or YYYY-MM-DD)
status	string	no	confirmed, completed, cancelled, no_show
staff_id	number	no	Filter by staff member ID
service_id	number	no	Filter by service ID
limit	number	no	Max results (default 50, max 200)
offset	number	no	Offset for pagination

get_event

Full details of a single event.

Param	Type	Required	Description
event_ref	string	yes	Event reference (e.g. EVT-B3F1D8). A missing event returns {"error": "Event not found"} as JSON

get_event_stats

Event statistics: total count, breakdown by status and staff.

Param	Type	Required	Description
since_date	string	no	Start date (RFC3339 or YYYY-MM-DD)
to_date	string	no	End date (RFC3339 or YYYY-MM-DD)

list_calendar_staff

List staff members configured for booking (id, name, role, color). No parameters.

list_calendar_services

List services configured for booking (id, name, duration, price, currency). No parameters.

Automations (sales_automations)

Read, diagnose, and configure the Lead Forms automation — the per-form rules that route Meta (Facebook/Instagram) Lead Gen submissions to an agent, as set up on Automations → Lead Forms. Connecting the Facebook page itself is OAuth and stays in the app; these tools manage what happens after leads arrive.

Two conventions specific to this area:

• Writes are a two-step confirm. Calling set_lead_form_mapping or remove_lead_form_mapping without confirm: true applies nothing — it returns a before/after preview to review (or show the user). Call again with confirm: true to apply.
• Writes fail closed. set_lead_form_mapping verifies the form exists on one of the account's own connected pages against the live list; if the social service is unreachable, the call errors and nothing changes.

set_lead_form_mapping also requires a plan that includes social account connections — the same entitlement as connecting the page. Removing a mapping works on any plan.

list_lead_forms

List the account's connected Facebook pages and each page's Meta Lead Gen forms, with whether each form already has a mapping. Use it to discover form ids before configuring.

Param	Type	Required	Description
social_account_id	string	no	One connected social account id (from a previous call). Absent = all connected Facebook accounts

Each form comes back with id, name, status, leads_count, and mapped (plus assistant_id and outreach_mode when mapped). A page whose Ads add-on is missing returns an empty form list with ads_addon_missing: true.

get_lead_forms_automation

The full automation config — every per-form mapping — plus a per-form diagnosis answering "why aren't this form's leads reaching anyone": form missing from every connected page, assistant deleted, no active channel of the chosen type for that assistant. No parameters.

Returns configured: false with guidance when the automation was never set up. When the social service is unreachable the stored config still comes back, with forms_verified: false instead of form-existence issues.

set_lead_form_mapping

Create or update the mapping for one form. Updating an existing mapping changes only the parameters you pass — everything else survives.

Param	Type	Required	Description
form_id	string	yes	Meta Lead Gen form id (from list_lead_forms)
assistant_id	string	on create	Assistant that handles this form's leads
outreach_mode	string	no	capture-and-outreach (default on create) — capture the lead AND message them. capture-only — capture into Contacts, send the person nothing
channels	string[]	in outreach mode	Outreach channels, e.g. ["Email", "TelegramAccount"]. Each must be an active connected channel of the assistant
agent_instruction	string	in outreach mode	What the assistant should do when it messages the lead (unless use_custom_message)
use_custom_message	boolean	no	Send custom_message verbatim instead of having the assistant compose the opener
custom_message	string	with use_custom_message	The verbatim first message
custom_email_subject	string	no	Email channel only: subject line
funnel_status	string	no	capture-only mode: funnel status (pipeline stage name) to drop captured leads into. Must not contain double quotes
notify_telegram_on_capture	boolean	no	capture-only mode: notify the assistant's Flight Control Telegram group on every captured lead
send_delay	string	no	Delay before sending, as a Go duration: "5m", "1h30m"
send_window_start / send_window_end	string	no	Daily send window, HH:MM (set together)
send_timezone	string	no	IANA timezone for the window, e.g. Europe/Kyiv
interval_seconds	number	no	Minimum seconds between sends to consecutive leads of this form
pipeline_id	number	no	Pipeline to drop this form's leads into
skip_chat_history	boolean	no	Don't write the form submission into the lead's chat history
form_name	string	no	Display-name override; defaults to the live form name
confirm	boolean	no	Absent/false = preview only. true = apply

Switching a mapping to outreach mode clears funnel_status and notify_telegram_on_capture (they only apply to capture-only routing) — same rule as the app editor.

remove_lead_form_mapping

Remove (disable) one form's mapping. Its leads are still captured into Contacts — capture is always-on — but no automation fires for them.

Param	Type	Required	Description
form_id	string	yes	Form id of the mapping to remove
confirm	boolean	no	Absent/false = preview only. true = apply

Testing & evals (sales_evals)

Saved eval scenarios (fixed lists of user turns, captured from real chats or written inline) plus eval runs that replay them against an assistant's current or candidate instructions and score answer stability. The workflow — capture, replay, A/B a prompt, measure consistency — is walked through in Testing & evals.

Conventions specific to this area:

• Ids are numeric. scenario_id and run_id are the numeric ids returned by the matching save/list/start tool; a JSON number or a numeric string both work.
• Eval traffic is free. Every turn a run executes is recorded as test-chat usage, never billed as customer messages.
• Runs are asynchronous. eval_run_start returns immediately; poll eval_run_get for progress and results. One queued-or-running run per account — a second start is rejected (not queued) with the active run's id.
• 30-turn cap. Scenarios and runs replay at most 30 user turns. Chat and test-chat sources with more turns are cut to the first 30 and flagged; longer inline messages lists are rejected.

eval_scenario_save

Save (or update, by name) an eval scenario: a fixed list of user messages to test an assistant against, replayable any number of times. Provide the user turns exactly one of three ways: messages (inline), from_chat_id (copy the user turns of a real chat), or from_test_chat_assistant_id (copy the user turns of that assistant's current test-chat session).

Param	Type	Required	Description
name	string	yes	Scenario name — the upsert key: saving again with the same name updates the scenario in place
description	string	no	What this scenario tests
assistant_id	string	no	Associate the scenario with an assistant (bookkeeping only — eval_run_start always names its assistant explicitly)
messages	string[]	one-of	The user turns, in order (max 30). Provide exactly one of messages, from_chat_id, from_test_chat_assistant_id
from_chat_id	string	one-of	Build the scenario from a real chat: its user turns become the messages, in order. Use the chat id from list_chats
from_test_chat_assistant_id	string	one-of	Build the scenario from the assistant's current test-chat session history (the one test_chat_send writes)
reference	string[]	no	Expected assistant answers, aligned per turn (item i = expected answer to turn i; use "" for turns without a reference). Enables the vs_reference similarity score in runs

Notes: only user turns are captured from a chat — activity events and platform notes are skipped, and empty turns dropped. A chat or test-chat source with more than 30 user turns is cut to the first 30, and the response carries turns_truncated: true plus a note; an inline messages list over 30 is rejected instead. reference may be shorter than the turn list but not longer. Returns {scenario_id, name, turns, updated} — updated: true means an existing scenario of that name was overwritten.

eval_scenario_list

List saved eval scenarios: scenario_id, name, description, turns (count), has_reference, timestamps, and assistant_id when one was associated. No parameters.

eval_scenario_get

Get one saved scenario in full: the user turns (messages, each {content}) and the reference answers when set.

Param	Type	Required	Description
scenario_id	number	yes	The scenario id from eval_scenario_list or eval_scenario_save

eval_scenario_delete

Delete a saved eval scenario. Past runs that used it keep their transcripts (the run's scenario_id link is cleared, results stay readable).

Param	Type	Required	Description
scenario_id	number	yes	The scenario id from eval_scenario_list

eval_run_start

Start an eval run: replay a conversation's user turns against an assistant and record every response and tool call. With the defaults (runs: 1, judge: "none") this is a plain replay — one pass, transcript only. The run executes in the background — poll eval_run_get.

Param	Type	Required	Description
assistant_id	string	yes	The assistant to evaluate
scenario_id	number	one-of	Run a saved scenario. Provide exactly one of scenario_id, source_chat_id, messages
source_chat_id	string	one-of	Replay a real chat's user turns directly (activity events and platform notes skipped). Use the chat id from list_chats
messages	string[]	one-of	Inline user turns, in order (max 30)
runs	number	no	Iterations over the turns (default 1, max 5). Each iteration is an independent conversation from a clean history
judge	string	no	none (default): transcripts only. similarity: deterministic token-overlap scoring — per-turn consistency across iterations (needs runs ≥ 2) and per-turn score vs the scenario's reference answers (when set). No extra LLM cost
instruction_override	string	no	Candidate instruction text to test instead of the assistant's saved instructions. The live assistant is not modified. Omit to run the assistant as currently configured
skills_override	string[]	no	Explicit skill selection for the run: skill slugs from assistant_list_skills. An empty array runs with no skills. Omit to use the assistant's configured skills

Notes: exactly one source is required. A slug in skills_override the assistant doesn't have is an error listing the available slugs. If a run is already queued or running for the account the call fails with that run's id — poll or eval_run_cancel it first. Returns {run_id, status: "queued", turns, runs, judge}. Runs have a 15-minute wall-clock deadline; a run that exceeds it flips to error with completed turns retained.

eval_run_get

Get an eval run's status and results. While the run is executing (status running) it returns the turns completed so far — poll it to watch progress.

Param	Type	Required	Description
run_id	number	yes	The run id from eval_run_start
include_tool_details	boolean	no	false (default): tool calls carry name + result preview only. true: include each call's arguments too

Returns JSON (abbreviated):

{
  "run_id": 41,
  "assistant_id": 42,
  "status": "done",
  "runs": 3,
  "judge": "similarity",
  "source": { "type": "scenario", "scenario_id": 17, "turns": 3 },
  "instruction_override_used": true,
  "iterations": [
    {
      "iteration": 1,
      "turns": [
        {
          "turn": 1,
          "user_message": "how much is delivery?",
          "response": "Delivery is 80 UAH…",
          "tool_calls": [
            { "name": "get_faq", "result_preview": "…", "result_bytes": 412 }
          ]
        }
      ]
    }
  ],
  "metrics": {
    "judge": "similarity",
    "per_turn": [ { "turn": 1, "consistency": 0.88, "vs_reference": 0.83 } ],
    "overall_consistency": 0.86,
    "overall_vs_reference": 0.83
  },
  "created_at": "2026-08-07T09:14:02Z",
  "finished_at": "2026-08-07T09:16:47Z"
}

Notes: status is one of queued, running, done, error, cancelled; while running the response carries a note that results are partial. instruction_override_used: true appears when the run tested candidate text (the text itself is not echoed); skills_override echoes the pinned slug list when one was given. Metrics appear only when judge: "similarity" was requested: scores are 0–1 (higher = more similar), consistency needs ≥ 2 iterations, vs_reference needs a non-empty reference for the turn, and the overall_* values average the defined per-turn scores. Failed turns and iterations carry an error field. Oversized results (~2 MB cap) are trimmed with results_truncated: true and a truncation_note — never silently. A failed run has status error and a top-level error message.

eval_run_cancel

Cancel a queued or running eval run (best effort — the current turn finishes first). Completed turns stay available via eval_run_get. Cancelling an already-finished run is a no-op that reports the final status.

Param	Type	Required	Description
run_id	number	yes	The run id from eval_run_start

See also

• Testing & evals — the capture → replay → A/B → stability workflow behind the sales_evals tools, with a worked example
• MCP & connectors — connecting Claude Code / Cursor to these tools
• Connectors cheat sheet — the app walkthrough and per-agent toggles
• Working with the Sales Platform — the operator/runtime split and outreach hand-off
• Tools & toggles — the single Sales Platform tools toggle