Sales tools reference

For a short task-to-domain index, use Sales tools by domain. This page remains the canonical parameter-level reference for every Sales-Management MCP tool and is intentionally complete for Claude, Codex, and other MCP clients.

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, Codex, or Cursor sees when you connect a ?domain= server. See MCP & connectors for client setup and Connectors 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/scan_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). Offset tools return live interactive pages; use scan_clients and export_chats immutable keyset cursors for exhaustive batches. list_chats also pages by keyset for recent-chat browsing.

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 blank assistant (sales bot) for this account. It is created switched on and attached to the account's default pipeline when one exists, but it does not copy skills, integrations, knowledge, or follow-ups.

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_clone

Create a full independent copy of an existing assistant: instructions, welcome message, language/style, knowledge-base attachment, skills, follow-ups, integrations, and toolkit settings. Integration and follow-up rows receive new IDs; channels are not copied.

Param	Type	Required	Description
source_assistant_id	string	yes	ID of the assistant to copy
bot_name	string	no	Name for the copy; omit to derive it from the source

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 one bounded, live page of clients (leads/customers), with filters. The response is {clients, count, total, limit, offset}. Start with offset=0, add count to the offset after each call, and stop when offset + count >= total (or when count < limit). An explicit zero or negative limit does not mean "all"; it is normalized to the default 20. The maximum is 100.

Offset paging is appropriate for interactive lookup, not an exhaustive batch: creates, deletes, changing filters, and activity-based reordering can shift rows between calls. Use scan_clients for complete large-data traversal.

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

scan_clients

Read one bounded, account-wide page of clients for exhaustive caller-side batch processing. Rows are ordered by immutable client UUID ascending. The response is {clients, count, limit, next_after_id}. Pass next_after_id back as after_id and stop when count < limit.

Each row is a compact batch projection: id, name, email, phone, company, pipeline/status, labels, manager, created time, and last activity. Use get_client only for selected records that require full metadata.

The exact row fields are id, full_name, email, phone_number, company_name, pipeline_id, funnel_status, labels, manager_id, created_at, and last_active. next_after_id is present on every non-empty page and absent on the terminal empty page.

There is no offset, server-computed total, sort, search, or server-side filter. Apply pipeline, status, labels, contact details, and other mutable conditions in the caller as each row arrives. New or deleted records cannot shift an existing unvisited row behind an offset.

Param	Type	Required	Description
limit	number	no	Max results (default 20, max 100)
after_id	string	no	Immutable client UUID cursor. Pass next_after_id from the prior response; omit on the first call

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
assistant_id	number	no	The Sales assistant that will work this lead. Shown on the lead as its Sales agent
channel	string	no	The channel that assistant will use, as the platform is named on the Channels page (Instagram, Messenger, TelegramAccount, EChatViber, Email, Calls, …). Only accepted together with assistant_id

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_notes returns {notes, count, total, limit, offset}. This is a live interactive page; inserts or deletes between offset calls can shift rows.

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_tasks returns {tasks, count, total, limit, offset}. This is a live interactive page; inserts or deletes between offset calls can shift rows.

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_list_attachments returns {attachments, count, total, limit, offset}. This is a live interactive page; inserts or deletes between offset calls can shift rows.

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)

export_chats

Read one bounded page of conversations plus a bounded message window for each chat. This is the primitive for caller-side export and deterministic batch processing: it returns structured data, not a job id, download URL, CSV, or uploaded file. The Claude/Codex session or routine skill owns the page loop, checkpointing, transformations, chosen total, file format, and final upload.

Each call selects at most 100 chats, ordered by immutable chat_id desc, and performs one bulk message read for exactly those conversation keys. Per-chat counters cover the complete conversation even when only the first or last N messages are included. Human operator replies are distinguished from bot replies using the platform's stored Manager: tag.

Param	Type	Required	Description
limit	number	no	Chats in this page (default 20, max 100)
messages_per_chat	number	no	Messages included per chat (default 10, max 50, 0 = counters only)
max_message_chars	number	no	Unicode characters returned per message (default 1,000, max 4,000). A larger value may require a smaller page/window
message_selection	string	no	last (default) or first. Messages are oldest-to-newest inside the selected window
before_id	string or number	no	Immutable chat-id page cursor. Pass next_before_id from the prior response; omit on the first call

The response is {chats, count, limit, messages_per_chat, max_message_chars, message_selection, next_before_id}. next_before_id is present on every non-empty page and absent on the terminal empty page. Each chat carries chat_id, assistant_id, common_client_id, external_client_id, page_id, name, username, phone, channel, chat_link, last_active, needs_operator, total_messages, operator_messages, operators, first_message_at, last_message_at, and a messages array. Optional identifiers and display fields can be absent when the stored chat has no value. Timestamps retain full RFC3339 precision.

Each message carries at, id, role, operator, and text; id and operator are omitted when unavailable or inapplicable. A shortened message also carries text_truncated: true and text_full_chars. Message text defaults to at most 1,000 Unicode characters per value and can be raised to 4,000. To prevent a row-bounded request from becoming an unbounded payload, limit × messages_per_chat × max_message_chars must not exceed 1,000,000. Reduce page size or message window when raising the text cap. Image/media turns count as messages: their caption is preserved and the text contains a safe [image], [N images], or [media] placeholder. Private or signed media URLs are deliberately not returned.

There is intentionally no offset. A chat's activity time can change while a large export is running, so export_chats does not order or page by activity. It uses immutable descending chat ids: a chat that receives a new message during the traversal cannot jump across the page cursor and disappear. For every next call, copy the returned next_before_id unchanged:

cursor = {}
rows = []

repeat:
  page = export_chats(limit=100, messages_per_chat=10,
                      message_selection="first", ...cursor)
  append page.chats to rows (or write/checkpoint this page immediately)
  if page.count < page.limit: stop
  cursor = {before_id: page.next_before_id}

The sweep is deliberately account-wide. Assistant/client assignment, page, channel, full-precision RFC3339 last_active, and needs_operator are returned on every chat but are not server-side filters on this multi-call tool: each can change while a large sweep runs, and reapplying membership predicates to every database page could make a matching unvisited chat disappear. Apply conditions in the caller as each row arrives. Passing one of those old filter arguments fails with a teaching error instead of being silently ignored. Use list_chats when live server-side filtering is more important than exhaustive batch membership.

For 7,000 chats this is 70 bounded data pages plus one terminal empty page when the total is an exact multiple of 100—not one 7,000-chat server job and not 7,000 get_chat_messages calls. Use common_client_id to join richer client fields from separately keyset-paginated scan_clients results. The caller must still escape spreadsheet formulas when it writes CSV and choose where to upload the finished file; export_chats itself creates no public object.

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. The boolean immediate_outreach_capable is true only for an enabled channel type accepted by immediate_outreach_create; construct its channel ID as <communication_channel>__<assistant_id>.

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

delete_channel

Disconnect one channel from an assistant and stop new message delivery. Existing conversations remain.

Param	Type	Required	Description
assistant_id	string	yes	Assistant that owns the channel
channel_type	string	yes	Exact channel type reported by list_channels

delete_assistant

Permanently delete a Sales assistant, including channels, skills, tasks, and—if explicitly allowed—its customer conversations. The tool refuses an assistant with conversations unless delete_conversations is true.

Param	Type	Required	Description
assistant_id	string	yes	Assistant to delete
delete_conversations	boolean	no	Must be true to delete an assistant that has customer conversations

connect_telegram

Validate a BotFather token, connect that Telegram bot to an assistant, register the webhook, and turn the channel on. Reconnecting the same bot to the same assistant refreshes its token. Treat bot_token as a secret.

Param	Type	Required	Description
assistant_id	string	yes	Assistant that should answer on the bot
bot_token	string	yes	Full Telegram bot token from BotFather
drop_pending_updates	boolean	no	Ignore messages accumulated while offline; default false

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	no	Short unique identifier, no spaces (e.g. main-site); omit for the assistant's default widget
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 with a messaging channel
• One lead, one voice call → outbound_call
• One lead, one operator call → send_one_off_message with Ringostat, UniTalk, or Binotel (legacy tool naming; its message is not delivered)
• Many leads (campaign) → immediate_outreach_preview_audience, then immediate_outreach_create
• Recurring, condition-based chasing → create and publish a complete postponed sequence with follow_up_*

Postponed and immediate outreach have deliberately different safety models. A postponed sequence is created as a disabled draft; inspect it with get_follow_up, then publish it explicitly. immediate_outreach_create schedules real messages or calls immediately and has no draft stage. Preview and obtain explicit approval before invoking it.

The tables below mirror the MCP JSON schemas. integer means a whole JSON number; numeric database IDs documented as string must be positive decimal strings such as "42". Unknown fields and values of the wrong JSON type are rejected. The connected MCP tool schema remains authoritative if it is newer than this page.

Postponed and immediate follow-up validation: names and targeting strings are trimmed, must be valid UTF-8, and reject unsafe control characters; IDs and list entries must not be duplicated. Their public-file inputs accept only HTTP(S) URLs up to 4,096 characters, without embedded credentials or local/private hosts. Their text fields reject NUL characters, and email subjects reject line breaks. Dates use the formats stated per field rather than locale-formatted dates.

list_follow_ups

List follow-up automations (outreach campaigns).

Param	Type	Required	Description
type	string	no	postponed, immediate, or trigger
status	string	no	Exact stored status, maximum 50 characters. Common values are draft/live for postponed and scheduled/running/user_paused/completed/failed for immediate
limit	integer	no	Page size, 1–100; default 20
offset	integer	no	Rows to skip, minimum 0. Pass next_offset from the previous response

Returns {follow_ups, count, offset} and includes next_offset only when another page exists. follow_ups is always an array, including on an empty page.

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	Positive decimal follow-up ID, for example "42"

Returns the complete stored record, including canonical steps, targeting, schedule, metadata, status, and execution fields.

follow_up_create

Create a complete postponed follow-up automation. It always starts as a disabled draft, even when every step is supplied. The tool accepts an ordered step list—not raw node IDs, edges, positions, or conditions—and the server generates the editor/runtime graph.

Param	Type	Required	Description
name	string	yes	Follow-up name, 1–200 characters
target_status_name	string	no	Target funnel status for the audience, maximum 200 characters; empty means every status
target_labels	array of string	no	Up to 100 unique, non-empty labels; each is at most 200 characters
target_labels_operator	string	no	or (default) or and
steps	array of object	no	Complete ordered sequence (maximum 100). See Ordered step object
schedule	object	no	Optional working-hours schedule. See Working-hours object
generate_email_subject	boolean	no	Generate subjects with AI instead of using each step's email_subject

Returns the complete stored draft record and its generated ID. Postponed pipeline targeting is not accepted by this MCP schema: do not pass target_pipeline_ids or pipeline_ids. Use status/label targeting, or configure any unsupported condition in the app.

Ordered step object

Field	Type	Required	Description
name	string	yes	Builder label (1–200 characters)
delay_seconds	integer	no	Continued silence before this step, 0–31,622,400 seconds. On the first step this is the entry delay; later it is measured after the preceding step
chat_depth	integer	no	Conversation history depth: 1–10, 20, or 100; default 10
instructions	string	conditional	AI composition instruction, maximum 20,000 characters. Required before publish when use_custom_message=false
use_custom_message	boolean	no	Send custom_message verbatim instead of composing with AI
custom_message	string	conditional	Static message, maximum 20,000 characters. Required before publish when use_custom_message=true
email_subject	string	no	Email subject, maximum 998 characters; line breaks are rejected
attachments	array of string	no	Up to 10 unique public HTTP(S) URLs for the AI-composed message; each is at most 4,096 characters
custom_message_attachments	array of string	no	Up to 10 unique public HTTP(S) URLs for the custom message; each is at most 4,096 characters
trigger_on_delivery_failed	boolean	no	Run an alternative AI instruction if every delivery channel fails
delivery_failed_prompt	string	conditional	Alternative instruction, maximum 20,000 characters; required when trigger_on_delivery_failed=true

Drafts may have no steps or incomplete message content. Publishing validates that the sequence has at least one step and that every step has the content required by its message mode.

Working-hours object

schedule is {timezone, days}. timezone is an IANA name such as Europe/Kyiv. days must contain all seven case-sensitive keys—Monday through Sunday—and each value is {start, end}. Use HH:MM 24-hour values for an active day and empty strings for a day off. At least one day must be active; overnight windows such as 22:00 → 06:00 are accepted.

Field	Type	Required	Description
timezone	string	yes	IANA timezone, 1–100 characters, for example Europe/Kyiv
days	object	yes	Exactly seven weekday objects with no extra keys
days.<Weekday>.start	string	yes	HH:MM or an empty string for a day off
days.<Weekday>.end	string	yes	HH:MM or an empty string for a day off; both start and end must be empty or populated

{
  "timezone": "Europe/Kyiv",
  "days": {
    "Monday": { "start": "09:00", "end": "18:00" },
    "Tuesday": { "start": "09:00", "end": "18:00" },
    "Wednesday": { "start": "09:00", "end": "18:00" },
    "Thursday": { "start": "09:00", "end": "18:00" },
    "Friday": { "start": "09:00", "end": "18:00" },
    "Saturday": { "start": "", "end": "" },
    "Sunday": { "start": "", "end": "" }
  }
}

follow_up_update

Update a postponed follow-up. Supplying steps atomically replaces the complete ordered sequence; use an empty array to clear a draft. Configuration on a live sequence can only change while it is being moved to draft in the same call, or after a prior unpublish. Updates use optimistic status matching, so a concurrent publish/unpublish returns an error instead of overwriting the other change.

Param	Type	Required	Description
follow_up_id	string	yes	Positive decimal postponed follow-up ID
name	string	no	New name, 1–200 characters
status	string	no	draft to disable or live to publish after full validation
target_status_name	string	no	Target funnel status, maximum 200 characters; "" clears it
target_labels	array of string	no	Full replacement of up to 100 unique, non-empty labels; [] clears label targeting
target_labels_operator	string	no	or or and; defaults to or when targeting is first created
steps	array of object	no	Full ordered replacement; same object as follow_up_create
schedule	object	no	Full working-hours replacement
clear_schedule	boolean	no	Remove working-hours restrictions. Cannot be combined with schedule
generate_email_subject	boolean	no	Enable or disable AI-generated email subjects

Provide at least one field to change in addition to follow_up_id.

Returns the complete updated record. Because updates use optimistic status matching, a concurrent lifecycle change fails instead of silently overwriting it; read the record again before retrying.

follow_up_delete

Delete a follow-up automation.

Param	Type	Required	Description
follow_up_id	string	yes	Positive decimal follow-up ID

Returns {message: "follow-up deleted", follow_up_id}. Deletion is permanent and can target any follow-up type; inspect the record first.

immediate_outreach_create

Create and schedule an immediate outreach campaign. This can send messages or place calls. Use immediate_outreach_preview_audience, inspect sample leads, confirm the channel, content, schedule, audience count, and pacing with the user, and only then call this tool. It creates a scheduled campaign immediately—there is no draft stage on this path.

Param	Type	Required	Description
name	string	yes	Campaign name, 1–200 characters
client_source	string	yes	Audience source: withChats, allClients, or withoutChats
outreach_channels	array of string	yes	1–50 unique, enabled, account-owned channels in ChannelType__AssistantID form, attempted in order; at most one assistant per channel type. Use only list_channels rows with immediate_outreach_capable=true. Supported types: PersonalWhatsApp, TelegramAccount, EChatViber, EChatTelegram, Email, Calls, Ringostat, UniTalk, Binotel, SMS
schedule_mode	string	yes	now (runs in ~3 min) or later (requires schedule_run_at)
schedule_run_at	string	no	Future RFC3339 instant for later, or a naive YYYY-MM-DDTHH:MM[:SS] wall time when paired with timezone_field; omit for now
timezone_field	string	no	Custom lead field, maximum 200 characters, containing an IANA timezone or UTC offset for per-lead scheduling; requires a naive schedule_run_at
send_window_start	string	no	Optional daily delivery-window start in HH:MM; requires send_window_end
send_window_end	string	no	Optional daily delivery-window end in HH:MM; supply both and make end later than start
send_timezone	string	no	IANA timezone for the daily window, maximum 100 characters; default UTC
dynamic_audience	boolean	no	false (default) freezes the audience when creating; true resolves the filters again at send time
instructions	string	conditional	AI prompt, maximum 20,000 characters; required when use_custom_message=false
custom_message	string	conditional	Static message, maximum 20,000 characters; required when use_custom_message=true
use_custom_message	boolean	no	If true, send custom_message verbatim; if false, compose with AI from instructions
email_subject	string	no	Email-only subject, maximum 998 characters and no line breaks
email_attachments	array	no	Up to 20 public HTTP(S) files; each entry is a URL or {url,name}. Requires an Email channel
instruction_attachments	array of string	no	Up to 20 public HTTP(S) URLs for AI-composed messages
custom_message_attachments	array of string	no	Up to 20 public HTTP(S) URLs for the custom message
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	Up to 100 unique funnel statuses, each 1–200 characters
include_no_status	boolean	no	Include clients with no funnel status
labels	array of string	no	Up to 100 unique labels, each 1–200 characters
labels_operator	string	no	or (any label) or and (all labels, default)
include_no_labels	boolean	no	Include clients with no labels
manager_ids	array of string	no	Up to 100 unique full UUIDs of assigned managers
targeting_channels	array of string	no	Up to 100 unique existing-chat channel types; only valid for withChats
targeting_assistants	array of integer	no	Up to 100 unique positive existing-chat assistant IDs; only valid for withChats
pipeline_ids	array of integer	no	Up to 100 unique positive Sales pipeline 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 lookback for withChats, 0–365 days (0 uses the default 7)
cutoff_date	string	no	Inclusive withChats activity-range start as RFC3339 or YYYY-MM-DD
cutoff_end_date	string	no	Inclusive withChats activity-range end as RFC3339 or YYYY-MM-DD; must not precede cutoff_date
created_date_from	string	no	Inclusive creation-range start for allClients/withoutChats, as RFC3339 or YYYY-MM-DD
created_date_to	string	no	Inclusive creation-range end for allClients/withoutChats; must not precede created_date_from
audience_limit	integer	no	Maximum recipients, 0–10,000; 0 means unlimited
metadata_filters	array of object	no	Up to 20 ANDed custom-field filters: {field, operator, values} where operator is eq, in, or contains; eq requires one value
interval_seconds	integer	no	Pacing window, 0–86,400 seconds. Must be positive together with chats_per_interval, or both zero
chats_per_interval	integer	no	Recipients per pacing window, 0–1,000
send_delay_seconds	integer	no	Delay between individual sends, 0–86,400 seconds; default 7
number_of_lines	integer	no	Concurrent Calls lines, 0–100; requires a Calls channel; 0 uses the channel default

Metadata filter object

Every object in metadata_filters must contain all three fields. Filters are ANDed and field/value comparisons are case-insensitive. Duplicate field names are rejected case-insensitively.

Field	Type	Required	Description
field	string	yes	Custom-field name, 1–200 characters
operator	string	yes	eq, in, or contains
values	array of string	yes	1–100 unique non-empty values; eq requires exactly one value; each value is at most 20,000 characters

Email attachment object

Each email_attachments entry may be a public HTTP(S) URL string or this object:

Field	Type	Required	Description
url	string	yes	Public HTTP(S) URL, maximum 4,096 characters; embedded credentials and local/private hosts are rejected
name	string	no	Display filename, maximum 200 characters; defaults from the URL path

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.

For a naive schedule_run_at paired with timezone_field, a static campaign validates the resulting UTC instant for every resolved recipient before it is stored. A dynamic campaign cannot know its future recipients yet, so its wall time must still be in the future at the easternmost supported offset (UTC+14). This prevents a past local time from turning into an immediate send when the scheduler wakes.

Returns {follow_up_id, status, stats: {matched}}. A successful call has already stored the campaign; it is not a simulation.

immediate_outreach_update_status

Pause, resume, or reset an immediate outreach campaign. The tool rejects unsafe lifecycle jumps and uses optimistic status matching. A running campaign must first move to user_paused; only a user-paused campaign can resume as scheduled. draft clears all progress and statistics and is not available directly from a running state.

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

Returns {success, follow_up_id, status}.

immediate_outreach_preview_audience

Preview the matched audience without creating or scheduling a campaign. Returns matched_count, missing_count, a five-lead sample, and the resolved cutoff range. It accepts the same audience fields as immediate_outreach_create (but no channel, message, or scheduling fields). Preview is read-only; creation is the separate external effect.

Param	Type	Required	Description
client_source	string	yes	withChats, allClients, or withoutChats
statuses	array of string	no	Up to 100 unique funnel statuses, each 1–200 characters
include_no_status	boolean	no	Include clients with no funnel status
labels	array of string	no	Up to 100 unique labels, each 1–200 characters
labels_operator	string	no	or or and; default and
include_no_labels	boolean	no	Include clients with no labels
manager_ids	array of string	no	Up to 100 unique manager UUIDs
targeting_channels	array of string	no	Up to 100 unique existing-chat channel types; withChats only
targeting_assistants	array of integer	no	Up to 100 unique positive existing-chat assistant IDs; withChats only
pipeline_ids	array of integer	no	Up to 100 unique positive pipeline 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)
cutoff_date	string	no	Inclusive existing-chat activity-range start as RFC3339 or YYYY-MM-DD
cutoff_end_date	string	no	Inclusive existing-chat activity-range end; must not precede cutoff_date
created_date_from	string	no	Inclusive client creation-range start for allClients/withoutChats
created_date_to	string	no	Inclusive client creation-range end; must not precede created_date_from
audience_limit	integer	no	Max recipients, 0–10,000; 0 means unlimited
metadata_filters	array of object	no	Up to 20 custom-field filters; same object shape and limits as create

Returns {matched_count, missing_count, sample_clients, cutoff_date, cutoff_end_date}. sample_clients contains at most five {client_id, client_name} rows.

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	Positive numeric assistant ID as a string; disambiguates when more than one assistant has a Calls channel and is 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.

Returns status, client and channel identifiers, the dialed number, and the provider conversation_id. A successful call means dialing was initiated; it is not a preview.

send_one_off_message

Perform a single ad-hoc outbound action for a specific lead through a non-Calls channel. Messaging channels send message; Ringostat, UniTalk, and Binotel instead initiate telephony calls and do not deliver that field as customer-visible text. For an AI voice call with a literal spoken opening line, use outbound_call. For campaigns, use immediate_outreach_create. The action is real and immediate: confirm the recipient, channel, and exact effect 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	Positive numeric assistant ID as a string; 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, or Binotel. Calls is rejected—use outbound_call
message	string	yes	Plain text for messaging channels. Required but not delivered or spoken by the Ringostat, UniTalk, and Binotel call providers
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: Ringostat, UniTalk, and Binotel are call providers despite this tool's legacy name; selecting one initiates a real operator callback/direct call. 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.

Returns {status: "sent", client_id, channel, page_id} plus chat_id when a chat record is available and the resolved to/cc/bcc arrays for Email. Success means a real send occurred; there is currently no no-effect preview for this tool.

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.

learn_website

Crawl the useful pages of a business website and write stored FAQ/business facts plus starter questions for one assistant. Unlike live website knowledge, stored knowledge also reaches voice assistants. Re-running replaces the stored knowledge this operation wrote before and can take 15–30 seconds.

Param	Type	Required	Description
assistant_id	string	yes	Assistant to teach
url	string	yes	Business website
knowledge_base	string	yes	Knowledge-base group for the stored source

add_website_knowledge

Add a website as a live search/read source. There is no indexing wait; the assistant reads current pages at answer time. Assistants without a knowledge base are attached to the named group automatically.

Param	Type	Required	Description
url	string	yes	Public website URL, including https://
knowledge_base	string	yes	Existing or new knowledge-base group
name	string	no	Human-readable source name; defaults to the domain

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), or a Shopify store address — see Shopify store seller
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
autoupdate_interval_hours	integer	no	Re-read the feed every 1, 3, 6, 12 or 24 hours; omit to leave auto-update off
fast_start	boolean	no	Shopify stores: index the first 250 products first so the assistant can answer within a couple of minutes, then sync the rest right after; 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

delete_product_feed_integration

Delete a Product Feed integration and all indexed data. Irreversible. This tool refuses manually managed Products integrations; use the matching delete tool for that catalog type.

Param	Type	Required	Description
integration_id	string	yes	The Product Feed 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.

enable_order_taking

Enable or reconfigure conversational order taking for one assistant. Existing settings are updated rather than duplicated.

Param	Type	Required	Description
assistant_id	string	yes	Assistant that should take orders
currency	string	no	Three-letter currency code; default USD
requires_payment	boolean	no	Whether payment is required before confirmation; default false
required_fields	array	no	Customer fields {name, type, required, options?}; type is text, number, or select
item_fields	array	no	Per-product fields with the same shape

disable_order_taking

Remove the assistant's ability to record new orders while preserving existing orders and its normal answering/recommendation behavior.

Param	Type	Required	Description
assistant_id	string	yes	Assistant that should stop taking orders

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

• Build and operate outreach with Claude or Codex — end-to-end use of the sales_outreach tools
• 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