io.github.saloprj/dialogbrain

Official225 toolsLive

by saloprj

Unified inbox MCP for WhatsApp, Telegram, Email, voice — read/send messages, search, AI agents.

io.github.saloprj/dialogbrain MCP Server

A unified inbox MCP server that connects various messaging channels to a single AI-enabled workspace. It enables reading and sending messages, searching content, and orchestrating AI agents across WhatsApp, Telegram, Email, voice, and more, with a focus on cross-channel workflow.

🛠️ Key Features

Unified inbox spanning WhatsApp, Telegram, Email, voice, and more
Read/write message operations across channels
Channel search, threads, and history access
AI agent orchestration within a shared workspace
OAuth 2.0 authentication with dynamic client registration
Streamable HTTP transport for low-latency access
Large toolset for cross-channel interactions

🚀 Use Cases

Multi-channel customer support and ticketing
AI-assisted inbox management and snooping across platforms
Cross-channel message search and history analysis
Agent orchestration for automated responses and workflows

⚡ Developer Benefits

Central MCP endpoint for multiple channels
Standard OAuth 2.0 authentication and dynamic client setup
Extensive toolset for reading, writing, and searching messages
Clear readme and developer docs linked in the source

⚠️ Limitations

Source data mentions a large but unspecified tool count; exact numbers may vary by deployment
Readme excerpt indicates ongoing documentation beyond initial setup
Availability and features may depend on hosted service (external product links)

Captured live from the server via tools/list.

contacts_find

👤 Search for contacts in your address book by name or username. When to use: - User asks 'find contact X' or 'who is Y?' - User wants to know someone's username or ID - Before sending a message to verify contact exists - To get contact's channel reference for messaging Examples: ❓ User: 'find contact named [name]' → contacts_search(query='[name]', limit=5) ❓ User: 'who is [full name]?' → contacts_search(query='[full name]', limit=1) ❓ User: 'search for @username' → contacts_search(query='username', limit=10) Returns: name, username, channel, channel_ref, similarity_score, match_type. Plus: - entity_id: local DB key — pass to contacts.profile. Null for live-discovered contacts (skip contacts.profile for those). - telegram_user_id (when channel='telegram'): the Telegram user ID — pass to calls.make / messages.send. NOT entity_id.

Parameters3

query	string	required	Name or username to search for (supports partial matches)
limit	integer	optional	Maximum number of results to return
channel	string	optional	Filter by channel. OMIT to search across all channels.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Name or username to search for (supports partial matches)",
      "minimum": 1
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    },
    "channel": {
      "type": "string",
      "description": "Filter by channel. OMIT to search across all channels.",
      "enum": [
        "telegram",
        "email",
        "whatsapp",
        "sms",
        "slack"
      ]
    }
  },
  "required": [
    "query"
  ]
}

contacts_discover

Search for a contact on a live channel (Telegram, WhatsApp, etc.) before adding them. Use this to look up a person by username or phone number before calling contacts.sync. This is the right tool when asked to add or find a specific person by @username or phone (use contacts.sync afterwards to actually add them) — not group_discovery.

Parameters2

query	string	required	Username, phone, or name to search for
channel	string	required	Channel name: telegram, whatsapp, etc.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Username, phone, or name to search for"
    },
    "channel": {
      "type": "string",
      "description": "Channel name: telegram, whatsapp, etc."
    }
  },
  "required": [
    "query",
    "channel"
  ]
}

contacts_research

Research a person before outreach: returns a synthesized profile (current role, company, location, career history, education, LinkedIn/social URLs) plus a candidates array for disambiguating namesakes. Use to personalize a first touch or brief before a meeting. Does NOT return contact channels (email/phone/telegram) — use contacts.discover to add a reachable channel, or the LinkedIn URL from the result for a connection request.

Parameters1

query

string

required

Who to research: full name plus any disambiguating context you have (company, role, location), e.g. '[full name], founder of [company]'.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Who to research: full name plus any disambiguating context you have (company, role, location), e.g. '[full name], founder of [company]'."
    }
  },
  "required": [
    "query"
  ]
}

contacts_sync

Add a discovered contact and open a conversation thread. Returns thread_id for the new conversation, plus entity_id — the canonical handle to pass as contacts.update's contact_id. Call contacts.discover first to verify the contact exists.

Parameters2

identifier	string	required	Username or phone number to add
channel	string	required	Channel name: telegram, whatsapp, etc.

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "Username or phone number to add"
    },
    "channel": {
      "type": "string",
      "description": "Channel name: telegram, whatsapp, etc."
    }
  },
  "required": [
    "identifier",
    "channel"
  ]
}

contacts_profile

👤 Get full profile for a contact: all channel identities, notes, role, capabilities, birthday. When to use: - After contacts.find to get complete info about a specific person - To see all channels a contact is reachable on - To read notes, role, or capabilities for a contact Requires contact_id (entity_id) from contacts.find.

Parameters1

contact_id

string

required

entity_id from contacts.find

Raw schema

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "description": "entity_id from contacts.find"
    }
  },
  "required": [
    "contact_id"
  ]
}

contacts_update

✏️ Update a contact's profile: name, notes, role, capabilities, birthday, preferred channel. When to use: - User wants to add notes about a contact - User wants to set/update role or capabilities for a contact - User wants to rename a contact or update birthday Requires contact_id — the entity_id returned by contacts.find or contacts.sync. At least one optional field must be provided.

Parameters9

contact_id	string	required	entity_id from contacts.find or contacts.sync
display_name	string	optional	New display name (max 255 chars)
notes	string	optional	Free-text notes/context about this contact. Empty string clears notes.
preferred_channel	string	optional	Preferred channel for contacting this person. OMIT to leave the preferred channel unchanged.
role	string	optional	Contact role (e.g. developer, client, partner). Empty string clears role.
capabilities	array	optional	List of capabilities (e.g. ['backend', 'design'])
birthday_month	integer	optional	Birth month 1-12 (must be set together with birthday_day)
birthday_day	integer	optional	Birth day 1-31 (must be set together with birthday_month)
birthday_year	integer	optional	Birth year 1900-2100 (optional, standalone)

Raw schema

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "description": "entity_id from contacts.find or contacts.sync"
    },
    "display_name": {
      "type": "string",
      "description": "New display name (max 255 chars)"
    },
    "notes": {
      "type": "string",
      "description": "Free-text notes/context about this contact. Empty string clears notes."
    },
    "preferred_channel": {
      "type": "string",
      "description": "Preferred channel for contacting this person. OMIT to leave the preferred channel unchanged.",
      "enum": [
        "telegram",
        "whatsapp",
        "email",
        "instagram",
        "linkedin"
      ]
    },
    "role": {
      "type": "string",
      "description": "Contact role (e.g. developer, client, partner). Empty string clears role."
    },
    "capabilities": {
      "type": "array",
      "description": "List of capabilities (e.g. ['backend', 'design'])",
      "items": {
        "type": "string"
      }
    },
    "birthday_month": {
      "type": "integer",
      "description": "Birth month 1-12 (must be set together with birthday_day)",
      "minimum": 1,
      "maximum": 12
    },
    "birthday_day": {
      "type": "integer",
      "description": "Birth day 1-31 (must be set together with birthday_month)",
      "minimum": 1,
      "maximum": 31
    },
    "birthday_year": {
      "type": "integer",
      "description": "Birth year 1900-2100 (optional, standalone)",
      "minimum": 1900,
      "maximum": 2100
    }
  },
  "required": [
    "contact_id"
  ]
}

contacts_add_channel

🔗 Link a new channel identity (email, phone, LinkedIn, etc.) to an existing contact. When to use: - User learns a contact's email or phone and wants to save it - User wants to link a LinkedIn/Instagram profile to an existing contact - Adding a second channel for an existing person Requires contact_id (entity_id) from contacts.find.

Parameters4

contact_id	string	required	entity_id from contacts.find
channel	string	required	Channel type to add
value	string	required	Email address, phone number, or username for this channel
display_name	string	optional	Optional display label for this identity

Raw schema

{
  "type": "object",
  "properties": {
    "contact_id": {
      "type": "string",
      "description": "entity_id from contacts.find"
    },
    "channel": {
      "type": "string",
      "description": "Channel type to add",
      "enum": [
        "email",
        "whatsapp",
        "telegram",
        "linkedin",
        "instagram"
      ]
    },
    "value": {
      "type": "string",
      "description": "Email address, phone number, or username for this channel"
    },
    "display_name": {
      "type": "string",
      "description": "Optional display label for this identity"
    }
  },
  "required": [
    "contact_id",
    "channel",
    "value"
  ]
}

contacts_capture_lead

📝 Save the current contact's details as a structured lead (contact + Contacts tab). When to use: - In a website-chat OR voice-call conversation, AFTER the person has shared their name (plus email / phone / company / use case if given) — e.g. when booking a demo or a class. - Call it once you have the details; then continue (e.g. share the booking link). Creates/links a contact record and a lead entry in the workspace's lead inbox. Works in any conversation thread (website chat, voice call, DM).

Parameters5

name	string	required	The visitor's full name (as they gave it).
email	string	optional	The visitor's email address.
company	string	optional	The visitor's company / organization, if mentioned.
use_case	string	optional	Their main use case / what they want to do with DialogBrain, if mentioned.
phone	string	optional	Phone number, if the visitor provided one.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "The visitor's full name (as they gave it)."
    },
    "email": {
      "type": "string",
      "description": "The visitor's email address."
    },
    "company": {
      "type": "string",
      "description": "The visitor's company / organization, if mentioned."
    },
    "use_case": {
      "type": "string",
      "description": "Their main use case / what they want to do with DialogBrain, if mentioned."
    },
    "phone": {
      "type": "string",
      "description": "Phone number, if the visitor provided one."
    }
  },
  "required": [
    "name"
  ]
}

group_search

Search for public groups or channels by topic on Telegram (or other channels). Returns matching groups with title, member count, and whether messages can be previewed. Finds public groups/channels by topic — NOT individual people. To find or add a specific person by @username, use contacts.discover / contacts.find instead. When to use: - Finding groups related to a topic or niche - Building a list of groups for outreach or monitoring After searching, use group.scan to evaluate quality before joining.

Parameters3

channel	string	required	Channel to search on (e.g. 'telegram')
keywords	string	required	Search keywords or phrase (e.g. 'crypto trading signals')
limit	integer	optional	Maximum number of results to return (1-50, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "description": "Channel to search on (e.g. 'telegram')"
    },
    "keywords": {
      "type": "string",
      "description": "Search keywords or phrase (e.g. 'crypto trading signals')"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return (1-50, default 20)",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "channel",
    "keywords"
  ]
}

group_add

Add a specific group to your discovery list by @username or invite link (t.me/...). Groups and channels only — this does NOT add an individual person/contact. To add a person by @username (e.g. a customer or lead), use contacts.discover then contacts.sync instead. When to use: - You already know the group's @username or invite link - Adding a known group without searching Returns: group metadata including id, title, member_count.

Parameters2

channel	string	required	Channel the group is on (e.g. 'telegram')
link	string	required	The group's @username or invite link (e.g. '@phuket' or 't.me/...')

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "description": "Channel the group is on (e.g. 'telegram')"
    },
    "link": {
      "type": "string",
      "description": "The group's @username or invite link (e.g. '@phuket' or 't.me/...')"
    }
  },
  "required": [
    "channel",
    "link"
  ]
}

group_list

List groups in this workspace's DISCOVERY/SCORING list (the discovered_group table). ⚠️ This is NOT your messageable inbox. It is a subset used for discovery + quality scoring, and its channel_ref may be un-normalized (raw positive id) and will NOT match a thread's channel_ref. Absence here does NOT mean a chat isn't joined or can't be messaged. To find a chat you can actually send to (and get its thread_id), use search_threads — never rely on group.list for reachability. Lifecycle values: - discovered: found but not yet evaluated - bookmarked: saved for later - monitored: joined and actively syncing messages - dismissed: hidden By default, dismissed groups are excluded. Returns: id, title, member_count, lifecycle, scan_status, overall_score.

Parameters5

channel	string	optional	Filter by channel (e.g. 'telegram'). Optional.
lifecycle	string	optional	Filter by state: discovered, bookmarked, monitored (=joined/syncing), dismissed. OMIT to include all states (dismissed excluded by default elsewhere).
min_score	number	optional	Minimum overall score (0.0-1.0). Optional.
limit	integer	optional	Maximum number of results (1-100, default 20)
offset	integer	optional	Pagination offset. OMIT to start at row 0 (default).

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "description": "Filter by channel (e.g. 'telegram'). Optional."
    },
    "lifecycle": {
      "type": "string",
      "description": "Filter by state: discovered, bookmarked, monitored (=joined/syncing), dismissed. OMIT to include all states (dismissed excluded by default elsewhere).",
      "enum": [
        "discovered",
        "bookmarked",
        "monitored",
        "dismissed"
      ]
    },
    "min_score": {
      "type": "number",
      "description": "Minimum overall score (0.0-1.0). Optional.",
      "minimum": 0,
      "maximum": 1
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of results (1-100, default 20)",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Pagination offset. OMIT to start at row 0 (default).",
      "minimum": 0
    }
  },
  "required": []
}

group_preview_messages

Read recent public messages from a group without joining it. Only works for groups where can_preview_history=true. Use this to manually evaluate message quality before deciding to join. For an automated quality score, use group.scan instead. Returns: list of recent messages with sender, text, date, is_reply.

Parameters2

group_id	integer	required	ID of the discovered group (from group.search or group.list)
limit	integer	optional	Number of recent messages to fetch (1-100, default 20)

Raw schema

{
  "type": "object",
  "properties": {
    "group_id": {
      "type": "integer",
      "description": "ID of the discovered group (from group.search or group.list)"
    },
    "limit": {
      "type": "integer",
      "description": "Number of recent messages to fetch (1-100, default 20)",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  },
  "required": [
    "group_id"
  ]
}

group_scan

Scan a group to evaluate its quality before joining. Fetches recent messages, analyzes activity, spam, and engagement, then returns a quality score and plain-English verdict. When to use: - After finding groups with group.search - Before deciding which groups to join Returns: overall_score (0-1), is_disqualified, disqualify_reasons, individual scores, and a verdict string.

Parameters1

group_id

integer

required

ID of the discovered group (from group.search or group.list)

Raw schema

{
  "type": "object",
  "properties": {
    "group_id": {
      "type": "integer",
      "description": "ID of the discovered group (from group.search or group.list)"
    }
  },
  "required": [
    "group_id"
  ]
}

group_join

Join a group and start syncing its messages to your inbox. The group must be in your discovery list (use group.search or group.add first). What this does: - Joins the group on Telegram (or other channel) - Creates a thread in your inbox for syncing messages - Optionally enables AI auto-reply drafts Returns: success, thread_id, auto_reply_enabled.

Parameters2

group_id	integer	required	ID of the discovered group (from group.search or group.list)
enable_auto_reply	boolean	optional	Enable AI auto-reply drafts for messages in this group. Drafts can be reviewed and sent manually. Default: true.

Raw schema

{
  "type": "object",
  "properties": {
    "group_id": {
      "type": "integer",
      "description": "ID of the discovered group (from group.search or group.list)"
    },
    "enable_auto_reply": {
      "type": "boolean",
      "description": "Enable AI auto-reply drafts for messages in this group. Drafts can be reviewed and sent manually. Default: true.",
      "default": true
    }
  },
  "required": [
    "group_id"
  ]
}

group_create

Create a new group on a channel (Telegram or WhatsApp). Returns the new group's chat ID and invite link. What this does: - Creates a new group with the specified title - Returns chat_id, invite_link, and channel_ref for further operations - Optionally registers the group in your inbox for monitoring Returns: success, chat_id, channel_ref, title, thread_id.

Parameters5

title	string	required	Title/name of the group to create
about	string	optional	Optional description or about text for the group
group_type	string	optional	Type of group to create. Options: 'supergroup' (default), 'basic'. Telegram-only; ignored on WhatsApp.
channel	string	required	Channel to create the group on (e.g., 'telegram', 'whatsapp')
register_in_inbox	boolean	optional	Auto-register the created group in your inbox for monitoring. Default: true.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Title/name of the group to create"
    },
    "about": {
      "type": "string",
      "description": "Optional description or about text for the group"
    },
    "group_type": {
      "type": "string",
      "description": "Type of group to create. Options: 'supergroup' (default), 'basic'. Telegram-only; ignored on WhatsApp.",
      "default": "supergroup"
    },
    "channel": {
      "type": "string",
      "description": "Channel to create the group on (e.g., 'telegram', 'whatsapp')"
    },
    "register_in_inbox": {
      "type": "boolean",
      "description": "Auto-register the created group in your inbox for monitoring. Default: true.",
      "default": true
    }
  },
  "required": [
    "title",
    "channel"
  ]
}

group_add_member

Add a member to an existing group on Telegram or WhatsApp. What this does: - Adds the specified member to the group - Resolves the member by username, phone number, or JID - Reports if the member is already in the group Returns: success, chat_id, member, already_member.

Parameters3

chat_id	integer	required	ID of the group/channel to add the member to
member	string	required	The member to add (format depends on channel: @username on Telegram, phone on WhatsApp)
channel	string	required	Channel where the group exists (e.g., 'telegram', 'whatsapp')

Raw schema

{
  "type": "object",
  "properties": {
    "chat_id": {
      "type": "integer",
      "description": "ID of the group/channel to add the member to"
    },
    "member": {
      "type": "string",
      "description": "The member to add (format depends on channel: @username on Telegram, phone on WhatsApp)"
    },
    "channel": {
      "type": "string",
      "description": "Channel where the group exists (e.g., 'telegram', 'whatsapp')"
    }
  },
  "required": [
    "chat_id",
    "member",
    "channel"
  ]
}

group_promote_admin

Promote a member to admin in an existing group on Telegram or WhatsApp. What this does: - Gives the specified member admin status in the group - On Telegram, this grants visibility of all group messages (even if not a bot) - Defaults to minimal/empty rights; specify custom rights if needed Returns: success, chat_id, member.

Parameters4

chat_id	integer	required	ID of the group/channel where the member will be promoted
member	string	required	The member to promote (format depends on channel: @username on Telegram, phone on WhatsApp)
rights	object	optional	Optional admin rights dict (Telegram-specific). If not provided, defaults to minimal/admin status only. Example: {"post_messages": true, "edit_messages": true}
channel	string	required	Channel where the group exists (e.g., 'telegram', 'whatsapp')

Raw schema

{
  "type": "object",
  "properties": {
    "chat_id": {
      "type": "integer",
      "description": "ID of the group/channel where the member will be promoted"
    },
    "member": {
      "type": "string",
      "description": "The member to promote (format depends on channel: @username on Telegram, phone on WhatsApp)"
    },
    "rights": {
      "type": "object",
      "description": "Optional admin rights dict (Telegram-specific). If not provided, defaults to minimal/admin status only. Example: {\"post_messages\": true, \"edit_messages\": true}"
    },
    "channel": {
      "type": "string",
      "description": "Channel where the group exists (e.g., 'telegram', 'whatsapp')"
    }
  },
  "required": [
    "chat_id",
    "member",
    "channel"
  ]
}

group_get_invite_link

Export an invite link for an existing group (Telegram). What this does: - Mints a fresh invite link (e.g. t.me/+...) for the group; previously issued links stay valid - Requires the connected account to be the group's owner or an admin with invite rights When to use: - A member can't be added directly because their privacy settings block invites (group.add_member fails with a privacy error) — send them this link instead - Onboarding people to a private group Returns: success, chat_id, invite_link.

Parameters2

chat_id	integer	required	ID of the group/channel to export an invite link for
channel	string	required	Channel where the group exists (e.g., 'telegram')

Raw schema

{
  "type": "object",
  "properties": {
    "chat_id": {
      "type": "integer",
      "description": "ID of the group/channel to export an invite link for"
    },
    "channel": {
      "type": "string",
      "description": "Channel where the group exists (e.g., 'telegram')"
    }
  },
  "required": [
    "chat_id",
    "channel"
  ]
}

files_ingest

Save and index a file into the knowledge base. Use this when the user asks to save, store, or remember a document. The file will be processed (OCR if needed) and indexed for future search.

Parameters5

file_id	integer	required	ID of the file to ingest (from attachment_file_ids in context).
title	string	optional	Human-readable title for the file (e.g., 'Project Presentation', 'Q1 Report'). If not provided, uses original filename.
description	string	optional	Optional description of the file contents.
thread_id	integer	optional	Optional thread ID to associate the file with. If not provided, uses context thread.
tags	array	optional	Optional list of tags for categorization (e.g., ['presentation', 'dextrade']).

Raw schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "integer",
      "description": "ID of the file to ingest (from attachment_file_ids in context)."
    },
    "title": {
      "type": "string",
      "description": "Human-readable title for the file (e.g., 'Project Presentation', 'Q1 Report'). If not provided, uses original filename."
    },
    "description": {
      "type": "string",
      "description": "Optional description of the file contents."
    },
    "thread_id": {
      "type": "integer",
      "description": "Optional thread ID to associate the file with. If not provided, uses context thread."
    },
    "tags": {
      "type": "array",
      "description": "Optional list of tags for categorization (e.g., ['presentation', 'dextrade']).",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "file_id"
  ]
}

files_read

Read **text content** of an attached file. Works for: .txt, .md, .json, code files, and PDFs (after files.ingest extracts text). DO NOT call on binary files — for IMAGES use `files.get_base64`, for AUDIO/VIDEO it cannot be transcribed via this tool, and for non-PDF DOCUMENTS run `files.ingest` first, THEN files.read. Calling on a binary mime-type returns an error — saves you a turn to read the routing hint before deciding.

Parameters4

file_id	integer	required	ID of the file to read (from attachment_file_ids in context).
max_chars	integer	optional	Maximum characters to return (default: 10000). Use smaller values for large files.
encoding	string	optional	Text encoding to use (default: utf-8).
summarize	boolean	optional	If true, generate AI summary instead of returning raw content. Use for 'summary', 'summarize', 'краткое содержание' requests. OMIT to return raw content (the default).

Raw schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "integer",
      "description": "ID of the file to read (from attachment_file_ids in context)."
    },
    "max_chars": {
      "type": "integer",
      "description": "Maximum characters to return (default: 10000). Use smaller values for large files.",
      "minimum": 100,
      "maximum": 50000,
      "default": 10000
    },
    "encoding": {
      "type": "string",
      "description": "Text encoding to use (default: utf-8).",
      "default": "utf-8"
    },
    "summarize": {
      "type": "boolean",
      "description": "If true, generate AI summary instead of returning raw content. Use for 'summary', 'summarize', 'краткое содержание' requests. OMIT to return raw content (the default)."
    }
  },
  "required": [
    "file_id"
  ]
}

files_upload

Upload a file to DialogBrain and get a file_id for use in messages_send. When to use: - User wants to send a file/image to a contact - Before calling messages_send with an attachment Returns: file_id (integer) to pass to messages_send attachments parameter.

Parameters5

content	string	optional	Base64-encoded file bytes. Either content OR source_url is required.
source_url	string	optional	Public URL to fetch file from. Either content OR source_url is required.
filename	string	optional	Filename with extension (e.g. 'photo.png')
mime_type	string	optional	MIME type (e.g. 'image/png', 'application/pdf')
title	string	optional	Optional display title

Raw schema

{
  "type": "object",
  "properties": {
    "content": {
      "type": "string",
      "description": "Base64-encoded file bytes. Either content OR source_url is required."
    },
    "source_url": {
      "type": "string",
      "description": "Public URL to fetch file from. Either content OR source_url is required."
    },
    "filename": {
      "type": "string",
      "description": "Filename with extension (e.g. 'photo.png')",
      "default": "upload"
    },
    "mime_type": {
      "type": "string",
      "description": "MIME type (e.g. 'image/png', 'application/pdf')",
      "default": "application/octet-stream"
    },
    "title": {
      "type": "string",
      "description": "Optional display title"
    }
  },
  "required": []
}

images_generate

Generates a PNG image from a text prompt using Gemini 2.5 Flash Image. Returns a file_id consumable by messages.send(attachments=[...]) and other file-aware tools. Supports up to 12 reference image file_ids for subject-consistent edits and composition (use file IDs from the [ATTACHMENTS] block, files.search, or search.files). Latency: ~8-10s per image. Output: 1024×1024 PNG.

Parameters3

prompt	string	required	Text description of the image to generate (3-4000 chars).
reference_file_ids	array	optional	Optional list of up to 3 file_ids whose images should be used as visual references (for edits, subject consistency, or composition). Files must be image MIME types (image/png, image/jpeg, image/webp, image/gif).
aspect_ratio	string	optional	Output aspect ratio.

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Text description of the image to generate (3-4000 chars)."
    },
    "reference_file_ids": {
      "type": "array",
      "description": "Optional list of up to 3 file_ids whose images should be used as visual references (for edits, subject consistency, or composition). Files must be image MIME types (image/png, image/jpeg, image/webp, image/gif).",
      "items": {
        "type": "integer"
      }
    },
    "aspect_ratio": {
      "type": "string",
      "description": "Output aspect ratio.",
      "enum": [
        "1:1",
        "16:9",
        "9:16",
        "4:3",
        "3:4"
      ],
      "default": "1:1"
    }
  },
  "required": [
    "prompt"
  ]
}

videos_generate

Generate a short video (5-10s) from a text prompt using BytePlus Seedance. Optionally accepts up to 12 image file IDs from the user's attached files (visible in the [ATTACHMENTS] block) as `reference_file_ids` for style and composition. Returns immediately with a job_id; the video is delivered back via continuation when the job completes (~30-90s for fast model, ~2-5min for pro). Reference images are temporarily re-hosted on a third-party CDN (imgbb) for the duration of generation and deleted on completion — don't submit confidential references. Gated behind a workspace opt-in flag.

Parameters12

prompt	string	required	Text description of the video to generate (3-4000 chars).
reference_file_ids	array	optional	Optional list of up to 12 image file_ids to use as visual references (style, composition). Files must be image MIME types (image/png, image/jpeg, image/webp, image/gif). Get IDs from the [ATTACHMENTS] block, files.search, or search.files.
model	string	optional	Video model. Recommended: 'wan2.6-i2v-flash' (default, cheap, 720p/1080p, optional audio), 'wan2.6-i2v' (premium, always-on audio), 'wan2.6-t2v' (text-only input, 720p/1080p, no audio), 'wan2.2-i2v-flash' (cheapest, 480p/720p, no audio). Legacy BytePlus: 'seedance-2-fast', 'seedance-2-pro' (720p only).
duration	integer	optional	Output video duration in seconds. Single-clip: 5 or 10. Long-form (chained, i2v models only): 15, 20, 30, 45, or 60. Long-form videos are silent (no audio in v1) and use only reference_file_ids[0] when refs are provided.
resolution	string	optional	Output resolution. '720p' is the safe default; '1080p' is wan2.6 only; '480p' is wan2.2-i2v-flash only. Per-model support enforced by validation.
aspect_ratio	string	optional	Output aspect ratio. Wan supports '16:9', '9:16', '1:1'; Seedance also supports '4:3', '3:4', '21:9'. Per-model support enforced by validation.
generate_audio	boolean	optional	Whether the model should produce native audio. For wan2.6-i2v-flash this doubles the per-second rate (e.g., 720p+audio is $0.05/s vs $0.025/s silent) — set False for cheaper silent clips. wan2.6-i2v always produces audio regardless of this flag. wan2.6-t2v / wan2.2-i2v-flash / seedance-2-fast never produce audio.
negative_prompt	string	optional	Optional text describing what to AVOID in the output. Honored by Wan and Seedance models.
seed	integer	optional	Random seed for reproducibility (0-2147483647). Omit for random.
shot_type	string	optional	Shot mode: 'single' (continuous) or 'multi' (scene cuts). wan2.6-t2v only. OMIT to use the model default.
style	string	optional	Style preset. Seedance models only. OMIT for no style preset.
camera_motion	string	optional	Camera motion preset. Seedance models only. OMIT for no camera motion.

Raw schema

{
  "type": "object",
  "properties": {
    "prompt": {
      "type": "string",
      "description": "Text description of the video to generate (3-4000 chars)."
    },
    "reference_file_ids": {
      "type": "array",
      "description": "Optional list of up to 12 image file_ids to use as visual references (style, composition). Files must be image MIME types (image/png, image/jpeg, image/webp, image/gif). Get IDs from the [ATTACHMENTS] block, files.search, or search.files.",
      "items": {
        "type": "integer"
      }
    },
    "model": {
      "type": "string",
      "description": "Video model. Recommended: 'wan2.6-i2v-flash' (default, cheap, 720p/1080p, optional audio), 'wan2.6-i2v' (premium, always-on audio), 'wan2.6-t2v' (text-only input, 720p/1080p, no audio), 'wan2.2-i2v-flash' (cheapest, 480p/720p, no audio). Legacy BytePlus: 'seedance-2-fast', 'seedance-2-pro' (720p only).",
      "enum": [
        "wan2.6-i2v-flash",
        "wan2.6-i2v",
        "wan2.6-t2v",
        "wan2.2-i2v-flash",
        "happyhorse-1.0-t2v",
        "happyhorse-1.0-i2v",
        "wan2.2-s2v",
        "omnihuman-1.5",
        "seedance-2-pro"
      ],
      "default": "wan2.6-i2v-flash"
    },
    "duration": {
      "type": "integer",
      "description": "Output video duration in seconds. Single-clip: 5 or 10. Long-form (chained, i2v models only): 15, 20, 30, 45, or 60. Long-form videos are silent (no audio in v1) and use only reference_file_ids[0] when refs are provided.",
      "default": 5
    },
    "resolution": {
      "type": "string",
      "description": "Output resolution. '720p' is the safe default; '1080p' is wan2.6 only; '480p' is wan2.2-i2v-flash only. Per-model support enforced by validation.",
      "enum": [
        "480p",
        "720p",
        "1080p"
      ],
      "default": "720p"
    },
    "aspect_ratio": {
      "type": "string",
      "description": "Output aspect ratio. Wan supports '16:9', '9:16', '1:1'; Seedance also supports '4:3', '3:4', '21:9'. Per-model support enforced by validation.",
      "enum": [
        "16:9",
        "9:16",
        "1:1",
        "4:3",
        "3:4",
        "21:9"
      ],
      "default": "16:9"
    },
    "generate_audio": {
      "type": "boolean",
      "description": "Whether the model should produce native audio. For wan2.6-i2v-flash this doubles the per-second rate (e.g., 720p+audio is $0.05/s vs $0.025/s silent) — set False for cheaper silent clips. wan2.6-i2v always produces audio regardless of this flag. wan2.6-t2v / wan2.2-i2v-flash / seedance-2-fast never produce audio.",
      "default": true
    },
    "negative_prompt": {
      "type": "string",
      "description": "Optional text describing what to AVOID in the output. Honored by Wan and Seedance models."
    },
    "seed": {
      "type": "integer",
      "description": "Random seed for reproducibility (0-2147483647). Omit for random."
    },
    "shot_type": {
      "type": "string",
      "description": "Shot mode: 'single' (continuous) or 'multi' (scene cuts). wan2.6-t2v only. OMIT to use the model default.",
      "enum": [
        "single",
        "multi"
      ]
    },
    "style": {
      "type": "string",
      "description": "Style preset. Seedance models only. OMIT for no style preset.",
      "enum": [
        "cinematic",
        "anime",
        "realistic",
        "3d_render"
      ]
    },
    "camera_motion": {
      "type": "string",
      "description": "Camera motion preset. Seedance models only. OMIT for no camera motion.",
      "enum": [
        "dolly_in",
        "dolly_out",
        "pan_left",
        "pan_right",
        "zoom_in",
        "zoom_out",
        "static"
      ]
    }
  },
  "required": [
    "prompt"
  ]
}

images_search

Searches images in this workspace by visual content using vector embeddings (Voyage multimodal-3). Pass a text description; returns ranked file_ids with cosine scores and presigned download URLs. Up to 50 results.

Parameters5

query	string	required	Text description of what you're looking for (3-4000 chars).
limit	integer	optional	Max number of results.
score_threshold	number	optional	Minimum cosine similarity (0.0 returns all, higher = stricter).
collection_id	integer	optional	Optional — restrict to images attached to this collection. Filter is applied after RAG, so you may get fewer than `limit` results; pass a larger limit to broaden if needed.
mime_type	string	optional	Optional — restrict to a specific image MIME (e.g. "image/png"). Filter is applied after RAG (same caveat as collection_id).

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Text description of what you're looking for (3-4000 chars)."
    },
    "limit": {
      "type": "integer",
      "description": "Max number of results.",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    },
    "score_threshold": {
      "type": "number",
      "description": "Minimum cosine similarity (0.0 returns all, higher = stricter).",
      "minimum": 0,
      "maximum": 1,
      "default": 0.3
    },
    "collection_id": {
      "type": "integer",
      "description": "Optional — restrict to images attached to this collection. Filter is applied after RAG, so you may get fewer than `limit` results; pass a larger limit to broaden if needed."
    },
    "mime_type": {
      "type": "string",
      "description": "Optional — restrict to a specific image MIME (e.g. \"image/png\"). Filter is applied after RAG (same caveat as collection_id)."
    }
  },
  "required": [
    "query"
  ]
}

vision_query

Look at the screen currently being shared in a meeting and answer a question about it. Returns a natural-language answer based on the visual content. Use ONLY when the user explicitly asks about the screen/slide/document being shown.

Parameters2

question	string	required	Question about the shared screen.
image_b64	string	optional	Base64-encoded JPEG image of the screen-share frame.

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "Question about the shared screen.",
      "minimum": 1
    },
    "image_b64": {
      "type": "string",
      "description": "Base64-encoded JPEG image of the screen-share frame."
    }
  },
  "required": [
    "question"
  ]
}

youtube_list_videos

List videos on the connected YouTube channel. Returns id, title, published_at, view_count. Paginate via page_token.

Parameters2

page_token	string	optional	Pagination cursor returned in a previous call's `next_page_token`. Omit for the first page.
max_results	integer	optional	Page size, 1-50. Default 25.

Raw schema

{
  "type": "object",
  "properties": {
    "page_token": {
      "type": "string",
      "description": "Pagination cursor returned in a previous call's `next_page_token`. Omit for the first page."
    },
    "max_results": {
      "type": "integer",
      "description": "Page size, 1-50. Default 25."
    }
  },
  "required": []
}

youtube_list_comments

List comment threads on a YouTube video. Pass video_id (e.g. 'dQw4w9WgXcQ') or channel_ref ('youtube:video:<id>'). Returns top-level comments with inline replies.

Parameters3

video_id	string	required	YouTube videoId — bare 11-char form OR full 'youtube:video:<id>'.
page_token	string	optional	Pagination cursor from a previous call's `next_page_token`.
max_results	integer	optional	Page size, 1-100. Default 25.

Raw schema

{
  "type": "object",
  "properties": {
    "video_id": {
      "type": "string",
      "description": "YouTube videoId — bare 11-char form OR full 'youtube:video:<id>'."
    },
    "page_token": {
      "type": "string",
      "description": "Pagination cursor from a previous call's `next_page_token`."
    },
    "max_results": {
      "type": "integer",
      "description": "Page size, 1-100. Default 25."
    }
  },
  "required": [
    "video_id"
  ]
}

youtube_post_comment_reply

Post a comment on a YouTube video, or reply to an existing comment. Pass video_id for a top-level comment, OR parent_comment_id to reply. AI-disclosure suffix appended automatically when configured.

Parameters3

text	string	required	Comment body. 1-10000 chars. AI-disclosure suffix may be auto-appended.
video_id	string	optional	Bare videoId or 'youtube:video:<id>' — for a top-level comment.
parent_comment_id	string	optional	Bare commentId or 'youtube:comment:<id>' — for a reply.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Comment body. 1-10000 chars. AI-disclosure suffix may be auto-appended."
    },
    "video_id": {
      "type": "string",
      "description": "Bare videoId or 'youtube:video:<id>' — for a top-level comment."
    },
    "parent_comment_id": {
      "type": "string",
      "description": "Bare commentId or 'youtube:comment:<id>' — for a reply."
    }
  },
  "required": [
    "text"
  ]
}

youtube_delete_comment

Permanently delete a YouTube comment by id (or 'youtube:comment:<id>'). Cannot be undone. Costs 50 quota units.

Parameters1

comment_id

string

required

Bare commentId OR 'youtube:comment:<id>'.

Raw schema

{
  "type": "object",
  "properties": {
    "comment_id": {
      "type": "string",
      "description": "Bare commentId OR 'youtube:comment:<id>'."
    }
  },
  "required": [
    "comment_id"
  ]
}

youtube_delete_video

Permanently delete a YouTube video by id (or 'youtube:video:<id>'). Cannot be undone. Costs 50 quota units. Caller must own the channel.

Parameters1

video_id

string

required

Bare videoId OR 'youtube:video:<id>'.

Raw schema

{
  "type": "object",
  "properties": {
    "video_id": {
      "type": "string",
      "description": "Bare videoId OR 'youtube:video:<id>'."
    }
  },
  "required": [
    "video_id"
  ]
}

youtube_update_video

Update title, description, privacy, or tags on a YouTube video. Costs 1600 quota units. Only fields provided are changed.

Parameters5

video_id	string	required	Bare videoId OR 'youtube:video:<id>'.
title	string	optional	New title (max 100 chars). Omit to keep current.
description	string	optional	New description (max 5000 chars). Omit to keep current.
privacy	string	optional	'private', 'unlisted', or 'public'. Omit to keep current.
tags	array	optional	New tags list. Omit to keep current.

Raw schema

{
  "type": "object",
  "properties": {
    "video_id": {
      "type": "string",
      "description": "Bare videoId OR 'youtube:video:<id>'."
    },
    "title": {
      "type": "string",
      "description": "New title (max 100 chars). Omit to keep current."
    },
    "description": {
      "type": "string",
      "description": "New description (max 5000 chars). Omit to keep current."
    },
    "privacy": {
      "type": "string",
      "description": "'private', 'unlisted', or 'public'. Omit to keep current.",
      "enum": [
        "private",
        "unlisted",
        "public"
      ]
    },
    "tags": {
      "type": "array",
      "description": "New tags list. Omit to keep current.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "video_id"
  ]
}

youtube_moderate_comment

Apply a moderation status to a YouTube comment. Allowed status values: heldForReview, published, rejected, spam. Costs 50 quota units.

Parameters2

comment_id	string	required	Bare commentId OR 'youtube:comment:<id>'.
status	string	required	One of: heldForReview, published, rejected, spam.

Raw schema

{
  "type": "object",
  "properties": {
    "comment_id": {
      "type": "string",
      "description": "Bare commentId OR 'youtube:comment:<id>'."
    },
    "status": {
      "type": "string",
      "description": "One of: heldForReview, published, rejected, spam."
    }
  },
  "required": [
    "comment_id",
    "status"
  ]
}

youtube_upload_video

Upload a workspace-owned video file (file_id) to the connected YouTube channel. Returns video_id + thread_id. Costs 1600 quota units. Default privacy is 'private' — pass privacy='public' to publish.

Parameters8

channel_account_id	integer	optional	The connected YouTube channel_account.id. OMIT to auto-resolve the workspace's YouTube account.
file_id	integer	required	Workspace `files.id` of the video to upload. Must be a video/* MIME type and `status='ready'`. Get IDs from the [ATTACHMENTS] block, files.search, or search.files.
title	string	required	Video title (max 100 chars).
description	string	optional	Video description (max 5000 chars). OMIT to upload without a description.
privacy	string	optional	Privacy status. 'private' (default), 'unlisted', or 'public'.
tags	array	optional	Optional list of tag strings (max ~500 chars total).
category_id	string	optional	YouTube category ID (default '22' = People & Blogs). See https://developers.google.com/youtube/v3/docs/videoCategories/list.
made_for_kids	boolean	optional	COPPA flag. OMIT for the standard (non-kids) default.

Raw schema

{
  "type": "object",
  "properties": {
    "channel_account_id": {
      "type": "integer",
      "description": "The connected YouTube channel_account.id. OMIT to auto-resolve the workspace's YouTube account."
    },
    "file_id": {
      "type": "integer",
      "description": "Workspace `files.id` of the video to upload. Must be a video/* MIME type and `status='ready'`. Get IDs from the [ATTACHMENTS] block, files.search, or search.files."
    },
    "title": {
      "type": "string",
      "description": "Video title (max 100 chars)."
    },
    "description": {
      "type": "string",
      "description": "Video description (max 5000 chars). OMIT to upload without a description."
    },
    "privacy": {
      "type": "string",
      "description": "Privacy status. 'private' (default), 'unlisted', or 'public'.",
      "enum": [
        "private",
        "unlisted",
        "public"
      ],
      "default": "private"
    },
    "tags": {
      "type": "array",
      "description": "Optional list of tag strings (max ~500 chars total).",
      "items": {
        "type": "string"
      }
    },
    "category_id": {
      "type": "string",
      "description": "YouTube category ID (default '22' = People & Blogs). See https://developers.google.com/youtube/v3/docs/videoCategories/list.",
      "default": "22"
    },
    "made_for_kids": {
      "type": "boolean",
      "description": "COPPA flag. OMIT for the standard (non-kids) default."
    }
  },
  "required": [
    "file_id",
    "title"
  ]
}

youtube_video_query

Ask Gemini about a YouTube video. Pass a video URL and any prompt — verbatim transcript with timestamps, summary, targeted Q&A about content or visuals, translation, etc. Works on any public/unlisted video.

Parameters2

url	string	required	YouTube video URL. Supported forms: youtube.com/watch?v=…, youtu.be/…, youtube.com/shorts/…, m.youtube.com/watch?v=…. Pass-through to Gemini verbatim.
prompt	string	required	What to ask Gemini about the video. Examples: 'Provide a verbatim transcript with [HH:MM:SS] timestamps.' / 'What is the main claim made in the first 30 seconds?' / 'Describe what's shown on screen at 0:30.' / 'Translate the spoken Spanish to English.'

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "YouTube video URL. Supported forms: youtube.com/watch?v=…, youtu.be/…, youtube.com/shorts/…, m.youtube.com/watch?v=…. Pass-through to Gemini verbatim."
    },
    "prompt": {
      "type": "string",
      "description": "What to ask Gemini about the video. Examples: 'Provide a verbatim transcript with [HH:MM:SS] timestamps.' / 'What is the main claim made in the first 30 seconds?' / 'Describe what's shown on screen at 0:30.' / 'Translate the spoken Spanish to English.'"
    }
  },
  "required": [
    "url",
    "prompt"
  ]
}

instagram_publish_media

Publish a photo (IMAGE) or video (REELS) from workspace files to a connected Instagram Business/Creator account. Returns media_id + permalink. Instagram allows ~25 publishes per day.

Parameters5

file_id	integer	required	Workspace files.id of the photo or video to publish.
caption	string	optional	Post caption (max 2200 chars). OMIT to publish without caption.
media_type	string	optional	'auto' (default, detects from mime), 'image', or 'reels'.
share_to_feed	boolean	optional	For Reels: also show on profile grid (default true).
location_id	string	optional	Facebook Place ID for location tag.

Raw schema

{
  "type": "object",
  "properties": {
    "file_id": {
      "type": "integer",
      "description": "Workspace files.id of the photo or video to publish."
    },
    "caption": {
      "type": "string",
      "description": "Post caption (max 2200 chars). OMIT to publish without caption."
    },
    "media_type": {
      "type": "string",
      "description": "'auto' (default, detects from mime), 'image', or 'reels'.",
      "enum": [
        "auto",
        "image",
        "reels"
      ],
      "default": "auto"
    },
    "share_to_feed": {
      "type": "boolean",
      "description": "For Reels: also show on profile grid (default true).",
      "default": true
    },
    "location_id": {
      "type": "string",
      "description": "Facebook Place ID for location tag."
    }
  },
  "required": [
    "file_id"
  ]
}

instagram_update_media

Update the caption of a published Instagram photo or Reel. Only caption is editable after publish (Instagram limitation).

Parameters2

media_id	string	required	Instagram media ID (from list_media or thread metadata).
caption	string	required	New caption (max 2200 chars).

Raw schema

{
  "type": "object",
  "properties": {
    "media_id": {
      "type": "string",
      "description": "Instagram media ID (from list_media or thread metadata)."
    },
    "caption": {
      "type": "string",
      "description": "New caption (max 2200 chars)."
    }
  },
  "required": [
    "media_id",
    "caption"
  ]
}

instagram_list_media

List photos and Reels on the connected Instagram Business/Creator account. Returns id, caption, media_type, permalink, thumbnail_url, timestamp.

Parameters2

limit	integer	optional	Page size, 1-50. Default 25.
after	string	optional	Pagination cursor from a previous call's next_cursor.

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Page size, 1-50. Default 25."
    },
    "after": {
      "type": "string",
      "description": "Pagination cursor from a previous call's next_cursor."
    }
  },
  "required": []
}

x_publish_post

Publish a post to the connected X (Twitter) account with optional media. Text can include mentions, hashtags, and URLs. Media files are uploaded via v2 chunked upload. Returns tweet_id and URL.

Parameters3

text	string	required	Post text (required). X enforces per-account character limits.
media_file_ids	array	optional	DialogBrain file IDs to attach (optional, max 4 per post).
account_id	string	optional	X account: numeric channel account ID or @handle (optional; defaults to workspace's sole X account).

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Post text (required). X enforces per-account character limits."
    },
    "media_file_ids": {
      "type": "array",
      "description": "DialogBrain file IDs to attach (optional, max 4 per post).",
      "items": {
        "type": "string"
      }
    },
    "account_id": {
      "type": "string",
      "description": "X account: numeric channel account ID or @handle (optional; defaults to workspace's sole X account)."
    }
  },
  "required": [
    "text"
  ]
}

files_info

Get metadata and download URLs for files by their IDs. When to use: - After messages_read_history returns attachment_file_ids - To get a presigned download URL to read a received file Returns: filename, mime_type, byte_size, download_url (1-hour presigned URL).

Parameters1

file_ids

array

required

List of file IDs (max 20)

Raw schema

{
  "type": "object",
  "properties": {
    "file_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "List of file IDs (max 20)"
    }
  },
  "required": [
    "file_ids"
  ]
}

files_get_base64

Download one or more files server-side and return their content as base64-encoded strings. Use this to inspect images, PDFs, or any binary file attached to messages when you cannot access presigned S3 URLs directly. Supports up to 5 files per call, max 15 MB each. For large files batch in groups of 1-2 to avoid oversized responses.

Parameters1

file_ids

array

required

List of file IDs to fetch as base64 (max 5). Get IDs from files.info or message attachment_file_ids.

Raw schema

{
  "type": "object",
  "properties": {
    "file_ids": {
      "type": "array",
      "description": "List of file IDs to fetch as base64 (max 5). Get IDs from files.info or message attachment_file_ids.",
      "items": {
        "type": "integer"
      }
    }
  },
  "required": [
    "file_ids"
  ]
}

files_delete

Permanently delete files from this workspace by their IDs (generated documents, uploads, screenshots, etc.). IRREVERSIBLE: removes the DB record, detaches every reference (knowledge collections, thread pins, message attachments), and deletes the stored blob. There is no undo. Use to clean up leftover / superseded generated files. Only files that belong to this workspace are touched; unknown or other-workspace ids are returned under `not_found`. Max 20 per call.

Parameters1

file_ids

array

required

List of file IDs to permanently delete (max 20).

Raw schema

{
  "type": "object",
  "properties": {
    "file_ids": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "List of file IDs to permanently delete (max 20)."
    }
  },
  "required": [
    "file_ids"
  ]
}

messages_read_history

Read messages from a conversation thread. Use text_contains to find specific messages by content. Returns the most recent messages, including sender info and timestamps. Voice calls: each row carries a `meta` object with allowlisted keys (`event_type` ∈ 'call_started'|'call_ended'|null, `source` ∈ 'voice_transcript'|null, `call_id`, `speaker_display_name`, `duration_seconds`, `outcome`, `direction`) plus per-message `channel`. To find calls without scanning every row, use `calls.list_history` instead. Usage: 1. Get thread_id from threads.list first, OR 2. Use contact_name to auto-resolve thread_id Examples: - User: 'show me messages from chat with [contact]' → read_history(contact_name='[contact]', limit=10) - User: 'last 5 messages from thread 571' → read_history(thread_id=571, limit=5)

Parameters6

thread_id	string	optional	Thread ID to read messages from (e.g., '571' or 'telegram:571'). Optional if contact_name provided.
contact_name	string	optional	Contact/thread name to search for (optional if thread_id provided). Example: 'Jane Smith', 'John Doe'
limit	integer	optional	Maximum number of messages to return (default: 10, max: 100)
offset	integer	optional	Number of messages to skip (for pagination, default: 0)
include_outgoing	boolean	optional	Include messages sent by you (default: true)
text_contains	string	optional	Filter: only return messages containing this text (case-insensitive substring match)

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Thread ID to read messages from (e.g., '571' or 'telegram:571'). Optional if contact_name provided."
    },
    "contact_name": {
      "type": "string",
      "description": "Contact/thread name to search for (optional if thread_id provided). Example: 'Jane Smith', 'John Doe'"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of messages to return (default: 10, max: 100)",
      "minimum": 1,
      "maximum": 100,
      "default": 10
    },
    "offset": {
      "type": "integer",
      "description": "Number of messages to skip (for pagination, default: 0)",
      "minimum": 0
    },
    "include_outgoing": {
      "type": "boolean",
      "description": "Include messages sent by you (default: true)",
      "default": true
    },
    "text_contains": {
      "type": "string",
      "description": "Filter: only return messages containing this text (case-insensitive substring match)"
    }
  },
  "required": []
}

channels_connect_telegram_bot

🤖 Connect a Telegram Bot (Bot API) channel from its bot token. When to use: - After a bot was created via @BotFather and you have its token. - The token alone is sufficient — no Telegram user account is needed. Validates the token, creates the channel account, and registers the webhook so the bot starts receiving messages immediately.

Parameters1

bot_token

string

required

Telegram bot token from @BotFather (e.g. '123456789:ABCdef...').

Raw schema

{
  "type": "object",
  "properties": {
    "bot_token": {
      "type": "string",
      "description": "Telegram bot token from @BotFather (e.g. '123456789:ABCdef...')."
    }
  },
  "required": [
    "bot_token"
  ]
}

threads_update

✏️ Update a conversation thread: rename it, add notes/description, or move to a folder. When to use: - User wants to rename a chat or group - User wants to add notes/context about a conversation - User wants to organize threads into folders For DM threads, renaming also updates the linked contact's display name by default. Requires thread_id from threads.list.

Parameters5

thread_id	string	required	Thread ID from threads.list
title	string	optional	New title for the thread (max 255 chars)
description	string	optional	AI context / notes for this thread. Empty string clears description.
folder_id	integer	optional	Move thread to this folder (null removes from folder)
update_contact	boolean	optional	For DM threads, also rename the linked contact (default: true)

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Thread ID from threads.list"
    },
    "title": {
      "type": "string",
      "description": "New title for the thread (max 255 chars)"
    },
    "description": {
      "type": "string",
      "description": "AI context / notes for this thread. Empty string clears description."
    },
    "folder_id": {
      "type": "integer",
      "description": "Move thread to this folder (null removes from folder)"
    },
    "update_contact": {
      "type": "boolean",
      "description": "For DM threads, also rename the linked contact (default: true)",
      "default": true
    }
  },
  "required": [
    "thread_id"
  ]
}

threads_delete

🗑️ PERMANENTLY delete conversation thread(s) and their messages + user-facing state (tags, assignments, drafts, reminders, RAG chunks). Destructive and NOT undoable — requires confirm=true. Pass thread_id for one, or thread_ids for a bulk delete. Kept intentionally: call history (voice_sessions), usage/billing, traces, and outreach dedup are NOT removed. Note: for a live synced channel (Telegram/WhatsApp) this clears the LOCAL copy; a new inbound can re-create the thread on next sync. For livechat/voice/test/duel threads it's effectively permanent.

Parameters3

thread_id	integer	optional	A single thread ID to delete. Use this OR thread_ids.
thread_ids	array	optional	Multiple thread IDs to delete in one call (bulk). Use this OR thread_id.
confirm	boolean	required	Must be true to actually delete — a safety gate for this destructive action.

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "integer",
      "description": "A single thread ID to delete. Use this OR thread_ids."
    },
    "thread_ids": {
      "type": "array",
      "description": "Multiple thread IDs to delete in one call (bulk). Use this OR thread_id.",
      "items": {
        "type": "integer"
      }
    },
    "confirm": {
      "type": "boolean",
      "description": "Must be true to actually delete — a safety gate for this destructive action."
    }
  },
  "required": [
    "confirm"
  ]
}

folders_create

📁 Create a new inbox folder to organize threads. When to use: - User wants to create a folder to group related conversations - User wants to organize threads by topic, project, or contact type After creating a folder, use threads.update with folder_id to move threads into it.

Parameters2

name	string	required	Folder name (max 100 chars)
icon	string	optional	Emoji icon for the folder (max 10 chars, optional)

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Folder name (max 100 chars)"
    },
    "icon": {
      "type": "string",
      "description": "Emoji icon for the folder (max 10 chars, optional)"
    }
  },
  "required": [
    "name"
  ]
}

folders_delete

🗑️ Delete an inbox folder. Threads inside become unfiled (not deleted). When to use: - User wants to remove a folder they no longer need - User wants to clean up their inbox organization Threads inside the folder are NOT deleted — they simply move back to the inbox.

Parameters1

folder_id

integer

required

ID of the folder to delete

Raw schema

{
  "type": "object",
  "properties": {
    "folder_id": {
      "type": "integer",
      "description": "ID of the folder to delete"
    }
  },
  "required": [
    "folder_id"
  ]
}

ai_tags_list

List all personal AI tags. AI tags are automatic message filters: the system runs a lightweight classifier on every incoming message and applies matching tags to threads. This lets AI agents skip expensive full analysis on most messages — they only act on threads that match relevant tags, dramatically cutting LLM costs. When to use: - Check which auto-classification filters exist before creating one - Get tag IDs for add_to_thread / remove_from_thread - See how many threads each tag currently matches Returns all tags with thread counts (non-archived, included threads only).

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

ai_tags_create

Create a new AI tag (automatic message filter). AI tags are lightweight classifiers that run on every incoming message. When a message matches the tag's description/criteria, the thread is automatically labelled — so AI agents can cheaply pre-filter threads instead of running full LLM analysis on everything. Good descriptions are the key: they tell the classifier exactly when to apply this tag. When to use: - User wants to auto-classify incoming messages (e.g. bug reports, sales leads, support requests) - User wants to reduce AI agent costs by pre-filtering threads by topic or intent Tips for the description field: - Be specific: 'Messages reporting errors, crashes, or unexpected behavior in the product' - Include examples of what qualifies and what doesn't Limit: 20 active personal tags / 50 active team tags.

Parameters4

name	string	required	Tag name (max 100 chars)
description	string	optional	Classifier prompt: describe exactly when this tag should be applied to a thread. The more specific, the better the auto-classification accuracy. E.g. 'Messages reporting software errors, crashes, or unexpected behavior'. Max 500 chars.
icon	string	optional	Emoji icon for the tag (max 10 chars, optional)
color	string	optional	Tailwind color key for the tag badge. Allowed: amber, blue, green, red, purple, yellow, slate. OMIT to use the default color.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Tag name (max 100 chars)"
    },
    "description": {
      "type": "string",
      "description": "Classifier prompt: describe exactly when this tag should be applied to a thread. The more specific, the better the auto-classification accuracy. E.g. 'Messages reporting software errors, crashes, or unexpected behavior'. Max 500 chars."
    },
    "icon": {
      "type": "string",
      "description": "Emoji icon for the tag (max 10 chars, optional)"
    },
    "color": {
      "type": "string",
      "description": "Tailwind color key for the tag badge. Allowed: amber, blue, green, red, purple, yellow, slate. OMIT to use the default color.",
      "enum": [
        "amber",
        "blue",
        "green",
        "purple",
        "red",
        "slate",
        "yellow"
      ]
    }
  },
  "required": [
    "name"
  ]
}

ai_tags_update

Update an existing personal AI tag's name, description, icon, color, or active state. When to use: - User wants to rename a tag - User wants to change a tag's icon, color, or description - User wants to enable or disable a tag Provide only the fields you want to change. At least one field is required.

Parameters6

tag_id	integer	required	ID of the tag to update
name	string	optional	New tag name (max 100 chars, optional)
description	string	optional	New LLM hint (max 500 chars; empty string clears it, optional)
icon	string	optional	New emoji icon (max 10 chars, optional)
color	string	optional	New color key. Allowed: amber, blue, green, red, purple, yellow, slate. OMIT to leave the color unchanged.
is_active	boolean	optional	Enable (true) or disable (false) the tag. OMIT to leave the active flag unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "tag_id": {
      "type": "integer",
      "description": "ID of the tag to update"
    },
    "name": {
      "type": "string",
      "description": "New tag name (max 100 chars, optional)"
    },
    "description": {
      "type": "string",
      "description": "New LLM hint (max 500 chars; empty string clears it, optional)"
    },
    "icon": {
      "type": "string",
      "description": "New emoji icon (max 10 chars, optional)"
    },
    "color": {
      "type": "string",
      "description": "New color key. Allowed: amber, blue, green, red, purple, yellow, slate. OMIT to leave the color unchanged.",
      "enum": [
        "amber",
        "blue",
        "green",
        "purple",
        "red",
        "slate",
        "yellow"
      ]
    },
    "is_active": {
      "type": "boolean",
      "description": "Enable (true) or disable (false) the tag. OMIT to leave the active flag unchanged."
    }
  },
  "required": [
    "tag_id"
  ]
}

ai_tags_delete

Delete a personal AI tag. All thread associations are removed automatically. When to use: - User wants to permanently remove a tag they no longer need This cannot be undone. Threads are NOT deleted — they just lose this tag.

Parameters1

tag_id

integer

required

ID of the tag to delete

Raw schema

{
  "type": "object",
  "properties": {
    "tag_id": {
      "type": "integer",
      "description": "ID of the tag to delete"
    }
  },
  "required": [
    "tag_id"
  ]
}

ai_tags_add_to_thread

Apply one or more AI tags to a thread (manually). When to use: - User wants to label a conversation with one or more tags - User asks to categorize or tag a thread Provide the thread_id (integer) and an array of tag_ids to apply. If a tag is already applied it will be updated to is_manual=true.

Parameters2

thread_id	integer	required	ID of the thread to tag
tag_ids	array	required	Array of tag IDs to apply (1–20 IDs)

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "integer",
      "description": "ID of the thread to tag"
    },
    "tag_ids": {
      "type": "array",
      "description": "Array of tag IDs to apply (1–20 IDs)",
      "items": {
        "type": "integer"
      }
    }
  },
  "required": [
    "thread_id",
    "tag_ids"
  ]
}

ai_tags_remove_from_thread

Remove a specific AI tag from a thread. When to use: - User wants to un-label or remove a specific tag from a conversation - User wants to correct an incorrectly applied tag Provide both thread_id and tag_id.

Parameters2

thread_id	integer	required	ID of the thread to remove the tag from
tag_id	integer	required	ID of the tag to remove

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "integer",
      "description": "ID of the thread to remove the tag from"
    },
    "tag_id": {
      "type": "integer",
      "description": "ID of the tag to remove"
    }
  },
  "required": [
    "thread_id",
    "tag_id"
  ]
}

ai_filters_list

List all AI filters for the current workspace. AI filters are semantic intent-based message filters that use embeddings (vector representations) to detect whether an incoming message matches a specific intent or topic. Unlike keyword filters, they understand meaning: 'I need help with my order' and 'my package hasn't arrived' both match a 'shipping support' filter even without shared keywords. Each filter stores a reference embedding of its description. When a message arrives, its embedding is compared via cosine similarity against the filter's reference vector. If the similarity exceeds the threshold, the filter matches. When to use: - Check which semantic filters already exist before creating a new one - Get filter IDs for use in trigger conditions - Review thresholds and active status of existing filters Returns all filters with id, name, description, threshold, and is_active.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

ai_filters_create

Create a new AI filter for semantic intent-based message matching. AI filters use vector embeddings (via Voyage AI) to detect whether an incoming message matches a specific intent or topic. The filter's description is embedded as a reference vector at creation time. When a message arrives, its embedding is compared against this reference using cosine similarity. The description field is the most important part — it becomes the reference embedding that all incoming messages are compared against. Write it as a clear statement of what kind of messages should match: - 'Customer asking about pricing, subscription plans, or billing' - 'User reporting a bug, crash, or unexpected behavior in the product' - 'Inbound sales lead expressing interest in purchasing or trialing' The threshold controls sensitivity: 0.5 is a balanced default, lower values (0.3) cast a wider net, higher values (0.8) require closer matches. Note: This tool calls the Voyage AI embedding API to generate the reference vector.

Parameters3

name	string	required	Filter name — a short, human-readable label (max 100 chars)
description	string	required	Reference text that defines what messages should match this filter. This text is embedded as a vector and used for cosine similarity comparison against all incoming messages. Be specific and descriptive — the quality of this text directly determines filter accuracy. E.g. 'Customer asking about pricing, subscription costs, or billing issues'. Max 500 chars.
threshold	number	optional	Cosine similarity threshold for a message to be considered a match. Range 0.1–1.0. Default 0.50. Lower values (e.g. 0.3) are more permissive and catch more messages. Higher values (e.g. 0.8) require closer semantic similarity.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Filter name — a short, human-readable label (max 100 chars)"
    },
    "description": {
      "type": "string",
      "description": "Reference text that defines what messages should match this filter. This text is embedded as a vector and used for cosine similarity comparison against all incoming messages. Be specific and descriptive — the quality of this text directly determines filter accuracy. E.g. 'Customer asking about pricing, subscription costs, or billing issues'. Max 500 chars."
    },
    "threshold": {
      "type": "number",
      "description": "Cosine similarity threshold for a message to be considered a match. Range 0.1–1.0. Default 0.50. Lower values (e.g. 0.3) are more permissive and catch more messages. Higher values (e.g. 0.8) require closer semantic similarity.",
      "minimum": 0.1,
      "maximum": 1,
      "default": 0.5
    }
  },
  "required": [
    "name",
    "description"
  ]
}

ai_filters_update

Update an existing AI filter's name, description, threshold, or active state. When to use: - User wants to rename a filter - User wants to refine the filter description to improve match accuracy - User wants to adjust the similarity threshold (higher = stricter matching) - User wants to enable or disable a filter without deleting it Provide only the fields you want to change. At least one field is required. Note: If the description is changed, this tool calls the Voyage AI embedding API to re-generate the reference vector with the new description text.

Parameters5

filter_id	integer	required	ID of the filter to update
name	string	optional	New filter name (max 100 chars, optional)
description	string	optional	New reference description text. If changed, the Voyage AI embedding API is called to re-generate the reference vector. Max 500 chars. Optional.
threshold	number	optional	New cosine similarity threshold. Range 0.1–1.0. Optional.
is_active	boolean	optional	Enable (true) or disable (false) the filter. OMIT to leave the active flag unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "description": "ID of the filter to update"
    },
    "name": {
      "type": "string",
      "description": "New filter name (max 100 chars, optional)"
    },
    "description": {
      "type": "string",
      "description": "New reference description text. If changed, the Voyage AI embedding API is called to re-generate the reference vector. Max 500 chars. Optional."
    },
    "threshold": {
      "type": "number",
      "description": "New cosine similarity threshold. Range 0.1–1.0. Optional.",
      "minimum": 0.1,
      "maximum": 1
    },
    "is_active": {
      "type": "boolean",
      "description": "Enable (true) or disable (false) the filter. OMIT to leave the active flag unchanged."
    }
  },
  "required": [
    "filter_id"
  ]
}

ai_filters_delete

Permanently delete an AI filter. When to use: - User wants to remove a filter they no longer need This action cannot be undone. Any triggers that reference this filter by ID will no longer match it — review and update those triggers after deletion.

Parameters1

filter_id

integer

required

ID of the filter to delete

Raw schema

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "description": "ID of the filter to delete"
    }
  },
  "required": [
    "filter_id"
  ]
}

ai_filters_test

Test a message against an AI filter to check whether it would match. This tool embeds the provided message using Voyage AI and computes the cosine similarity between the message vector and the filter's stored reference vector. It returns the similarity score, whether the message would match (similarity >= threshold), and the filter's threshold value. Use this to: - Verify a filter works as intended before using it in a trigger - Tune the threshold by testing borderline messages - Debug why a message did or did not match a filter in production Returns: {similarity: float, matched: bool, threshold: float} Note: This tool calls the Voyage AI embedding API to embed the test message.

Parameters2

filter_id	integer	required	ID of the filter to test against
message	string	required	The message text to test. This is embedded and compared against the filter's reference vector via cosine similarity.

Raw schema

{
  "type": "object",
  "properties": {
    "filter_id": {
      "type": "integer",
      "description": "ID of the filter to test against"
    },
    "message": {
      "type": "string",
      "description": "The message text to test. This is embedded and compared against the filter's reference vector via cosine similarity."
    }
  },
  "required": [
    "filter_id",
    "message"
  ]
}

messages_send

Send a message to a thread, channel, or contact. Supports Telegram, Email, LinkedIn, and other connected channels. For LinkedIn posts (comment_thread kind), this posts a comment on the post. Can automatically resolve recipients and channels when not specified. Can send files/images/documents as attachments — pass `attachments=[file_id, ...]` with integer file IDs obtained from collections.list_files, search.files, or files.search. `text` is optional when attachments are provided.

Parameters8

thread_id	string	optional	Target thread. OMIT to reply in the same chat you received the triggering message from — the backend defaults to the current thread. Pass an explicit value ONLY to reply in a DIFFERENT thread, and only use: (a) a numeric DB thread id from search.threads, or (b) a channel_ref like 'telegram:-12345'. NEVER use a chat-type word (dm, group, channel, livechat) — those are category labels from the SITUATION block, not ids.
recipient_name	string	optional	Name of person to send to (e.g., 'Jane', 'John'). Tool will auto-resolve channel. Optional if thread_id provided.
recipient_username	string	optional	Telegram @username to message (e.g. '@some_username'). Use this for a Telegram user NOT yet in contacts — it resolves the handle, adds the contact, and creates the thread. Telegram only; for existing contacts prefer thread_id or recipient_name.
text	string	optional	Message text to send. Optional if attachments provided.
reply_to_message_id	string	optional	ID of message to reply to (optional)
format	string	optional	Message format
attachments	array	optional	Array of integer file IDs to send as attachments (images, documents, any files). Get file IDs from collections.list_files (field `file_id`), search.files (field `file_id`), or files.search. Example: [302237]. The file must already exist in the workspace (status=ready) — no separate upload step needed. When attachments are provided, `text` becomes optional (a caption can be included alongside).
silent	boolean	optional	Send without notification

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Target thread. OMIT to reply in the same chat you received the triggering message from — the backend defaults to the current thread. Pass an explicit value ONLY to reply in a DIFFERENT thread, and only use: (a) a numeric DB thread id from search.threads, or (b) a channel_ref like 'telegram:-12345'. NEVER use a chat-type word (dm, group, channel, livechat) — those are category labels from the SITUATION block, not ids."
    },
    "recipient_name": {
      "type": "string",
      "description": "Name of person to send to (e.g., 'Jane', 'John'). Tool will auto-resolve channel. Optional if thread_id provided."
    },
    "recipient_username": {
      "type": "string",
      "description": "Telegram @username to message (e.g. '@some_username'). Use this for a Telegram user NOT yet in contacts — it resolves the handle, adds the contact, and creates the thread. Telegram only; for existing contacts prefer thread_id or recipient_name."
    },
    "text": {
      "type": "string",
      "description": "Message text to send. Optional if attachments provided.",
      "maximum": 4096
    },
    "reply_to_message_id": {
      "type": "string",
      "description": "ID of message to reply to (optional)"
    },
    "format": {
      "type": "string",
      "description": "Message format",
      "enum": [
        "text",
        "markdown",
        "html"
      ],
      "default": "text"
    },
    "attachments": {
      "type": "array",
      "description": "Array of integer file IDs to send as attachments (images, documents, any files). Get file IDs from collections.list_files (field `file_id`), search.files (field `file_id`), or files.search. Example: [302237]. The file must already exist in the workspace (status=ready) — no separate upload step needed. When attachments are provided, `text` becomes optional (a caption can be included alongside).",
      "items": {
        "type": "integer"
      }
    },
    "silent": {
      "type": "boolean",
      "description": "Send without notification"
    }
  },
  "required": []
}

messages_send_email

Compose and send an email — with subject, CC/BCC, and attachments. Use for email; for chat messages (Telegram/WhatsApp/livechat) use messages.send instead.

Parameters6

recipient_email	string	optional	Recipient email address (e.g. 'john@example.com'). Provide to start a new email thread; OMIT to reply in the current email thread.
subject	string	optional	Email subject line. Required for new emails; for replies it auto-generates 'Re: ...' when omitted.
text	string	optional	Email body.
attachments	array	optional	Array of integer file IDs to attach.
cc	array	optional	Email addresses to CC. OMIT to skip.
bcc	array	optional	Email addresses to BCC. OMIT to skip.

Raw schema

{
  "type": "object",
  "properties": {
    "recipient_email": {
      "type": "string",
      "description": "Recipient email address (e.g. 'john@example.com'). Provide to start a new email thread; OMIT to reply in the current email thread."
    },
    "subject": {
      "type": "string",
      "description": "Email subject line. Required for new emails; for replies it auto-generates 'Re: ...' when omitted."
    },
    "text": {
      "type": "string",
      "description": "Email body."
    },
    "attachments": {
      "type": "array",
      "description": "Array of integer file IDs to attach.",
      "items": {
        "type": "integer"
      }
    },
    "cc": {
      "type": "array",
      "description": "Email addresses to CC. OMIT to skip.",
      "items": {
        "type": "string"
      }
    },
    "bcc": {
      "type": "array",
      "description": "Email addresses to BCC. OMIT to skip.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": []
}

messages_delete

Delete a message from a thread. Supports Telegram, WhatsApp, and other connected channels. Note: Some channels have time limits on message deletion.

Parameters2

thread_id	string	required	Thread/channel ID containing the message
message_id	string	required	ID of the message to delete

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Thread/channel ID containing the message"
    },
    "message_id": {
      "type": "string",
      "description": "ID of the message to delete"
    }
  },
  "required": [
    "thread_id",
    "message_id"
  ]
}

messages_edit

Edit the text of a message you already sent, in place. Supported on Telegram, WhatsApp, LiveChat, Max.ru, LINE, WeChat and similar channels; NOT supported on Gmail, Instagram, or LinkedIn (their platforms forbid editing) — those return an explicit error. Note: channels impose their own limits (own messages only, edit time windows such as ~48h on Telegram / ~15min on WhatsApp). Get the message_id from messages.read_history (each row's id).

Parameters3

thread_id	string	required	Thread ID containing the message (numeric DB id or channel_ref like 'telegram:-100123').
message_id	string	required	ID of the message to edit (from messages.read_history).
new_text	string	required	Replacement text for the message.

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Thread ID containing the message (numeric DB id or channel_ref like 'telegram:-100123')."
    },
    "message_id": {
      "type": "string",
      "description": "ID of the message to edit (from messages.read_history)."
    },
    "new_text": {
      "type": "string",
      "description": "Replacement text for the message."
    }
  },
  "required": [
    "thread_id",
    "message_id",
    "new_text"
  ]
}

messages_forward

Forward a message from one thread to another. Supports native Telegram forwarding (preserves original sender attribution) and text-based forwarding for cross-channel scenarios.

Parameters4

source_thread_id	string	required	Thread containing the message to forward (e.g., 'telegram:123456' or numeric DB ID)
source_message_id	string	required	ID of the message to forward
dest_thread_id	string	optional	Destination thread to forward into. Provide at least one of dest_thread_id or recipient_name. To forward into the active conversation, pass the current thread_id. (If both are provided, dest_thread_id wins and recipient_name is ignored.)
recipient_name	string	optional	Name of person to forward to (channel auto-resolved). Provide at least one of dest_thread_id or recipient_name. Use only when forwarding to a different contact than the current conversation.

Raw schema

{
  "type": "object",
  "properties": {
    "source_thread_id": {
      "type": "string",
      "description": "Thread containing the message to forward (e.g., 'telegram:123456' or numeric DB ID)"
    },
    "source_message_id": {
      "type": "string",
      "description": "ID of the message to forward"
    },
    "dest_thread_id": {
      "type": "string",
      "description": "Destination thread to forward into. Provide at least one of dest_thread_id or recipient_name. To forward into the active conversation, pass the current thread_id. (If both are provided, dest_thread_id wins and recipient_name is ignored.)"
    },
    "recipient_name": {
      "type": "string",
      "description": "Name of person to forward to (channel auto-resolved). Provide at least one of dest_thread_id or recipient_name. Use only when forwarding to a different contact than the current conversation."
    }
  },
  "required": [
    "source_thread_id",
    "source_message_id"
  ]
}

knowledge_query

Answer questions using knowledge base (uploaded documents, handbooks, files). Use for QUESTIONS that need an answer synthesized from documents or messages. Returns an evidence pack with source citations, KG entities, and extracted numbers. Modes: - 'auto' (default): Smart routing — works for most questions - 'rag': Semantic search across documents & messages - 'entity': Entity-centric queries (e.g., 'Tell me about [entity]') - 'relationship': Two-entity queries (e.g., 'How is [entity A] related to [entity B]?') Examples: - 'What did we discuss about the budget?' → knowledge.query - 'Tell me about [entity]' → knowledge.query mode=entity - 'How is [A] related to [B]?' → knowledge.query mode=relationship NOT for finding/listing files, threads, or links — use search.files / search.threads / search.links for that.

Parameters8

question	string	required	The question to answer from user's knowledge base. Required even for entity queries.
max_sources	integer	optional	Maximum number of sources to consider (1-10)
include_relationships	boolean	optional	Include KG relationships in answer (default: true for entity mode)
file_ids	array	optional	Specific file IDs to search within (for pinned files)
thread_id	string	optional	Limit search to a specific thread/chat
date_from	string	optional	Filter messages from this date (ISO format: YYYY-MM-DD). Use for time-based queries like 'this week', 'last month'.
date_to	string	optional	Filter messages until this date (ISO format: YYYY-MM-DD).
needs_aggregation	boolean	optional	True if query asks for totals/sums/counts.

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The question to answer from user's knowledge base. Required even for entity queries.",
      "minimum": 1
    },
    "max_sources": {
      "type": "integer",
      "description": "Maximum number of sources to consider (1-10)",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    },
    "include_relationships": {
      "type": "boolean",
      "description": "Include KG relationships in answer (default: true for entity mode)",
      "default": true
    },
    "file_ids": {
      "type": "array",
      "description": "Specific file IDs to search within (for pinned files)",
      "items": {
        "type": "string"
      }
    },
    "thread_id": {
      "type": "string",
      "description": "Limit search to a specific thread/chat"
    },
    "date_from": {
      "type": "string",
      "description": "Filter messages from this date (ISO format: YYYY-MM-DD). Use for time-based queries like 'this week', 'last month'."
    },
    "date_to": {
      "type": "string",
      "description": "Filter messages until this date (ISO format: YYYY-MM-DD)."
    },
    "needs_aggregation": {
      "type": "boolean",
      "description": "True if query asks for totals/sums/counts."
    }
  },
  "required": [
    "question"
  ]
}

kg_find_entity

Find an entity by name in the Knowledge Graph. USE WHEN user mentions a person, project, company by name and you need: - To resolve a name to entity_id for subsequent queries - 'Кто работает над X?' → find X first - 'Расскажи про Y' → find Y first RETURNS entity_id for use in kg.get_relationships or kg.explore. ALWAYS use this as the FIRST step in KG query chains.

Parameters3

name	string	required	Entity name to search for. Can be in any language (Russian, English, etc.) - transliteration is automatic.
entity_type	string	optional	Filter by entity type: - 'person': People, contacts - 'project': Projects, tasks - 'organization': Companies, teams - 'event': Meetings, deadlines - 'topic': Discussion topics - 'location': Places, addresses - 'document': Files, documents OMIT to include all entity types.
limit	integer	optional	Maximum results to return (1-10). Default: 5

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Entity name to search for. Can be in any language (Russian, English, etc.) - transliteration is automatic."
    },
    "entity_type": {
      "type": "string",
      "description": "Filter by entity type:\n- 'person': People, contacts\n- 'project': Projects, tasks\n- 'organization': Companies, teams\n- 'event': Meetings, deadlines\n- 'topic': Discussion topics\n- 'location': Places, addresses\n- 'document': Files, documents\nOMIT to include all entity types.",
      "enum": [
        "person",
        "project",
        "organization",
        "event",
        "topic",
        "location",
        "document"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Maximum results to return (1-10). Default: 5",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    }
  },
  "required": [
    "name"
  ]
}

kg_get_relationships

Get relationships for a specific entity from Knowledge Graph. USE WHEN: - 'Кто работает над X?' - filter by works_on - 'С кем общался Y?' - filter by discussed_with - 'Кто из компании Z?' - filter by member_of - 'Что связано с W?' - no filter, get all REQUIRES: entity_id from previous kg.find_entity step. Use: {{step_N.entity_id}} where N is the find_entity step number.

Parameters4

entity_id	string	required	Entity ID from kg.find_entity step. Use {{step_N.entity_id}} reference.
relation_types	array	optional	Filter by relationship types (optional): People: works_on, works_for, member_of, manages, knows, client_of, provides_service Communication: discussed_with, participated_in, mentioned_in Org/Project: developed_by, funded_by, partnered_with, integrates_with, depends_on, part_of Document: issued_by, issued_to, signed_by, authored_by Other: uses, located_in, about, follows, owns, related_to
direction	string	optional	Relationship direction: - 'outgoing': Entity → Others - 'incoming': Others → Entity - 'both': All relationships (default)
limit	integer	optional	Maximum relationships to return (1-50). Default: 20

Raw schema

{
  "type": "object",
  "properties": {
    "entity_id": {
      "type": "string",
      "description": "Entity ID from kg.find_entity step. Use {{step_N.entity_id}} reference."
    },
    "relation_types": {
      "type": "array",
      "description": "Filter by relationship types (optional):\nPeople: works_on, works_for, member_of, manages, knows, client_of, provides_service\nCommunication: discussed_with, participated_in, mentioned_in\nOrg/Project: developed_by, funded_by, partnered_with, integrates_with, depends_on, part_of\nDocument: issued_by, issued_to, signed_by, authored_by\nOther: uses, located_in, about, follows, owns, related_to",
      "items": {
        "type": "string"
      }
    },
    "direction": {
      "type": "string",
      "description": "Relationship direction:\n- 'outgoing': Entity → Others\n- 'incoming': Others → Entity\n- 'both': All relationships (default)",
      "enum": [
        "incoming",
        "outgoing",
        "both"
      ],
      "default": "both"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum relationships to return (1-50). Default: 20",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    }
  },
  "required": [
    "entity_id"
  ]
}

calendar_create_event

Create a new event in Google Calendar. Specify the title, start time, end time, and optionally invite attendees. Use ISO 8601 format for dates (e.g., 2024-12-15T14:00:00).

Parameters13

summary	string	optional	Event title/summary. Required. Also accepts 'title' as alias.
title	string	optional	Alias for summary - event title.
start	string	optional	Event start time in ISO 8601 format (e.g., 2024-12-15T14:00:00). Also accepts 'start_time' as alias.
start_time	string	optional	Alias for start - event start time in ISO 8601 format.
end	string	optional	Event end time in ISO 8601 format. If not provided, defaults to 1 hour after start. Also accepts 'end_time' as alias.
end_time	string	optional	Alias for end - event end time.
description	string	optional	Event description/notes.
location	string	optional	Event location (physical address or virtual meeting link).
attendees	array	optional	List of attendee email addresses to invite.
calendar_id	string	optional	Calendar ID to create the event in. OMIT to use the agent's configured default calendar (or primary).
timezone	string	optional	Timezone for the event (e.g., 'America/New_York', 'UTC').
add_google_meet	boolean	optional	If true, automatically creates a Google Meet link for the event. OMIT to skip Meet link.
conference_data	object	optional	Conference data for Google Meet. Alternative to add_google_meet flag.

Raw schema

{
  "type": "object",
  "properties": {
    "summary": {
      "type": "string",
      "description": "Event title/summary. Required. Also accepts 'title' as alias."
    },
    "title": {
      "type": "string",
      "description": "Alias for summary - event title."
    },
    "start": {
      "type": "string",
      "description": "Event start time in ISO 8601 format (e.g., 2024-12-15T14:00:00). Also accepts 'start_time' as alias."
    },
    "start_time": {
      "type": "string",
      "description": "Alias for start - event start time in ISO 8601 format."
    },
    "end": {
      "type": "string",
      "description": "Event end time in ISO 8601 format. If not provided, defaults to 1 hour after start. Also accepts 'end_time' as alias."
    },
    "end_time": {
      "type": "string",
      "description": "Alias for end - event end time."
    },
    "description": {
      "type": "string",
      "description": "Event description/notes."
    },
    "location": {
      "type": "string",
      "description": "Event location (physical address or virtual meeting link)."
    },
    "attendees": {
      "type": "array",
      "description": "List of attendee email addresses to invite.",
      "items": {
        "type": "string"
      }
    },
    "calendar_id": {
      "type": "string",
      "description": "Calendar ID to create the event in. OMIT to use the agent's configured default calendar (or primary)."
    },
    "timezone": {
      "type": "string",
      "description": "Timezone for the event (e.g., 'America/New_York', 'UTC')."
    },
    "add_google_meet": {
      "type": "boolean",
      "description": "If true, automatically creates a Google Meet link for the event. OMIT to skip Meet link."
    },
    "conference_data": {
      "type": "object",
      "description": "Conference data for Google Meet. Alternative to add_google_meet flag."
    }
  },
  "required": []
}

calendar_list_events

List events from Google Calendar. Shows upcoming events by default. Can filter by date range and search query.

Parameters5

calendar_id	string	optional	Calendar ID to list events from. OMIT to use the agent's configured default calendar (or primary).
date_from	string	optional	Start date/time to query (YYYY-MM-DD or ISO 8601 format). Defaults to now. Alias: time_min.
date_to	string	optional	End date/time to query (YYYY-MM-DD or ISO 8601 format). Defaults to 7 days from now. Alias: time_max.
max_results	integer	optional	Maximum number of events to return.
query	string	optional	Free text search query to filter events.

Raw schema

{
  "type": "object",
  "properties": {
    "calendar_id": {
      "type": "string",
      "description": "Calendar ID to list events from. OMIT to use the agent's configured default calendar (or primary)."
    },
    "date_from": {
      "type": "string",
      "description": "Start date/time to query (YYYY-MM-DD or ISO 8601 format). Defaults to now. Alias: time_min."
    },
    "date_to": {
      "type": "string",
      "description": "End date/time to query (YYYY-MM-DD or ISO 8601 format). Defaults to 7 days from now. Alias: time_max."
    },
    "max_results": {
      "type": "integer",
      "description": "Maximum number of events to return.",
      "default": 25
    },
    "query": {
      "type": "string",
      "description": "Free text search query to filter events."
    }
  },
  "required": []
}

calendar_update_event

Update an existing event in Google Calendar. Can modify title, time, location, description, and attendees. Only specified fields will be updated.

Parameters8

event_id	string	required	ID of the event to update. Required.
summary	string	optional	New event title/summary. Optional.
start	string	optional	New start time in ISO 8601 format. Optional.
end	string	optional	New end time in ISO 8601 format. Optional.
description	string	optional	New event description. Optional.
location	string	optional	New event location. Optional.
attendees	array	optional	New list of attendee emails. Replaces existing attendees.
calendar_id	string	optional	Calendar ID containing the event. OMIT to use the agent's configured default calendar (or primary).

Raw schema

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "ID of the event to update. Required."
    },
    "summary": {
      "type": "string",
      "description": "New event title/summary. Optional."
    },
    "start": {
      "type": "string",
      "description": "New start time in ISO 8601 format. Optional."
    },
    "end": {
      "type": "string",
      "description": "New end time in ISO 8601 format. Optional."
    },
    "description": {
      "type": "string",
      "description": "New event description. Optional."
    },
    "location": {
      "type": "string",
      "description": "New event location. Optional."
    },
    "attendees": {
      "type": "array",
      "description": "New list of attendee emails. Replaces existing attendees.",
      "items": {
        "type": "string"
      }
    },
    "calendar_id": {
      "type": "string",
      "description": "Calendar ID containing the event. OMIT to use the agent's configured default calendar (or primary)."
    }
  },
  "required": [
    "event_id"
  ]
}

calendar_delete_event

Delete an event from Google Calendar. This action cannot be undone. Use with caution.

Parameters3

event_id	string	required	ID of the event to delete. Required.
calendar_id	string	optional	Calendar ID containing the event. OMIT to use the agent's configured default calendar (or primary).
send_notifications	boolean	optional	Whether to send cancellation notifications to attendees.

Raw schema

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "description": "ID of the event to delete. Required."
    },
    "calendar_id": {
      "type": "string",
      "description": "Calendar ID containing the event. OMIT to use the agent's configured default calendar (or primary)."
    },
    "send_notifications": {
      "type": "boolean",
      "description": "Whether to send cancellation notifications to attendees.",
      "default": true
    }
  },
  "required": [
    "event_id"
  ]
}

calendar_check_availability

Check when you have free time in Google Calendar. Shows busy periods and free slots in a given time range. Useful for finding meeting times or checking schedule conflicts.

Parameters5

start_time	string	optional	Start date/time to check availability (YYYY-MM-DD or ISO 8601). Defaults to start of today.
end_time	string	optional	End date/time to check availability (YYYY-MM-DD or ISO 8601). Defaults to end of start_time day, or 7 days from now.
calendar_id	string	optional	Calendar ID to check. OMIT to use the agent's configured default calendar (or primary).
working_hours_only	boolean	optional	If true, only show free slots during working hours (9 AM - 6 PM). OMIT to show all free time (the default).
min_duration_minutes	integer	optional	Minimum duration in minutes for free slots. Filters out short gaps. Default: 30 minutes.

Raw schema

{
  "type": "object",
  "properties": {
    "start_time": {
      "type": "string",
      "description": "Start date/time to check availability (YYYY-MM-DD or ISO 8601). Defaults to start of today."
    },
    "end_time": {
      "type": "string",
      "description": "End date/time to check availability (YYYY-MM-DD or ISO 8601). Defaults to end of start_time day, or 7 days from now."
    },
    "calendar_id": {
      "type": "string",
      "description": "Calendar ID to check. OMIT to use the agent's configured default calendar (or primary)."
    },
    "working_hours_only": {
      "type": "boolean",
      "description": "If true, only show free slots during working hours (9 AM - 6 PM). OMIT to show all free time (the default)."
    },
    "min_duration_minutes": {
      "type": "integer",
      "description": "Minimum duration in minutes for free slots. Filters out short gaps. Default: 30 minutes.",
      "default": 30
    }
  },
  "required": []
}

web_search

Search the web for current information, news, facts, prices, or events. Use this when the user asks about something that requires up-to-date information from the internet, or when internal knowledge base doesn't have the answer. Examples: recent news, stock prices, weather, product information, current events.

Parameters3

query	string	required	Search query - what to search for on the web.
num_results	integer	optional	Number of results to return (1-10).
search_type	string	optional	Type of search: 'search' for general web, 'news' for news articles.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search query - what to search for on the web."
    },
    "num_results": {
      "type": "integer",
      "description": "Number of results to return (1-10).",
      "minimum": 1,
      "maximum": 10,
      "default": 5
    },
    "search_type": {
      "type": "string",
      "description": "Type of search: 'search' for general web, 'news' for news articles.",
      "enum": [
        "search",
        "news"
      ],
      "default": "search"
    }
  },
  "required": [
    "query"
  ]
}

web_fetch

Fetches a single URL and returns its content. Use this when you have a specific URL in mind — for example, after web.search returns a link you want to read, or when the user pastes a URL. Modes (extract): - 'auto' (default): picks the right mode based on response content type. - 'markdown': for HTML pages; returns cleaned markdown plus the page <title>. - 'text': for JSON/XML/plaintext APIs; returns the raw decoded body. - 'file': for images, PDFs, audio, video, archives, or any binary — ingests the bytes into the user's file storage and returns a file_id you can pass to messages.send (to send as an attachment), agents.add_file (to add to agent knowledge), or files.read. Use web.fetch (not files.upload) when you need the file_id immediately for the next tool call — files.upload(source_url=…) is async and won't have the file ready in the same turn. Use web.search (not web.fetch) when you don't have a specific URL yet and need to find one.

Parameters2

url	string	required	URL to fetch (http or https). Must be publicly reachable.
extract	string	optional	How to handle the response: 'auto' (default), 'markdown' (HTML → markdown), 'text' (raw body), or 'file' (ingest as binary, return file_id).

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "URL to fetch (http or https). Must be publicly reachable."
    },
    "extract": {
      "type": "string",
      "description": "How to handle the response: 'auto' (default), 'markdown' (HTML → markdown), 'text' (raw body), or 'file' (ingest as binary, return file_id).",
      "enum": [
        "auto",
        "markdown",
        "text",
        "file"
      ],
      "default": "auto"
    }
  },
  "required": [
    "url"
  ]
}

web_research

Answer a research question from live web sources in one call — returns a synthesized answer with numbered [N] citation markers and a citations array of {url, title, index}. Supports recency and domain filters. Use for questions needing current, sourced information (news about a company, market state, comparisons). For raw search result links use web.search; mode='deep' runs minutes-long exhaustive research — only when explicitly requested.

Parameters4

query	string	required	Research question. Specific scoped questions outperform vague keywords.
mode	string	optional	Research depth: 'quick' (default, seconds, cheapest), 'pro' (harder questions, better sourcing), 'deep' (autonomous multi-step research, takes minutes — only when the user explicitly wants an exhaustive report).
recency	string	optional	Only use sources from this window. Omit for no limit.
domains	array	optional	Restrict search to these domains (max 10), e.g. ['coindesk.com', 'cointelegraph.com']. Prefix with '-' to exclude a domain.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Research question. Specific scoped questions outperform vague keywords."
    },
    "mode": {
      "type": "string",
      "description": "Research depth: 'quick' (default, seconds, cheapest), 'pro' (harder questions, better sourcing), 'deep' (autonomous multi-step research, takes minutes — only when the user explicitly wants an exhaustive report).",
      "enum": [
        "quick",
        "pro",
        "deep"
      ],
      "default": "quick"
    },
    "recency": {
      "type": "string",
      "description": "Only use sources from this window. Omit for no limit.",
      "enum": [
        "day",
        "week",
        "month",
        "year"
      ]
    },
    "domains": {
      "type": "array",
      "description": "Restrict search to these domains (max 10), e.g. ['coindesk.com', 'cointelegraph.com']. Prefix with '-' to exclude a domain.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "query"
  ]
}

web__local_search

Multi-source web research with citations. Returns a synthesized answer with numbered [^1] markers and a citations array of {url, title, snippet, index}. Use for evidence-backed synthesis (competitive analysis, regulatory summary, whitepaper section). For quick fact lookups use web.search instead.

Parameters3

query	string	required	Research question. Specific scoped questions outperform vague keywords.
num_sources	integer	optional	How many top search results to fetch and synthesize (1-4, default 4). Lower = faster + cheaper, higher = more comprehensive.
language	string	optional	Search language hint (BCP-47, e.g. 'en', 'ru'). Defaults to 'en'. The synthesis output language matches the query language regardless.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Research question. Specific scoped questions outperform vague keywords."
    },
    "num_sources": {
      "type": "integer",
      "description": "How many top search results to fetch and synthesize (1-4, default 4). Lower = faster + cheaper, higher = more comprehensive.",
      "minimum": 1,
      "maximum": 4,
      "default": 4
    },
    "language": {
      "type": "string",
      "description": "Search language hint (BCP-47, e.g. 'en', 'ru'). Defaults to 'en'. The synthesis output language matches the query language regardless.",
      "default": "en"
    }
  },
  "required": [
    "query"
  ]
}

documents_create

Render a document (PDF / HTML / PPTX / DOCX) and save it to the workspace. This tool has two input pipelines — pass **exactly one** of `content_html` or `content_markdown`. # Pipeline A — `content_html` (canonical for decks, proposals, designed pages) You author full HTML+CSS. A baked-in design-system preamble ships first (`<style>` with Inter/Manrope as data-URI fonts, CSS-variable palette tokens, 8px spacing scale, and pre-styled layout helpers); your markup and any of your own `<style>` blocks land after the preamble so you can override anything. Chromium renders the assembled document into a static PDF — JavaScript is disabled and DNS is blackholed, so external font / image / script fetches will fail by configuration. Required when this pipeline is used: - `title` — human-readable, used for PDF metadata and the saved filename. - `content_html` — the `<body>` and any custom `<style>` blocks. The renderer wraps this in `<html>…</html>` and injects the preamble + a canonical `<meta charset>` + `<title>`. Do NOT emit `<script>`, `<iframe>`, `<object>`, `<embed>`, `<meta>`, `<link>`, `<base>`, `<form>`, or event handlers — the sanitizer strips them. - `output_type` — `"pdf"` or `"html"`. (`"pptx"` and `"docx"` require `content_markdown` since they need structured markdown intermediates.) Optional: - `page_preset` — `"slide_16_9"` (default for any deck), `"a4"` (default for flowing documents — used if omitted), `"letter"`, or `"none"` (you declare your own `@page` rule). For a web-styled page (dark background, full-bleed sections) use `"none"` and declare `@page { margin: 0 }`, set the background on `html` as well as `body`, and add `print-color-adjust: exact` — the a4/letter presets keep 24mm paper margins, which paint as a white frame around dark designs. - `design_tokens` — flat dict overriding the preamble's CSS variables. Whitelisted keys: `brand_primary`, `accent`, `surface_dark` (hex color), `font_display`, `font_body` (font name from ['Inter', 'Manrope', 'monospace', 'sans-serif', 'serif', 'system-ui', 'ui-monospace', 'ui-sans-serif', 'ui-serif']). - `language` — BCP-47 tag (default `"en"`). Drives `<html lang>`. ## Slide structure (`page_preset="slide_16_9"`) Each slide is `<section class="slide …">…</section>`. The base `.slide` class is what sizes it to the viewport and forces the page break — do not drop it. Composable variants (apply alongside `.slide`): - `.slide-cover` — gradient hero, big display title. - `.slide-split` — two equal columns, image + narrative. - `.slide-stats` — three-up KPI cards (use `<div class="stat">` with `.stat-value` + `.stat-label` inside). - `.slide-quote` — centered pull quote + `<cite>` attribution. Layout helpers (work in any preset): `.grid-2`, `.grid-3`, `.split`, `.stack`, `.cluster`, `.callout`, `.muted`, `.kbd`. ## Speaker notes `<aside class="notes">…text…</aside>` inside a `<section class="slide">`. The sanitizer strips them from the rendered PDF and returns them as `slide_notes[]` (parallel to slide order). Orphan notes outside any slide are dropped with a warning. ## Images Only these `src` schemes resolve: - `file:NNN` — workspace `file_id`. - `data:image/...;base64,...` — inline. - `https://<host>` where `<host>` ∈ `DOCUMENTS_MEDIA_URL_ALLOWLIST`. Other URLs are dropped and replaced with an HTML comment placeholder. # Pipeline B — `content_markdown` (invoice / contract only) Required: - `title`, `content_markdown`, `output_type`. Optional: - `theme` — `"invoice"` or `"contract"`. Triggers the corresponding exemplar styling and (for invoices) the arithmetic validator that fail-closes on missing or mismatched totals. - `language` — BCP-47 (default `"en"`). # Delivery contract (CRITICAL) After this tool returns `file_id`, deliver the file with `messages.send(attachments=[file_id], text="<short caption>")`. Embedding the file_id in a markdown link, `sandbox:` URL, or `/api/files/<id>/download` text will render as plain text on the recipient's channel — the `attachments` parameter is the only way the file actually attaches.

Parameters8

title	string	required	Short human-readable title for the document.
content_html	string	optional	Full HTML body (with optional <style> blocks) for the canonical Chromium pipeline. Mutually exclusive with content_markdown.
content_markdown	string	optional	Markdown body for the invoice/contract pipeline. Mutually exclusive with content_html.
output_type	string	required	Renderer target: 'pdf' \| 'pptx' \| 'docx' \| 'html'. PPTX/DOCX require content_markdown.
page_preset	string	optional	Page geometry for content_html. 'slide_16_9' = 1280x720 deck, 'a4'/'letter' = flowing document, 'none' = LLM declares its own @page. Defaults to 'a4' inside the html branch when omitted. Rejected with content_markdown.
design_tokens	object	optional	Flat dict of CSS-variable overrides for content_html. Whitelisted keys: brand_primary, accent, surface_dark (hex color), font_display, font_body (Inter\|Manrope\|system-ui\|ui-sans-serif\|ui-serif\|ui-monospace\|sans-serif\|serif\|monospace). Unknown keys / invalid values are dropped with a warning. Rejected with content_markdown.
theme	string	optional	Invoice or contract styling for content_markdown. Rejected with content_html (use design_tokens + your own CSS instead). OMIT for default (unthemed) styling.
language	string	optional	BCP-47 language tag (e.g. 'en', 'ru', 'zh', 'ja'). Drives <html lang> and (markdown path) font fallback for non-Latin scripts.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Short human-readable title for the document."
    },
    "content_html": {
      "type": "string",
      "description": "Full HTML body (with optional <style> blocks) for the canonical Chromium pipeline. Mutually exclusive with content_markdown."
    },
    "content_markdown": {
      "type": "string",
      "description": "Markdown body for the invoice/contract pipeline. Mutually exclusive with content_html."
    },
    "output_type": {
      "type": "string",
      "description": "Renderer target: 'pdf' | 'pptx' | 'docx' | 'html'. PPTX/DOCX require content_markdown.",
      "enum": [
        "pdf",
        "pptx",
        "docx",
        "html"
      ]
    },
    "page_preset": {
      "type": "string",
      "description": "Page geometry for content_html. 'slide_16_9' = 1280x720 deck, 'a4'/'letter' = flowing document, 'none' = LLM declares its own @page. Defaults to 'a4' inside the html branch when omitted. Rejected with content_markdown.",
      "enum": [
        "slide_16_9",
        "a4",
        "letter",
        "none"
      ]
    },
    "design_tokens": {
      "type": "object",
      "description": "Flat dict of CSS-variable overrides for content_html. Whitelisted keys: brand_primary, accent, surface_dark (hex color), font_display, font_body (Inter|Manrope|system-ui|ui-sans-serif|ui-serif|ui-monospace|sans-serif|serif|monospace). Unknown keys / invalid values are dropped with a warning. Rejected with content_markdown."
    },
    "theme": {
      "type": "string",
      "description": "Invoice or contract styling for content_markdown. Rejected with content_html (use design_tokens + your own CSS instead). OMIT for default (unthemed) styling.",
      "enum": [
        "invoice",
        "contract"
      ]
    },
    "language": {
      "type": "string",
      "description": "BCP-47 language tag (e.g. 'en', 'ru', 'zh', 'ja'). Drives <html lang> and (markdown path) font fallback for non-Latin scripts.",
      "default": "en"
    }
  },
  "required": [
    "title",
    "output_type"
  ]
}

artifacts_create

Host a self-contained HTML page at a stable, default-private, shareable URL — the Artifact experience, in-app. Pass **exactly one** of: - `html` — the full page: your `<body>` plus any `<style>`/`<script>`. Unlike documents.create, the page is served **live** (JavaScript runs), so charts, interactivity, and small tools work. - `file_id` — a workspace file whose contents are already the HTML page. - `analytics_card_ids` — ids of saved analytics dashboard cards; the platform re-runs their queries and composes one designed report page (static charts, snapshot at build time). Best way to give someone a shareable analytics report. The page runs in a locked-down sandbox: a dedicated origin + a strict CSP. That means it is **fully self-contained** — it CANNOT call out to the network (`fetch`/XHR/WebSocket are blocked) or load anything from a CDN. Inline all assets: CSS/JS inline, images/fonts as `data:` URIs. Draw charts yourself as inline SVG (no external chart library). `access_level` defaults to `'private'` (viewable only in-app). Set `'shared'` to make the unguessable link itself the capability (anyone-with-link). You can flip this later with artifacts.set_access. Returns `{artifact_id, slug, url, version}`. `url` is the live link when the public origin is configured; until then the artifact is hosted and versioned but `url` is null. Republish with artifacts.update — the URL stays the same.

Parameters8

title	string	required	Short human-readable title (page <title> + gallery label).
html	string	optional	Full self-contained HTML page. Mutually exclusive with file_id.
file_id	integer	optional	Workspace file whose contents are the HTML page. Mutually exclusive with html.
description	string	optional	Optional one-line summary for the gallery card.
favicon	string	optional	Optional emoji used as the browser-tab icon (e.g. '📊').
access_level	string	optional	'private' (default, in-app only) or 'shared' (anyone-with-link).
analytics_card_ids	array	optional	Compose saved analytics dashboard cards into one report page: each card's SQL re-runs through the guarded analytics engine and renders as a static chart. Data is a snapshot at build time. Mutually exclusive with html/file_id.
template	string	optional	Optional data-driven template: HTML with {{placeholder}} tokens. When set, later artifacts.refresh(data={...}) re-renders the page server-side from tiny data payloads (no HTML round-trip) — ideal for a scheduled agent that refreshes live numbers. The initial html you pass should be this template already rendered with today's values.

Raw schema

{
  "type": "object",
  "properties": {
    "title": {
      "type": "string",
      "description": "Short human-readable title (page <title> + gallery label)."
    },
    "html": {
      "type": "string",
      "description": "Full self-contained HTML page. Mutually exclusive with file_id."
    },
    "file_id": {
      "type": "integer",
      "description": "Workspace file whose contents are the HTML page. Mutually exclusive with html."
    },
    "description": {
      "type": "string",
      "description": "Optional one-line summary for the gallery card."
    },
    "favicon": {
      "type": "string",
      "description": "Optional emoji used as the browser-tab icon (e.g. '📊')."
    },
    "access_level": {
      "type": "string",
      "description": "'private' (default, in-app only) or 'shared' (anyone-with-link).",
      "enum": [
        "private",
        "shared"
      ],
      "default": "private"
    },
    "analytics_card_ids": {
      "type": "array",
      "description": "Compose saved analytics dashboard cards into one report page: each card's SQL re-runs through the guarded analytics engine and renders as a static chart. Data is a snapshot at build time. Mutually exclusive with html/file_id.",
      "items": {
        "type": "integer"
      }
    },
    "template": {
      "type": "string",
      "description": "Optional data-driven template: HTML with {{placeholder}} tokens. When set, later artifacts.refresh(data={...}) re-renders the page server-side from tiny data payloads (no HTML round-trip) — ideal for a scheduled agent that refreshes live numbers. The initial html you pass should be this template already rendered with today's values."
    }
  },
  "required": [
    "title"
  ]
}

artifacts_update

Republish an existing artifact with new HTML. The slug and URL stay the SAME; a new version is stored (older versions are retained up to a cap). Use this to refresh a shared dashboard — anyone with the link sees the new snapshot.

Parameters4

artifact_id	integer	required	The artifact to republish.
html	string	required	The new full self-contained HTML page (same contract as artifacts.create).
label	string	optional	Optional human name for this version (e.g. 'Q3 final').
template	string	optional	Optional: attach/replace the data-driven template (HTML with {{placeholder}} tokens) on this existing artifact, so later artifacts.refresh(data={...}) can re-render it server-side. Pass the html rendered from this template. Omit to leave the template unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "integer",
      "description": "The artifact to republish."
    },
    "html": {
      "type": "string",
      "description": "The new full self-contained HTML page (same contract as artifacts.create)."
    },
    "label": {
      "type": "string",
      "description": "Optional human name for this version (e.g. 'Q3 final')."
    },
    "template": {
      "type": "string",
      "description": "Optional: attach/replace the data-driven template (HTML with {{placeholder}} tokens) on this existing artifact, so later artifacts.refresh(data={...}) can re-render it server-side. Pass the html rendered from this template. Omit to leave the template unchanged."
    }
  },
  "required": [
    "artifact_id",
    "html"
  ]
}

artifacts_get

Fetch an artifact's metadata by id or slug — title, access level, version, view count, URL. Set include_html=true to also return the latest HTML body (so you can read-then-edit before calling artifacts.update).

Parameters3

artifact_id	integer	optional	The artifact id. Pass this or slug.
slug	string	optional	The artifact slug. Pass this or artifact_id.
include_html	boolean	optional	If true, include the latest version's HTML body.

Raw schema

{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "integer",
      "description": "The artifact id. Pass this or slug."
    },
    "slug": {
      "type": "string",
      "description": "The artifact slug. Pass this or artifact_id."
    },
    "include_html": {
      "type": "boolean",
      "description": "If true, include the latest version's HTML body."
    }
  },
  "required": []
}

artifacts_list

List the workspace's artifacts (most-recently-updated first): title, url, access level, version, view count. Soft-deleted artifacts are excluded.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

artifacts_set_access

Change an artifact's access level. 'shared' makes the unguessable link the capability (anyone-with-link); 'private' revokes that — the link 404s for anyone not signed into the workspace. Existing shared links keep the same URL when re-shared.

Parameters2

artifact_id	integer	required	The artifact to change.
access_level	string	required	'shared' (anyone-with-link) or 'private' (in-app only).

Raw schema

{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "integer",
      "description": "The artifact to change."
    },
    "access_level": {
      "type": "string",
      "description": "'shared' (anyone-with-link) or 'private' (in-app only).",
      "enum": [
        "private",
        "shared"
      ]
    }
  },
  "required": [
    "artifact_id",
    "access_level"
  ]
}

artifacts_export_pdf

Snapshot an artifact's current version to a PDF saved in the workspace. NOTE: the PDF is a STATIC capture rendered with JavaScript disabled — interactive or JS-drawn content (charts on <canvas>, script-generated SVG) will not appear. Author charts as static SVG if they must show in the PDF. Returns the file_id; deliver it with messages.send(attachments=[file_id]).

Parameters1

artifact_id

integer

required

The artifact to snapshot (its latest version).

Raw schema

{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "integer",
      "description": "The artifact to snapshot (its latest version)."
    }
  },
  "required": [
    "artifact_id"
  ]
}

artifacts_refresh

Re-render a data-driven artifact from a small data payload and publish a new version at the SAME URL. The artifact must have been created/updated with a `template` (HTML containing {{placeholder}} tokens). Pass `data` as a flat map of placeholder -> value (e.g. {"leads": "3 200", "date": "15 июля 2026"}); the server substitutes them into the stored template — you do NOT send any HTML. Ideal for scheduled refreshes of live numbers. Every template placeholder must have a value in data, or the call fails.

Parameters3

artifact_id	integer	required	The data-driven artifact to refresh.
data	object	required	Flat map of {{placeholder}} name -> value. Every placeholder in the template must be present. Values are HTML-escaped.
label	string	optional	Optional version label (e.g. 'daily refresh').

Raw schema

{
  "type": "object",
  "properties": {
    "artifact_id": {
      "type": "integer",
      "description": "The data-driven artifact to refresh."
    },
    "data": {
      "type": "object",
      "description": "Flat map of {{placeholder}} name -> value. Every placeholder in the template must be present. Values are HTML-escaped."
    },
    "label": {
      "type": "string",
      "description": "Optional version label (e.g. 'daily refresh')."
    }
  },
  "required": [
    "artifact_id",
    "data"
  ]
}

agents_list

List all AI agents configured in the workspace. Returns agents with their basic info, trigger count, and knowledge collection count. Each agent's `description` field tells you when that agent is useful. If you're a router-style agent deciding whether to delegate via `agent.handoff`, read descriptions and pick the best fit. Use this to: - See all configured AI agents - Filter by status (active/paused/archived) - Get agent IDs for further operations

Parameters1

status

string

optional

Filter by status ('active' / 'paused' / 'archived'). Omit for all.

Raw schema

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by status ('active' / 'paused' / 'archived'). Omit for all.",
      "enum": [
        "active",
        "paused",
        "archived"
      ]
    }
  },
  "required": []
}

agents_get

Get detailed information about a specific AI agent. Returns full agent config including: - Execution configuration - Tool configuration - Knowledge configuration - Escalation configuration - Triggers list - Knowledge collections - Custom AI instructions (prompt_text) - Auto-reply rules override (auto_reply_rules)

Parameters1

agent_id

integer

required

ID of the AI agent to fetch

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the AI agent to fetch"
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_create

Create a new AI agent in the workspace. Execution modes: - ai_assisted (default, recommended): Two-phase AI — fast pre-classifier (Haiku) for keyword filtering and simple replies, then full AI with tools for complex messages. Best for: auto-replies, group monitoring, keyword-based filtering. - agentic: Autonomous multi-step agent with planning and tool execution. Best for: complex scheduled tasks, multi-step automation. - rule_based: Simple pattern matching without AI. For keyword filtering: use ai_assisted mode + set keywords in trigger conditions (free, deterministic) and/or auto_reply_rules (smart, LLM-based) via agents.update.

Parameters8

name	string	required	Name of the AI agent (1-100 characters)
description	string	optional	Optional description of what this agent does
text_engine	string	optional	Text-execution engine: 'rule_based', 'ai_assisted', 'agentic' (default), or 'claude_channels'. Voice is derived from triggers, not engine. OMIT to use the default ('agentic').
send_mode	string	optional	Default send mode: 'auto' or 'draft'. OMIT to use 'draft' (the default).
prompt_id	integer	optional	ID of the prompt to assign to this agent
model	string	optional	LLM the agent runs on. OMIT to use the platform default (deepseek-chat). Applied right after creation so you don't need a follow-up agents_update.
allowed_tools	array	optional	Explicit allow-list of tool IDs the agent may call on triggered runs (e.g. ['workbench.run_python', 'messages.send']). OMIT to use system defaults. Applied right after creation.
max_iterations	integer	optional	Hard cap on agentic-loop turns per run (1-50). OMIT for the default (10).

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name of the AI agent (1-100 characters)"
    },
    "description": {
      "type": "string",
      "description": "Optional description of what this agent does"
    },
    "text_engine": {
      "type": "string",
      "description": "Text-execution engine: 'rule_based', 'ai_assisted', 'agentic' (default), or 'claude_channels'. Voice is derived from triggers, not engine. OMIT to use the default ('agentic').",
      "enum": [
        "rule_based",
        "ai_assisted",
        "agentic",
        "claude_channels"
      ]
    },
    "send_mode": {
      "type": "string",
      "description": "Default send mode: 'auto' or 'draft'. OMIT to use 'draft' (the default).",
      "enum": [
        "auto",
        "draft"
      ]
    },
    "prompt_id": {
      "type": "integer",
      "description": "ID of the prompt to assign to this agent"
    },
    "model": {
      "type": "string",
      "description": "LLM the agent runs on. OMIT to use the platform default (deepseek-chat). Applied right after creation so you don't need a follow-up agents_update.",
      "enum": [
        "deepseek-chat",
        "deepseek-reasoner",
        "gpt-4.1",
        "gpt-4.1-mini",
        "gpt-4.1-nano",
        "gpt-4o",
        "claude-haiku-4-5-20251001",
        "claude-sonnet-4-6",
        "claude-sonnet-5",
        "claude-opus-4-6",
        "kimi-k2.6"
      ]
    },
    "allowed_tools": {
      "type": "array",
      "description": "Explicit allow-list of tool IDs the agent may call on triggered runs (e.g. ['workbench.run_python', 'messages.send']). OMIT to use system defaults. Applied right after creation.",
      "items": {
        "type": "string"
      }
    },
    "max_iterations": {
      "type": "integer",
      "description": "Hard cap on agentic-loop turns per run (1-50). OMIT for the default (10)."
    }
  },
  "required": [
    "name"
  ]
}

agents_update

Update an existing AI agent's configuration. All parameters are optional — only provided fields will be updated. Use this to: - Enable or disable an agent - Change agent name or description - Assign or detach a prompt - Change default send mode - Replace knowledge collections - Update agent status - Change agent priority for trigger matching (lower number = higher priority) - Override which tools the agent can/can't call on triggered runs - Override which context sections (situation, communication style, job state, conversation history, thread summary) the agent receives - Opt into boilerplate prompt sections (safety guidelines, data confidentiality, factual accuracy) — all default OFF

Parameters63

agent_id	integer	required	ID of the agent to update
name	string	optional	New name for the agent
description	string	optional	New description for the agent
prompt_id	integer	optional	Prompt ID to assign (null to detach)
send_mode	string	optional	Default send mode: 'auto' or 'draft'. OMIT to leave the send-mode unchanged.
knowledge_collection_ids	array	optional	Replace all knowledge collections with these IDs (empty list = clear all)
status	string	optional	Agent status: 'active', 'paused', or 'archived'. OMIT to leave the status unchanged.
text_engine	string	optional	Text-execution engine: 'agentic', 'ai_assisted', 'rule_based', or 'claude_channels'. Replaces the legacy execution_mode field (20260523_002). Voice is now derived from triggers, not engine. OMIT to leave unchanged.
model	string	optional	Canonical source for which LLM the agent runs on. To switch models pass JUST this — do NOT also rewrite prompt_text (any 'duty model' section in the prompt is stale doc, not the config). OMIT to leave the model unchanged.
max_iterations	integer	optional	Hard cap on agentic-loop turns (LLM round-trips) per run, 1-50 (default 10). Each turn can call tools; the loop stops when the model replies with no tool call OR this cap is hit. Raise it for multi-step tool chains (e.g. browser automation: open → snapshot → fill → confirm → reply) that otherwise exhaust their turns before producing a final answer. OMIT to leave it unchanged.
output_text_filters	array	optional	Deterministic post-processing of the user-facing text an AGENTIC run produces (messages.send text + auto-delivered final answer; drafts inherit; ai_assisted fast-path replies and messages.edit are NOT covered). List of {pattern, replacement} regex rules applied in order. Example — strip AI-tell em dashes while keeping '—————' separator runs and never gluing lines: [{"pattern": "[ \\t](?<![—–])[—–](?![—–])[ \\t]", "replacement": ", "}] (use [ \\t], not \\s — \\s matches newlines). Use for style rules the LLM won't reliably follow via prompt. Patterns are validated (invalid regex rejects the update). Max 20 rules. Empty list [] = clear all filters. OMIT to leave unchanged.
api_surface	string	optional	OpenAI HTTPS endpoint for this agent's LLM calls (Phase 3a). 'chat_completions' (default, also when null) routes to /v1/chat/completions. 'responses' routes to /v1/responses — required for OpenAI native server tools (web_search, code_interpreter, image_generation, input_file PDFs). Capability still wins: agents whose tool list triggers the server_tool_responses_api substitution always route to Responses regardless of this setting. Ignored on non-OpenAI models (Anthropic, DeepSeek, Moonshot). OMIT to leave the api_surface unchanged.
prompt_text	string	optional	DESTRUCTIVE — REPLACES the entire system prompt. Pass ONLY when the user explicitly asks to edit/rewrite the prompt. To READ the prompt use prompts.get. When updating other fields (model, name, …) OMIT this. To append, prompts.get first then concatenate. Pass null to revert to the linked template.
auto_reply_rules	string	optional	Plain-English rules injected into the fast model's system prompt as a `## Rules` block. No reserved keywords — the fast model reads them as guidance and decides per turn whether to reply directly or escalate to the main model for tools. Example: '- If the user greets, reply "Hi! How can I help?"\n- If the user asks what you can do, reply with a 1-sentence summary\n- If the question needs live data (prices, stock, booking), escalate' Engagement filtering (SKIP) belongs in trigger `conditions` (keywords, ai_filters, channel_types, cooldown), NOT here — if a message should be ignored the trigger shouldn't have fired. Pass null to clear.
priority	integer	optional	Agent priority for trigger matching. LOWER number = HIGHER priority (wins tiebreaks). Typical range 1-100. Fallback auto-reply agents use 10; specialised/topical agents use 100. When two agents match the same incoming message, the one with the lower priority number fires.
vision_enabled	boolean	optional	Per-agent opt-in for vision content. When true, the executor splices recent image attachments from the active thread into the LLM call (Phase 3a continuous vision for Meet bot screen-share, plus any future channel that uploads images). Requires the agent's model to support vision (model_has_vision check). Default false; new calls pay zero token cost until the operator opts in. OMIT to leave the vision flag unchanged.
allowed_tools	array	optional	Explicit allow-list of tool IDs this agent can call on triggered runs (e.g. ['messages.send', 'agent.handoff']). Empty list [] = clear the allow-list and fall back to system defaults. When set, only these tools (minus denied_tools) are exposed to the agent. Does NOT affect the My AI dropdown path.
denied_tools	array	optional	Block-list of tool IDs the agent must not call on triggered runs. Applied after allowed_tools and default visibility. Empty list [] = clear the block-list.
include_situation	boolean	optional	Include situation context (channel, sender info, trigger type) in the agent's prompt. OMIT to leave this flag unchanged.
include_learned_style	boolean	optional	Include learned communication style (per-contact tone, dormancy state) in the agent's prompt. OMIT to leave this flag unchanged.
include_job_state	boolean	optional	Include current job state (active job context, tasks, notes) in the agent's prompt. OMIT to leave this flag unchanged.
include_conversation_history	boolean	optional	Include recent messages from this thread (up to 20) in the agent's prompt. OMIT to leave this flag unchanged.
include_thread_summary	boolean	optional	Include condensed summary of older thread messages in the agent's prompt. OMIT to leave this flag unchanged.
include_tool_call_history	boolean	optional	Include the agent's own tool calls and results from the last 3 runs on this thread, compacted to IDs + top hits (~200-1000 tokens). Lets the agent recall file IDs, search hits, and decisions it already made across turns. Default ON. Agentic mode only. OMIT to leave this flag unchanged.
include_safety_guidelines	boolean	optional	Inject the generic Safety Guidelines block (~80 tokens) into the system prompt. Default OFF — enable only if you don't already write safety rules in your Instructions. Agentic mode only. OMIT to leave this flag unchanged.
include_data_confidentiality	boolean	optional	Inject the Data Confidentiality block (~250 tokens, cross-contact PII isolation + prompt-injection defense) into the system prompt. Recommended for multi-tenant workspaces. Default OFF. Agentic mode only. OMIT to leave this flag unchanged.
include_factual_accuracy	boolean	optional	Inject the Factual Accuracy block (~100 tokens, generic anti-hallucination rules) into the system prompt. Default OFF — skip if you write domain-specific accuracy rules in Instructions. Agentic mode only. OMIT to leave this flag unchanged.
include_specialists	boolean	optional	Inject a [SPECIALISTS] block (~50–200 tokens) listing the workspace's delegation-capable agents so a router-style agent can pick a handoff target without first calling agents.list. Default OFF for new agents; the Router template ships with this ON. Agentic mode only. OMIT to leave this flag unchanged.
fast_model	string	optional	Model for the fast-path responder (voice, text auto-reply, agent executor). Defaults to deepseek-chat when unset. Non-Anthropic models (deepseek-chat, gpt-4.1-nano, kimi-k2.6) do NOT use BYOK today — they use the system API key + credits. Pass null to revert to default.
fast_prompt_override	string	optional	Full fast-path prompt override. Placeholders substituted via .replace(): {message}, {history}, {rules}, {tools}, {output_contract}. agent.prompt_text is NOT injected into fast_prompt_override — include it yourself if you want it. Pass null to clear.
script	string	optional	rule_based deterministic action (no LLM): Python run in the workbench sandbox on each matched event. Reads `inputs` (raw_data, message_id, from_name, …) and calls the agent's integrations via call_tool('ext<id>_<name>', {..}). Dedupe writes on inputs['message_id'] (retries re-run). Pass null to clear (falls back to per-trigger template).
voice_primary_model	string	optional	Primary LLM for voice turns (e.g. 'gpt-4.1-mini', 'claude-haiku-4-5-20251001'). gpt-4.1-nano is too weak for reliable turn tracking; mini is the recommended floor. Pass null to revert to default.
voice_max_tokens	integer	optional	Max TTS tokens per voice reply (40-200, default 100). Lower = snappier, higher = more detail. Controls speech brevity only: when the agent has voice tools, the runtime floors the underlying LLM completion cap at 400 so tool-call JSON always fits.
voice_max_tool_calls	integer	optional	Max tool calls per voice turn (1-10, default 3). OMIT to leave unchanged.
voice_stt_provider	string	optional	Speech-to-text provider. 'deepgram' (default) runs Nova-3 / Flux and preserves existing behaviour. 'gladia' routes to Gladia streaming STT (solaria-1), which is Deepgram-class latency and covers ~115 languages Deepgram does NOT — including Uzbek ('uz'), Kazakh ('kk'), Azerbaijani ('az'), Tajik ('tg'). Pick 'gladia' when the caller's language is outside Deepgram's coverage, then set voice_stt_language to that language's code. The provider also decides which language codes voice_stt_language accepts. OMIT to leave the STT provider unchanged.
voice_stt_model	string	optional	Speech-to-text model (Deepgram provider only): 'flux' (alias for flux-general-en), 'flux-general-en' (English Flux, LLM-powered end-of-turn), 'flux-general-multi' (multilingual Flux), or 'nova-3' (silence-based fallback). Flux variants are more responsive; nova-3 is the fallback when your Deepgram plan lacks Flux. Ignored when voice_stt_provider='gladia' (Gladia has a single model). OMIT to leave the STT model unchanged.
voice_stt_language	string	optional	STT language code, validated against the SELECTED voice_stt_provider. 'multi' (default) enables autodetect / code-switching on either provider; a singleton like 'en', 'ru', 'uz' gives higher accuracy when the caller language is known. Deepgram provider: 'en' runs on Flux (fastest, eager end-of-turn); 'multi' and every other language run on Nova-3. Some languages — notably Thai ('th'), Vietnamese ('vi'), Indonesian ('id'), Tagalog ('tl') — are NOT in Nova-3's 'multi' auto-detect set, so those callers MUST be given an explicit code. Gladia provider: use its codes (e.g. 'uz' Uzbek, 'kk' Kazakh, 'az' Azerbaijani, 'tg' Tajik) — these are NOT valid under Deepgram. The enum below lists the union of both providers' codes; a code invalid for the chosen provider is rejected on save. OMIT to leave the STT language unchanged.
voice_stt_keyterms	array	optional	Domain-vocab bias for STT — names, product SKUs, etc. Passed verbatim as repeated `&keyterm=<w>` query params. Works on both Nova-3 and Flux. Prefer short phrases over full sentences. Empty list [] = no bias. Omit leaves unchanged.
voice_tts_provider	string	optional	Text-to-speech provider: 'deepgram' (default, Aura-2 EN-only), 'openai' (multilingual), 'cartesia' (Sonic-3, ultra-low TTFB, multilingual), 'alibaba' (CosyVoice v3-flash, multilingual, ~95ms TTFB), 'yandex' (best Russian), 'qwen' (Qwen3-TTS, self-hosted), or 'xai' (Grok, ~20 langs). OMIT to leave the TTS provider unchanged.
voice_tts_voice	string	optional	TTS voice id — provider-specific (e.g. 'aura-2-thalia-en' for Deepgram, 'alloy' for OpenAI, 'alena' for Yandex, Cartesia voice UUID). Pass null to revert to provider default.
voice_tts_language	string	optional	TTS language code, BCP-47 lite e.g. 'en', 'es', 'pt-BR' (Cartesia only, default 'en').
voice_tts_speed	number	optional	TTS playback speed multiplier (0.5-2.0, default 1.0). Yandex/OpenAI/Cartesia only — ignored for Deepgram.
voice_endpointing_min_delay	number	optional	Silence after end-of-utterance before agent replies (0.1-2.0s, default 0.3). Higher = fewer false interrupts; lower = snappier.
voice_interruption_min_duration	number	optional	Min caller speech duration to interrupt the agent (0.1-1.5s, default 0.25). Higher = ignore short fillers like 'uh-huh'.
voice_group_interim_barge_in	boolean	optional	GROUP/Meet barge-in: interrupt the agent AS SOON AS a participant starts speaking (on the interim transcript), instead of waiting for the finished utterance. Default true. Set true to make a presenter/group agent easy to interrupt mid-sentence (word-gated by voice_group_barge_in_min_words so ambient noise can't trip it); false = only a completed utterance interrupts. OMIT to leave unchanged.
voice_group_barge_in_min_words	integer	optional	GROUP/Meet barge-in word gate (1-6, default 1): a participant line must have at least this many words to interrupt the agent. 1 = any word interrupts (most responsive); raise to ignore short cross-talk. OMIT to leave unchanged.
voice_group_barge_in_stop_words	array	optional	GROUP/Meet barge-in stop-words: any of these words/phrases ALWAYS interrupts the agent, even below voice_group_barge_in_min_words (e.g. ['стоп','подожди','вопрос','stop','wait','question']). Empty list [] clears. OMIT to leave unchanged.
voice_group_barge_in_requires_address	boolean	optional	GROUP/Meet barge-in: when true, only lines that ADDRESS the agent (by name/keyword) interrupt it — two humans talking to each other won't break the walk. Default false. OMIT to leave unchanged.
voice_greeting	string	optional	Opening line the agent speaks when the call connects. Pass an empty string "" to clear. Omit or null leaves unchanged.
voice_greeting_returning	string	optional	Greeting variant for RETURNING callers (thread has prior history or a resolved name). Supports '{name}' — replaced with the caller's name when known, stripped when not. Pass an empty string "" to clear (always use voice_greeting). Omit or null leaves unchanged.
voice_filler_enabled	boolean	optional	Emit 'thinking' filler audio while tools run so the caller hears life on the line (default true). OMIT to leave this flag unchanged.
voice_filler_audio_preset	string	optional	Which bundled clip plays as the 'thinking' filler while the agent is working (LLM + tool calls), used when voice_thinking_texts is empty. Requires voice_filler_enabled=true. Built-in presets: 'keyboard_typing' / 'keyboard_typing2' (keyboard-typing SFX — sounds like the agent is typing/looking something up), plus any bundled music preset. Pass '' to clear (fall back to spoken filler). An unknown value silently plays no filler. OMIT or null to leave unchanged.
voice_greeting_interruptible	boolean	optional	Allow the caller to barge in during the opener TTS. Default true (trial-friendly — long greetings can be interrupted). Set false on outbound-call agents whose configured opener would otherwise get preempted by the caller's 'Hello?' triggering an off-script auto-turn. OMIT to leave this flag unchanged.
voice_preemptive_generation	boolean	optional	Speculatively start the LLM on STT partials so the agent begins responding before end-of-utterance. Matches LiveKit stock template. Default true. OMIT to leave this flag unchanged.
voice_thinking_texts	array	optional	Pool of phrases spoken while the agent sets up the turn before calling the LLM (e.g. ['Hmm', 'So', 'One sec']). Pre-rendered to PCM at call start; one is picked at random per turn so the agent doesn't repeat the same word. Pass [] to clear. Omit or null leaves unchanged.
voice_turn_detector	string	optional	Voice end-of-turn detector: 'vad' (default — sharp, low-latency) or 'multilingual' (semantic model, ~1s slower per turn, fewer mid-pause cuts). OMIT to leave unchanged.
voice_flux_eot_threshold	number	optional	Flux STT end-of-turn confidence threshold (0.1-1.0). Higher = wait for more certainty before finalizing the turn. Flux STT only (ignored on nova-3). OMIT to keep the worker default (0.7).
voice_flux_eager_eot_threshold	number	optional	Flux eager end-of-turn threshold (0.1-1.0). Setting this ENABLES EagerEndOfTurn for faster turn-taking at the cost of +50-70% LLM calls. Flux STT only. OMIT to leave eager off.
voice_flux_eot_timeout_ms	integer	optional	Flux end-of-turn hard timeout in ms (500-15000). Flux STT only. OMIT to keep the worker default (5000).
voice_early_finalize_confidence	number	optional	Flux early-finalize confidence (0.1-1.0, worker default 0.65). Lower = finalize sooner on trailing silence (snappier, small mid-word clip risk). Flux STT only. OMIT to leave unchanged.
voice_mip_opt_out	boolean	optional	Opt out of Deepgram's model-improvement program (privacy) for Flux STT. Default false. OMIT to leave unchanged.
voice_tools	array	optional	The EXACT set of tool IDs exposed to the LIVE VOICE runner (dotted IDs, e.g. ['knowledge.query','messages.send','messages.read_history','agent.handoff','calls.end','calendar.check_availability','calendar.create_event','contacts.capture_lead']). SEPARATE from allowed_tools (which governs TEXT mode): a tool only reaches the voice LLM if listed here. When set this REPLACES the whole voice surface — include EVERY tool the voice agent needs (the small default set is NOT auto-added once any voice tool is set). Tools listed here are also added to the text allow-list if absent. Empty list [] = no voice tools. OMIT to leave the voice tool surface unchanged.
default_calendar_id	string	optional	Default Google calendar_id applied at the TOOL layer whenever this agent calls a calendar tool without an explicit calendar_id (e.g. 'c_...@group.calendar.google.com'). Use for agents whose bookings must always land on one dedicated calendar — a prompt-only rule is advisory and the model occasionally drops the param. An explicit calendar_id in a tool call still wins. Pass an empty string to clear (falls back to 'primary'). OMIT to leave unchanged.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to update"
    },
    "name": {
      "type": "string",
      "description": "New name for the agent"
    },
    "description": {
      "type": "string",
      "description": "New description for the agent"
    },
    "prompt_id": {
      "type": "integer",
      "description": "Prompt ID to assign (null to detach)"
    },
    "send_mode": {
      "type": "string",
      "description": "Default send mode: 'auto' or 'draft'. OMIT to leave the send-mode unchanged.",
      "enum": [
        "auto",
        "draft"
      ]
    },
    "knowledge_collection_ids": {
      "type": "array",
      "description": "Replace all knowledge collections with these IDs (empty list = clear all)",
      "items": {
        "type": "integer"
      }
    },
    "status": {
      "type": "string",
      "description": "Agent status: 'active', 'paused', or 'archived'. OMIT to leave the status unchanged.",
      "enum": [
        "active",
        "paused",
        "archived"
      ]
    },
    "text_engine": {
      "type": "string",
      "description": "Text-execution engine: 'agentic', 'ai_assisted', 'rule_based', or 'claude_channels'. Replaces the legacy execution_mode field (20260523_002). Voice is now derived from triggers, not engine. OMIT to leave unchanged.",
      "enum": [
        "rule_based",
        "ai_assisted",
        "agentic",
        "claude_channels"
      ]
    },
    "model": {
      "type": "string",
      "description": "Canonical source for which LLM the agent runs on. To switch models pass JUST this — do NOT also rewrite prompt_text (any 'duty model' section in the prompt is stale doc, not the config). OMIT to leave the model unchanged.",
      "enum": [
        "deepseek-chat",
        "deepseek-reasoner",
        "gpt-4.1",
        "gpt-4.1-mini",
        "gpt-4.1-nano",
        "gpt-4o",
        "claude-haiku-4-5-20251001",
        "claude-sonnet-4-6",
        "claude-sonnet-5",
        "claude-opus-4-6",
        "kimi-k2.6"
      ]
    },
    "max_iterations": {
      "type": "integer",
      "description": "Hard cap on agentic-loop turns (LLM round-trips) per run, 1-50 (default 10). Each turn can call tools; the loop stops when the model replies with no tool call OR this cap is hit. Raise it for multi-step tool chains (e.g. browser automation: open → snapshot → fill → confirm → reply) that otherwise exhaust their turns before producing a final answer. OMIT to leave it unchanged.",
      "minimum": 1,
      "maximum": 50
    },
    "output_text_filters": {
      "type": "array",
      "description": "Deterministic post-processing of the user-facing text an AGENTIC run produces (messages.send text + auto-delivered final answer; drafts inherit; ai_assisted fast-path replies and messages.edit are NOT covered). List of {pattern, replacement} regex rules applied in order. Example — strip AI-tell em dashes while keeping '—————' separator runs and never gluing lines: [{\"pattern\": \"[ \\\\t]*(?<![—–])[—–](?![—–])[ \\\\t]*\", \"replacement\": \", \"}] (use [ \\\\t], not \\\\s — \\\\s matches newlines). Use for style rules the LLM won't reliably follow via prompt. Patterns are validated (invalid regex rejects the update). Max 20 rules. Empty list [] = clear all filters. OMIT to leave unchanged.",
      "items": {
        "type": "string"
      }
    },
    "api_surface": {
      "type": "string",
      "description": "OpenAI HTTPS endpoint for this agent's LLM calls (Phase 3a). 'chat_completions' (default, also when null) routes to /v1/chat/completions. 'responses' routes to /v1/responses — required for OpenAI native server tools (web_search, code_interpreter, image_generation, input_file PDFs). Capability still wins: agents whose tool list triggers the server_tool_responses_api substitution always route to Responses regardless of this setting. Ignored on non-OpenAI models (Anthropic, DeepSeek, Moonshot). OMIT to leave the api_surface unchanged.",
      "enum": [
        "chat_completions",
        "responses"
      ]
    },
    "prompt_text": {
      "type": "string",
      "description": "DESTRUCTIVE — REPLACES the entire system prompt. Pass ONLY when the user explicitly asks to edit/rewrite the prompt. To READ the prompt use prompts.get. When updating other fields (model, name, …) OMIT this. To append, prompts.get first then concatenate. Pass null to revert to the linked template."
    },
    "auto_reply_rules": {
      "type": "string",
      "description": "Plain-English rules injected into the fast model's system prompt as a `## Rules` block. No reserved keywords — the fast model reads them as guidance and decides per turn whether to reply directly or escalate to the main model for tools. Example: '- If the user greets, reply \"Hi! How can I help?\"\\n- If the user asks what you can do, reply with a 1-sentence summary\\n- If the question needs live data (prices, stock, booking), escalate'\nEngagement filtering (SKIP) belongs in trigger `conditions` (keywords, ai_filters, channel_types, cooldown), NOT here — if a message should be ignored the trigger shouldn't have fired. Pass null to clear."
    },
    "priority": {
      "type": "integer",
      "description": "Agent priority for trigger matching. LOWER number = HIGHER priority (wins tiebreaks). Typical range 1-100. Fallback auto-reply agents use 10; specialised/topical agents use 100. When two agents match the same incoming message, the one with the lower priority number fires."
    },
    "vision_enabled": {
      "type": "boolean",
      "description": "Per-agent opt-in for vision content. When true, the executor splices recent image attachments from the active thread into the LLM call (Phase 3a continuous vision for Meet bot screen-share, plus any future channel that uploads images). Requires the agent's model to support vision (model_has_vision check). Default false; new calls pay zero token cost until the operator opts in. OMIT to leave the vision flag unchanged."
    },
    "allowed_tools": {
      "type": "array",
      "description": "Explicit allow-list of tool IDs this agent can call on triggered runs (e.g. ['messages.send', 'agent.handoff']). Empty list [] = clear the allow-list and fall back to system defaults. When set, only these tools (minus denied_tools) are exposed to the agent. Does NOT affect the My AI dropdown path.",
      "items": {
        "type": "string"
      }
    },
    "denied_tools": {
      "type": "array",
      "description": "Block-list of tool IDs the agent must not call on triggered runs. Applied after allowed_tools and default visibility. Empty list [] = clear the block-list.",
      "items": {
        "type": "string"
      }
    },
    "include_situation": {
      "type": "boolean",
      "description": "Include situation context (channel, sender info, trigger type) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_learned_style": {
      "type": "boolean",
      "description": "Include learned communication style (per-contact tone, dormancy state) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_job_state": {
      "type": "boolean",
      "description": "Include current job state (active job context, tasks, notes) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_conversation_history": {
      "type": "boolean",
      "description": "Include recent messages from this thread (up to 20) in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_thread_summary": {
      "type": "boolean",
      "description": "Include condensed summary of older thread messages in the agent's prompt. OMIT to leave this flag unchanged."
    },
    "include_tool_call_history": {
      "type": "boolean",
      "description": "Include the agent's own tool calls and results from the last 3 runs on this thread, compacted to IDs + top hits (~200-1000 tokens). Lets the agent recall file IDs, search hits, and decisions it already made across turns. Default ON. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "include_safety_guidelines": {
      "type": "boolean",
      "description": "Inject the generic Safety Guidelines block (~80 tokens) into the system prompt. Default OFF — enable only if you don't already write safety rules in your Instructions. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "include_data_confidentiality": {
      "type": "boolean",
      "description": "Inject the Data Confidentiality block (~250 tokens, cross-contact PII isolation + prompt-injection defense) into the system prompt. Recommended for multi-tenant workspaces. Default OFF. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "include_factual_accuracy": {
      "type": "boolean",
      "description": "Inject the Factual Accuracy block (~100 tokens, generic anti-hallucination rules) into the system prompt. Default OFF — skip if you write domain-specific accuracy rules in Instructions. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "include_specialists": {
      "type": "boolean",
      "description": "Inject a [SPECIALISTS] block (~50–200 tokens) listing the workspace's delegation-capable agents so a router-style agent can pick a handoff target without first calling agents.list. Default OFF for new agents; the Router template ships with this ON. Agentic mode only. OMIT to leave this flag unchanged."
    },
    "fast_model": {
      "type": "string",
      "description": "Model for the fast-path responder (voice, text auto-reply, agent executor). Defaults to deepseek-chat when unset. Non-Anthropic models (deepseek-chat, gpt-4.1-nano, kimi-k2.6) do NOT use BYOK today — they use the system API key + credits. Pass null to revert to default."
    },
    "fast_prompt_override": {
      "type": "string",
      "description": "Full fast-path prompt override. Placeholders substituted via .replace(): {message}, {history}, {rules}, {tools}, {output_contract}. agent.prompt_text is NOT injected into fast_prompt_override — include it yourself if you want it. Pass null to clear."
    },
    "script": {
      "type": "string",
      "description": "rule_based deterministic action (no LLM): Python run in the workbench sandbox on each matched event. Reads `inputs` (raw_data, message_id, from_name, …) and calls the agent's integrations via call_tool('ext<id>_<name>', {..}). Dedupe writes on inputs['message_id'] (retries re-run). Pass null to clear (falls back to per-trigger template)."
    },
    "voice_primary_model": {
      "type": "string",
      "description": "Primary LLM for voice turns (e.g. 'gpt-4.1-mini', 'claude-haiku-4-5-20251001'). gpt-4.1-nano is too weak for reliable turn tracking; mini is the recommended floor. Pass null to revert to default."
    },
    "voice_max_tokens": {
      "type": "integer",
      "description": "Max TTS tokens per voice reply (40-200, default 100). Lower = snappier, higher = more detail. Controls speech brevity only: when the agent has voice tools, the runtime floors the underlying LLM completion cap at 400 so tool-call JSON always fits.",
      "minimum": 40,
      "maximum": 200
    },
    "voice_max_tool_calls": {
      "type": "integer",
      "description": "Max tool calls per voice turn (1-10, default 3). OMIT to leave unchanged.",
      "minimum": 1,
      "maximum": 10
    },
    "voice_stt_provider": {
      "type": "string",
      "description": "Speech-to-text provider. 'deepgram' (default) runs Nova-3 / Flux and preserves existing behaviour. 'gladia' routes to Gladia streaming STT (solaria-1), which is Deepgram-class latency and covers ~115 languages Deepgram does NOT — including Uzbek ('uz'), Kazakh ('kk'), Azerbaijani ('az'), Tajik ('tg'). Pick 'gladia' when the caller's language is outside Deepgram's coverage, then set voice_stt_language to that language's code. The provider also decides which language codes voice_stt_language accepts. OMIT to leave the STT provider unchanged.",
      "enum": [
        "deepgram",
        "gladia"
      ]
    },
    "voice_stt_model": {
      "type": "string",
      "description": "Speech-to-text model (Deepgram provider only): 'flux' (alias for flux-general-en), 'flux-general-en' (English Flux, LLM-powered end-of-turn), 'flux-general-multi' (multilingual Flux), or 'nova-3' (silence-based fallback). Flux variants are more responsive; nova-3 is the fallback when your Deepgram plan lacks Flux. Ignored when voice_stt_provider='gladia' (Gladia has a single model). OMIT to leave the STT model unchanged.",
      "enum": [
        "flux",
        "flux-general-en",
        "flux-general-multi",
        "nova-3"
      ]
    },
    "voice_stt_language": {
      "type": "string",
      "description": "STT language code, validated against the SELECTED voice_stt_provider. 'multi' (default) enables autodetect / code-switching on either provider; a singleton like 'en', 'ru', 'uz' gives higher accuracy when the caller language is known. Deepgram provider: 'en' runs on Flux (fastest, eager end-of-turn); 'multi' and every other language run on Nova-3. Some languages — notably Thai ('th'), Vietnamese ('vi'), Indonesian ('id'), Tagalog ('tl') — are NOT in Nova-3's 'multi' auto-detect set, so those callers MUST be given an explicit code. Gladia provider: use its codes (e.g. 'uz' Uzbek, 'kk' Kazakh, 'az' Azerbaijani, 'tg' Tajik) — these are NOT valid under Deepgram. The enum below lists the union of both providers' codes; a code invalid for the chosen provider is rejected on save. OMIT to leave the STT language unchanged.",
      "enum": [
        "af",
        "am",
        "ar",
        "ar-AE",
        "ar-DZ",
        "ar-EG",
        "ar-IQ",
        "ar-IR",
        "ar-JO",
        "ar-KW",
        "ar-LB",
        "ar-MA",
        "ar-PS",
        "ar-QA",
        "ar-SA",
        "ar-SD",
        "ar-SY",
        "ar-TD",
        "ar-TN",
        "as",
        "ast",
        "az",
        "ba",
        "be",
        "bg",
        "bn",
        "bo",
        "br",
        "bs",
        "ca",
        "ceb",
        "cs",
        "cy",
        "da",
        "da-DK",
        "de",
        "de-CH",
        "el",
        "en",
        "en-AU",
        "en-GB",
        "en-IN",
        "en-NZ",
        "en-US",
        "es",
        "es-419",
        "et",
        "eu",
        "fa",
        "ff",
        "fi",
        "fo",
        "fr",
        "fr-CA",
        "fy",
        "ga",
        "gd",
        "gl",
        "gu",
        "ha",
        "haw",
        "he",
        "hi",
        "hr",
        "ht",
        "hu",
        "hy",
        "id",
        "ig",
        "ilo",
        "is",
        "it",
        "ja",
        "jv",
        "ka",
        "kk",
        "km",
        "kn",
        "ko",
        "ko-KR",
        "la",
        "lb",
        "lg",
        "ln",
        "lo",
        "lt",
        "lv",
        "mg",
        "mi",
        "mk",
        "ml",
        "mn",
        "mo",
        "mr",
        "ms",
        "mt",
        "multi",
        "my",
        "ne",
        "nl",
        "nl-BE",
        "nn",
        "no",
        "oc",
        "or",
        "pa",
        "pl",
        "ps",
        "pt",
        "pt-BR",
        "pt-PT",
        "ro",
        "ru",
        "sa",
        "sd",
        "si",
        "sk",
        "sl",
        "sn",
        "so",
        "sq",
        "sr",
        "ss",
        "su",
        "sv",
        "sv-SE",
        "sw",
        "ta",
        "te",
        "tg",
        "th",
        "th-TH",
        "tk",
        "tl",
        "tn",
        "tr",
        "tt",
        "uk",
        "ur",
        "uz",
        "vi",
        "wo",
        "xh",
        "yi",
        "yo",
        "zh",
        "zh-CN",
        "zh-HK",
        "zh-Hans",
        "zh-Hant",
        "zh-TW",
        "zu"
      ]
    },
    "voice_stt_keyterms": {
      "type": "array",
      "description": "Domain-vocab bias for STT — names, product SKUs, etc. Passed verbatim as repeated `&keyterm=<w>` query params. Works on both Nova-3 and Flux. Prefer short phrases over full sentences. Empty list [] = no bias. Omit leaves unchanged.",
      "items": {
        "type": "string"
      }
    },
    "voice_tts_provider": {
      "type": "string",
      "description": "Text-to-speech provider: 'deepgram' (default, Aura-2 EN-only), 'openai' (multilingual), 'cartesia' (Sonic-3, ultra-low TTFB, multilingual), 'alibaba' (CosyVoice v3-flash, multilingual, ~95ms TTFB), 'yandex' (best Russian), 'qwen' (Qwen3-TTS, self-hosted), or 'xai' (Grok, ~20 langs). OMIT to leave the TTS provider unchanged.",
      "enum": [
        "alibaba",
        "cartesia",
        "deepgram",
        "openai",
        "qwen",
        "xai",
        "yandex"
      ]
    },
    "voice_tts_voice": {
      "type": "string",
      "description": "TTS voice id — provider-specific (e.g. 'aura-2-thalia-en' for Deepgram, 'alloy' for OpenAI, 'alena' for Yandex, Cartesia voice UUID). Pass null to revert to provider default."
    },
    "voice_tts_language": {
      "type": "string",
      "description": "TTS language code, BCP-47 lite e.g. 'en', 'es', 'pt-BR' (Cartesia only, default 'en').",
      "pattern": "^[a-z]{2}(-[A-Z]{2})?$"
    },
    "voice_tts_speed": {
      "type": "number",
      "description": "TTS playback speed multiplier (0.5-2.0, default 1.0). Yandex/OpenAI/Cartesia only — ignored for Deepgram.",
      "minimum": 0.5,
      "maximum": 2
    },
    "voice_endpointing_min_delay": {
      "type": "number",
      "description": "Silence after end-of-utterance before agent replies (0.1-2.0s, default 0.3). Higher = fewer false interrupts; lower = snappier.",
      "minimum": 0.1,
      "maximum": 2
    },
    "voice_interruption_min_duration": {
      "type": "number",
      "description": "Min caller speech duration to interrupt the agent (0.1-1.5s, default 0.25). Higher = ignore short fillers like 'uh-huh'.",
      "minimum": 0.1,
      "maximum": 1.5
    },
    "voice_group_interim_barge_in": {
      "type": "boolean",
      "description": "GROUP/Meet barge-in: interrupt the agent AS SOON AS a participant starts speaking (on the interim transcript), instead of waiting for the finished utterance. Default true. Set true to make a presenter/group agent easy to interrupt mid-sentence (word-gated by voice_group_barge_in_min_words so ambient noise can't trip it); false = only a completed utterance interrupts. OMIT to leave unchanged."
    },
    "voice_group_barge_in_min_words": {
      "type": "integer",
      "description": "GROUP/Meet barge-in word gate (1-6, default 1): a participant line must have at least this many words to interrupt the agent. 1 = any word interrupts (most responsive); raise to ignore short cross-talk. OMIT to leave unchanged.",
      "minimum": 1,
      "maximum": 6
    },
    "voice_group_barge_in_stop_words": {
      "type": "array",
      "description": "GROUP/Meet barge-in stop-words: any of these words/phrases ALWAYS interrupts the agent, even below voice_group_barge_in_min_words (e.g. ['стоп','подожди','вопрос','stop','wait','question']). Empty list [] clears. OMIT to leave unchanged.",
      "items": {
        "type": "string"
      }
    },
    "voice_group_barge_in_requires_address": {
      "type": "boolean",
      "description": "GROUP/Meet barge-in: when true, only lines that ADDRESS the agent (by name/keyword) interrupt it — two humans talking to each other won't break the walk. Default false. OMIT to leave unchanged."
    },
    "voice_greeting": {
      "type": "string",
      "description": "Opening line the agent speaks when the call connects. Pass an empty string \"\" to clear. Omit or null leaves unchanged."
    },
    "voice_greeting_returning": {
      "type": "string",
      "description": "Greeting variant for RETURNING callers (thread has prior history or a resolved name). Supports '{name}' — replaced with the caller's name when known, stripped when not. Pass an empty string \"\" to clear (always use voice_greeting). Omit or null leaves unchanged."
    },
    "voice_filler_enabled": {
      "type": "boolean",
      "description": "Emit 'thinking' filler audio while tools run so the caller hears life on the line (default true). OMIT to leave this flag unchanged."
    },
    "voice_filler_audio_preset": {
      "type": "string",
      "description": "Which bundled clip plays as the 'thinking' filler while the agent is working (LLM + tool calls), used when voice_thinking_texts is empty. Requires voice_filler_enabled=true. Built-in presets: 'keyboard_typing' / 'keyboard_typing2' (keyboard-typing SFX — sounds like the agent is typing/looking something up), plus any bundled music preset. Pass '' to clear (fall back to spoken filler). An unknown value silently plays no filler. OMIT or null to leave unchanged."
    },
    "voice_greeting_interruptible": {
      "type": "boolean",
      "description": "Allow the caller to barge in during the opener TTS. Default true (trial-friendly — long greetings can be interrupted). Set false on outbound-call agents whose configured opener would otherwise get preempted by the caller's 'Hello?' triggering an off-script auto-turn. OMIT to leave this flag unchanged."
    },
    "voice_preemptive_generation": {
      "type": "boolean",
      "description": "Speculatively start the LLM on STT partials so the agent begins responding before end-of-utterance. Matches LiveKit stock template. Default true. OMIT to leave this flag unchanged."
    },
    "voice_thinking_texts": {
      "type": "array",
      "description": "Pool of phrases spoken while the agent sets up the turn before calling the LLM (e.g. ['Hmm', 'So', 'One sec']). Pre-rendered to PCM at call start; one is picked at random per turn so the agent doesn't repeat the same word. Pass [] to clear. Omit or null leaves unchanged.",
      "items": {
        "type": "string"
      }
    },
    "voice_turn_detector": {
      "type": "string",
      "description": "Voice end-of-turn detector: 'vad' (default — sharp, low-latency) or 'multilingual' (semantic model, ~1s slower per turn, fewer mid-pause cuts). OMIT to leave unchanged.",
      "enum": [
        "vad",
        "multilingual"
      ]
    },
    "voice_flux_eot_threshold": {
      "type": "number",
      "description": "Flux STT end-of-turn confidence threshold (0.1-1.0). Higher = wait for more certainty before finalizing the turn. Flux STT only (ignored on nova-3). OMIT to keep the worker default (0.7).",
      "minimum": 0.1,
      "maximum": 1
    },
    "voice_flux_eager_eot_threshold": {
      "type": "number",
      "description": "Flux eager end-of-turn threshold (0.1-1.0). Setting this ENABLES EagerEndOfTurn for faster turn-taking at the cost of +50-70% LLM calls. Flux STT only. OMIT to leave eager off.",
      "minimum": 0.1,
      "maximum": 1
    },
    "voice_flux_eot_timeout_ms": {
      "type": "integer",
      "description": "Flux end-of-turn hard timeout in ms (500-15000). Flux STT only. OMIT to keep the worker default (5000).",
      "minimum": 500,
      "maximum": 15000
    },
    "voice_early_finalize_confidence": {
      "type": "number",
      "description": "Flux early-finalize confidence (0.1-1.0, worker default 0.65). Lower = finalize sooner on trailing silence (snappier, small mid-word clip risk). Flux STT only. OMIT to leave unchanged.",
      "minimum": 0.1,
      "maximum": 1
    },
    "voice_mip_opt_out": {
      "type": "boolean",
      "description": "Opt out of Deepgram's model-improvement program (privacy) for Flux STT. Default false. OMIT to leave unchanged."
    },
    "voice_tools": {
      "type": "array",
      "description": "The EXACT set of tool IDs exposed to the LIVE VOICE runner (dotted IDs, e.g. ['knowledge.query','messages.send','messages.read_history','agent.handoff','calls.end','calendar.check_availability','calendar.create_event','contacts.capture_lead']). SEPARATE from allowed_tools (which governs TEXT mode): a tool only reaches the voice LLM if listed here. When set this REPLACES the whole voice surface — include EVERY tool the voice agent needs (the small default set is NOT auto-added once any voice tool is set). Tools listed here are also added to the text allow-list if absent. Empty list [] = no voice tools. OMIT to leave the voice tool surface unchanged.",
      "items": {
        "type": "string"
      }
    },
    "default_calendar_id": {
      "type": "string",
      "description": "Default Google calendar_id applied at the TOOL layer whenever this agent calls a calendar tool without an explicit calendar_id (e.g. 'c_...@group.calendar.google.com'). Use for agents whose bookings must always land on one dedicated calendar — a prompt-only rule is advisory and the model occasionally drops the param. An explicit calendar_id in a tool call still wins. Pass an empty string to clear (falls back to 'primary'). OMIT to leave unchanged."
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_delete

Permanently delete an AI agent. WARNING: This cannot be undone. The agent and all its triggers will be removed.

Parameters1

agent_id

integer

required

ID of the agent to delete

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to delete"
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_ask

Send a message to an AI agent and get its response. The agent runs with its configured prompt, tools, and knowledge. Use this to test agents or have them process a task. Returns: {status: 'replied'|'silent', response_text, messages[], full_reply, model_used, tokens_*, send_mode, execution_mode, tool_calls[]}. `tool_calls[]` is the per-tool trace in call order — each {tool, success, error, duration_ms} — so you can see which tool the agent ran and why it failed (e.g. a workbench script error) directly from this response, no trace lookup needed. `messages[]` carries each messages.send invocation the agent made (text, subject, reply_to_message_id, timestamp, message_id, attachments=[{file_id,name,mime}]). `full_reply` concatenates text only — attachment-only sends show up in `messages` but not `full_reply`. `status='silent'` iff both response_text is empty AND messages is empty. Execution may take 10-60s depending on agent complexity. For runs that may exceed ~2 minutes (heavy multi-step agents), pass background=true: the call returns immediately with status='started' and the run continues server-side, detached from this connection — poll agents.traces_list / agents.trace_get for the outcome and agents.list_drafts for produced drafts.

Parameters4

agent_id	integer	required	ID of the AI agent to ask
message	string	required	Message/goal to send to the agent
send_mode	string	optional	Send mode for the agent run: 'draft' = create drafts, 'auto' = send directly. Defaults to the agent's configured default_send_mode. Does NOT change execution_mode — that is fixed by the agent's config.
background	boolean	optional	Run detached from this MCP connection. Returns immediately with status='started'; the run survives client timeouts and disconnects (up to 15 min). Poll agents.traces_list for the outcome. Use for runs expected to exceed ~2 minutes — a synchronous call is cancelled when the MCP request dies. OMIT to run synchronously and get the answer in this call (the default).

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the AI agent to ask"
    },
    "message": {
      "type": "string",
      "description": "Message/goal to send to the agent"
    },
    "send_mode": {
      "type": "string",
      "description": "Send mode for the agent run: 'draft' = create drafts, 'auto' = send directly. Defaults to the agent's configured default_send_mode. Does NOT change execution_mode — that is fixed by the agent's config."
    },
    "background": {
      "type": "boolean",
      "description": "Run detached from this MCP connection. Returns immediately with status='started'; the run survives client timeouts and disconnects (up to 15 min). Poll agents.traces_list for the outcome. Use for runs expected to exceed ~2 minutes — a synchronous call is cancelled when the MCP request dies. OMIT to run synchronously and get the answer in this call (the default)."
    }
  },
  "required": [
    "agent_id",
    "message"
  ]
}

agents_trigger_create

Create a new trigger for an AI agent. Triggers determine when the agent activates. Trigger types: - incoming_message: Activates on new incoming messages - schedule: Activates on a schedule - webhook: Activates on webhook events - event: Activates on system events

Parameters8

agent_id	integer	required	ID of the agent to create a trigger for
trigger_type	string	required	Type of trigger: 'incoming_message', 'incoming_call', 'schedule', 'webhook', 'event', 'blockchain_event', 'job_completed', 'calendar_event', or 'lead_captured'
conditions	object	optional	Trigger conditions (JSON). Supported fields for incoming_message: - keywords: ["pricing","demo"] — message must contain keyword(s) (free, no LLM cost) - keyword_match: "any" (default, OR) or "all" (AND) - channel_types: ["telegram","whatsapp","livechat_voice","twilio_voice","telegram_voice","voice",...] — filter by channel. For voice, use EITHER the three per-channel keys (scoped) OR "voice" alone (wildcard matching all three) — mixing them is redundant. Per-channel keys: "livechat_voice" (web widget), "twilio_voice" (PSTN inbound), "telegram_voice" (Telegram p2p calls) - context_types: ["dm","group","channel","livechat"] — filter by chat type - group_mode: "mentions_only" or "questions" — for group chats - channel_account_ids: ["123"] — restrict to specific accounts - folder_ids: [5,10] — restrict to threads in folders - ai_tag_ids: [1,2] — restrict to threads with AI tags - ai_filter_ids: [1,2] — semantic intent filters (message matched via embedding similarity, works in noisy groups) - ai_filter_mode: "any" (default, OR) or "all" (AND) — how multiple AI filters combine - ai_filters: [{id: 1}, {name: "...", description: "..."}] — shorthand: reference existing by id or create inline (calls Voyage embedding API). If a filter with the same name already exists, it is reused by id. Prefer referencing existing filters by id when available. Use ai_filters.create + ai_filters.test for fine-tuning before assigning. - contact_states: ["active"] — filter by contact state - cooldown_seconds: 30 — min gap between runs per thread - max_runs_per_thread_per_hour: 5 — rate limit Supported fields for job_completed (proactive callback when a delegated job finishes): - source_agent_id: <int> — fire only when this agent's job completed - source_agent_slug: <str> — alternate to source_agent_id - job_type: "agentic_session" — match a specific job type (default: any) - outcome: ["completed"] \| ["escalated"] \| ["completed","escalated"] — default ["completed"] - min_duration_seconds: <int> — skip very-short jobs (noise filter) - thread_filter: {thread_ids: [<int>...]} — restrict to specific threads Supported fields for calendar_event (fires N minutes before a Google Calendar event starts): - window_minutes_before: <int 1-1440> — REQUIRED, fire when an event starts within this window - channel_account_ids: [<int>...] — restrict to specific calendar accounts (default: all) - keywords: ["standup"] — word-boundary match on event title - prepare_meet_join: true — pre-invite pool bots to the event (enables unattended Meet join) Generic run-mode fields (incoming_message AND calendar_event): - run_mode: "text" (default, normal agent run) or "voice" (deterministically join the meeting/call resolved from the event or message — requires send_mode=auto) - voice: {speak_first: <bool — greet immediately vs stay silent until addressed>, vision_mode: "off"\|"on_demand"\|"continuous_0_3fps"}
thread_ids	array	optional	Restrict this trigger to specific threads (chats) by their numeric thread IDs. When set, the trigger only fires for messages in these threads. Only for incoming_message and job_completed triggers. Maps to conditions.thread_filter.thread_ids.
excluded_thread_ids	array	optional	Exclude specific threads (chats) by their numeric thread IDs — the opposite of thread_ids. When set, the trigger NEVER fires for messages in these threads, even if thread_ids would otherwise allow them (explicit deny wins). Only for incoming_message and job_completed triggers. Maps to conditions.thread_filter.excluded_thread_ids.
send_mode	string	optional	Send mode override for this trigger. OMIT to inherit from the agent.
enabled	boolean	optional	Whether the trigger is enabled. OMIT to use the default (true).
priority	integer	optional	Trigger priority — lower numbers run first (default: 100)

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to create a trigger for"
    },
    "trigger_type": {
      "type": "string",
      "description": "Type of trigger: 'incoming_message', 'incoming_call', 'schedule', 'webhook', 'event', 'blockchain_event', 'job_completed', 'calendar_event', or 'lead_captured'",
      "enum": [
        "incoming_message",
        "incoming_call",
        "schedule",
        "webhook",
        "event",
        "blockchain_event",
        "job_completed",
        "calendar_event",
        "lead_captured"
      ]
    },
    "conditions": {
      "type": "object",
      "description": "Trigger conditions (JSON). Supported fields for incoming_message:\n- keywords: [\"pricing\",\"demo\"] — message must contain keyword(s) (free, no LLM cost)\n- keyword_match: \"any\" (default, OR) or \"all\" (AND)\n- channel_types: [\"telegram\",\"whatsapp\",\"livechat_voice\",\"twilio_voice\",\"telegram_voice\",\"voice\",...] — filter by channel. For voice, use EITHER the three per-channel keys (scoped) OR \"voice\" alone (wildcard matching all three) — mixing them is redundant. Per-channel keys: \"livechat_voice\" (web widget), \"twilio_voice\" (PSTN inbound), \"telegram_voice\" (Telegram p2p calls)\n- context_types: [\"dm\",\"group\",\"channel\",\"livechat\"] — filter by chat type\n- group_mode: \"mentions_only\" or \"questions\" — for group chats\n- channel_account_ids: [\"123\"] — restrict to specific accounts\n- folder_ids: [5,10] — restrict to threads in folders\n- ai_tag_ids: [1,2] — restrict to threads with AI tags\n- ai_filter_ids: [1,2] — semantic intent filters (message matched via embedding similarity, works in noisy groups)\n- ai_filter_mode: \"any\" (default, OR) or \"all\" (AND) — how multiple AI filters combine\n- ai_filters: [{id: 1}, {name: \"...\", description: \"...\"}] — shorthand: reference existing by id or create inline (calls Voyage embedding API). If a filter with the same name already exists, it is reused by id. Prefer referencing existing filters by id when available. Use ai_filters.create + ai_filters.test for fine-tuning before assigning.\n- contact_states: [\"active\"] — filter by contact state\n- cooldown_seconds: 30 — min gap between runs per thread\n- max_runs_per_thread_per_hour: 5 — rate limit\n\nSupported fields for job_completed (proactive callback when a delegated job finishes):\n- source_agent_id: <int> — fire only when this agent's job completed\n- source_agent_slug: <str> — alternate to source_agent_id\n- job_type: \"agentic_session\" — match a specific job type (default: any)\n- outcome: [\"completed\"] | [\"escalated\"] | [\"completed\",\"escalated\"] — default [\"completed\"]\n- min_duration_seconds: <int> — skip very-short jobs (noise filter)\n- thread_filter: {thread_ids: [<int>...]} — restrict to specific threads\n\nSupported fields for calendar_event (fires N minutes before a Google Calendar event starts):\n- window_minutes_before: <int 1-1440> — REQUIRED, fire when an event starts within this window\n- channel_account_ids: [<int>...] — restrict to specific calendar accounts (default: all)\n- keywords: [\"standup\"] — word-boundary match on event title\n- prepare_meet_join: true — pre-invite pool bots to the event (enables unattended Meet join)\n\nGeneric run-mode fields (incoming_message AND calendar_event):\n- run_mode: \"text\" (default, normal agent run) or \"voice\" (deterministically join the meeting/call resolved from the event or message — requires send_mode=auto)\n- voice: {speak_first: <bool — greet immediately vs stay silent until addressed>, vision_mode: \"off\"|\"on_demand\"|\"continuous_0_3fps\"}"
    },
    "thread_ids": {
      "type": "array",
      "description": "Restrict this trigger to specific threads (chats) by their numeric thread IDs. When set, the trigger only fires for messages in these threads. Only for incoming_message and job_completed triggers. Maps to conditions.thread_filter.thread_ids.",
      "items": {
        "type": "integer"
      }
    },
    "excluded_thread_ids": {
      "type": "array",
      "description": "Exclude specific threads (chats) by their numeric thread IDs — the opposite of thread_ids. When set, the trigger NEVER fires for messages in these threads, even if thread_ids would otherwise allow them (explicit deny wins). Only for incoming_message and job_completed triggers. Maps to conditions.thread_filter.excluded_thread_ids.",
      "items": {
        "type": "integer"
      }
    },
    "send_mode": {
      "type": "string",
      "description": "Send mode override for this trigger. OMIT to inherit from the agent.",
      "enum": [
        "auto",
        "draft"
      ]
    },
    "enabled": {
      "type": "boolean",
      "description": "Whether the trigger is enabled. OMIT to use the default (true)."
    },
    "priority": {
      "type": "integer",
      "description": "Trigger priority — lower numbers run first (default: 100)"
    }
  },
  "required": [
    "agent_id",
    "trigger_type"
  ]
}

agents_trigger_update

Update an existing AI agent trigger. All parameters are optional — only provided fields will be updated.

Parameters9

trigger_id	integer	required	ID of the trigger to update
agent_id	integer	required	ID of the agent that owns this trigger
trigger_type	string	optional	New trigger type. OMIT to keep the existing type unchanged.
conditions	object	optional	New trigger conditions (replaces existing). Same fields as trigger_create: keywords, keyword_match, channel_types, context_types, group_mode, channel_account_ids, folder_ids, ai_tag_ids, ai_filter_ids, ai_filter_mode, ai_filters: [{id: 1}, {name: "...", description: "..."}] — shorthand: reference existing by id or create inline (calls Voyage embedding API). If a filter with the same name already exists, it is reused by id. contact_states, cooldown_seconds, max_runs_per_thread_per_hour. calendar_event: window_minutes_before (1-1440, required), channel_account_ids, keywords, prepare_meet_join. Generic (incoming_message + calendar_event): run_mode "text"\|"voice" (voice requires send_mode=auto), voice: {speak_first, vision_mode}
thread_ids	array	optional	Restrict this trigger to specific threads (chats) by their numeric thread IDs. When set, merged into conditions.thread_filter.thread_ids. If conditions is also provided, thread_ids is merged into it. Only for incoming_message and job_completed triggers.
excluded_thread_ids	array	optional	Exclude specific threads (chats) by their numeric thread IDs — the opposite of thread_ids. When set, the trigger NEVER fires for messages in these threads (explicit deny wins). Merged into conditions.thread_filter.excluded_thread_ids. Only for incoming_message and job_completed triggers.
send_mode	string	optional	New send mode override. OMIT to leave the send-mode unchanged.
enabled	boolean	optional	Enable or disable this trigger. OMIT to leave the enabled flag unchanged.
priority	integer	optional	Trigger priority — lower numbers run first

Raw schema

{
  "type": "object",
  "properties": {
    "trigger_id": {
      "type": "integer",
      "description": "ID of the trigger to update"
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent that owns this trigger"
    },
    "trigger_type": {
      "type": "string",
      "description": "New trigger type. OMIT to keep the existing type unchanged.",
      "enum": [
        "incoming_message",
        "incoming_call",
        "schedule",
        "webhook",
        "event",
        "blockchain_event",
        "job_completed",
        "calendar_event",
        "lead_captured"
      ]
    },
    "conditions": {
      "type": "object",
      "description": "New trigger conditions (replaces existing). Same fields as trigger_create:\nkeywords, keyword_match, channel_types, context_types, group_mode,\nchannel_account_ids, folder_ids, ai_tag_ids,\nai_filter_ids, ai_filter_mode,\nai_filters: [{id: 1}, {name: \"...\", description: \"...\"}] — shorthand: reference existing by id or create inline (calls Voyage embedding API). If a filter with the same name already exists, it is reused by id.\ncontact_states, cooldown_seconds, max_runs_per_thread_per_hour.\ncalendar_event: window_minutes_before (1-1440, required), channel_account_ids, keywords, prepare_meet_join.\nGeneric (incoming_message + calendar_event): run_mode \"text\"|\"voice\" (voice requires send_mode=auto), voice: {speak_first, vision_mode}"
    },
    "thread_ids": {
      "type": "array",
      "description": "Restrict this trigger to specific threads (chats) by their numeric thread IDs. When set, merged into conditions.thread_filter.thread_ids. If conditions is also provided, thread_ids is merged into it. Only for incoming_message and job_completed triggers.",
      "items": {
        "type": "integer"
      }
    },
    "excluded_thread_ids": {
      "type": "array",
      "description": "Exclude specific threads (chats) by their numeric thread IDs — the opposite of thread_ids. When set, the trigger NEVER fires for messages in these threads (explicit deny wins). Merged into conditions.thread_filter.excluded_thread_ids. Only for incoming_message and job_completed triggers.",
      "items": {
        "type": "integer"
      }
    },
    "send_mode": {
      "type": "string",
      "description": "New send mode override. OMIT to leave the send-mode unchanged.",
      "enum": [
        "auto",
        "draft"
      ]
    },
    "enabled": {
      "type": "boolean",
      "description": "Enable or disable this trigger. OMIT to leave the enabled flag unchanged."
    },
    "priority": {
      "type": "integer",
      "description": "Trigger priority — lower numbers run first"
    }
  },
  "required": [
    "trigger_id",
    "agent_id"
  ]
}

agents_trigger_delete

Delete a trigger from an AI agent. WARNING: This cannot be undone.

Parameters2

trigger_id	integer	required	ID of the trigger to delete
agent_id	integer	required	ID of the agent that owns this trigger

Raw schema

{
  "type": "object",
  "properties": {
    "trigger_id": {
      "type": "integer",
      "description": "ID of the trigger to delete"
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent that owns this trigger"
    }
  },
  "required": [
    "trigger_id",
    "agent_id"
  ]
}

webhooks_configure_enrichment

Enable enrichment on an agent's webhook trigger so reference-only webhook payloads are resolved to full data before the agent runs. One tool for every provider — choose `provider` and pass its `config`. Providers & required config: - meta_leadgen (Meta/Facebook Lead Ads): config = {app_id, app_secret, user_access_token}. The user token needs pages_show_list + leads_retrieval. Stores all page tokens encrypted per workspace and resolves each lead's name/email/phone. Reuses the existing webhook URL (no token rotation); creates a webhook trigger if the agent has none.

Parameters3

agent_id	integer	required	ID of the agent whose webhook trigger should be enriched.
provider	string	required	Enrichment provider to configure.
config	object	required	Provider-specific configuration/credentials. For meta_leadgen: {app_id, app_secret, user_access_token}.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent whose webhook trigger should be enriched."
    },
    "provider": {
      "type": "string",
      "description": "Enrichment provider to configure.",
      "enum": [
        "meta_leadgen"
      ]
    },
    "config": {
      "type": "object",
      "description": "Provider-specific configuration/credentials. For meta_leadgen: {app_id, app_secret, user_access_token}."
    }
  },
  "required": [
    "agent_id",
    "provider",
    "config"
  ]
}

agents_list_drafts

List pending agent drafts awaiting approval. Shows drafts that have been generated by AI agents but not yet sent. Each draft includes: - Thread/conversation info - Trigger message (what prompted the reply) - Generated response text - Creation time and expiration Use this when user asks: - 'Show pending agent drafts' - 'What messages are waiting for approval?' - 'List drafts to approve'

Parameters2

thread_id	string	optional	Filter by specific thread ID (optional)
limit	integer	optional	Maximum number of drafts to return

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "string",
      "description": "Filter by specific thread ID (optional)"
    },
    "limit": {
      "type": "integer",
      "description": "Maximum number of drafts to return",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    }
  },
  "required": []
}

agents_approve_draft

Approve a pending agent draft and send the message. The draft will be sent to the conversation it was generated for. You can optionally edit the text before sending. Use this when user says: - 'Approve this draft' - 'Send this reply' - 'Approve and send' - 'Looks good, send it' IMPORTANT: This will send a message to a real person.

Parameters2

draft_id	integer	required	ID of the draft to approve
edited_text	string	optional	Optional edited response text (if user wants to modify before sending)

Raw schema

{
  "type": "object",
  "properties": {
    "draft_id": {
      "type": "integer",
      "description": "ID of the draft to approve"
    },
    "edited_text": {
      "type": "string",
      "description": "Optional edited response text (if user wants to modify before sending)"
    }
  },
  "required": [
    "draft_id"
  ]
}

agents_reject_draft

Reject a pending agent draft without sending. The draft will be marked as rejected and won't be sent. Use this when the generated response isn't appropriate. Use this when user says: - 'Reject this draft' - 'Don't send this' - 'Cancel this reply' - 'Delete this draft' - 'This response is wrong'

Parameters2

draft_id	integer	required	ID of the draft to reject
reason	string	optional	Optional reason for rejection (for logging/feedback)

Raw schema

{
  "type": "object",
  "properties": {
    "draft_id": {
      "type": "integer",
      "description": "ID of the draft to reject"
    },
    "reason": {
      "type": "string",
      "description": "Optional reason for rejection (for logging/feedback)"
    }
  },
  "required": [
    "draft_id"
  ]
}

agents_list_files

List files directly attached to this agent (agent-specific files, not shared collections). Returns file_id, title, status, and chunk_count for each file. chunk_count shows how many indexed chunks were created — 0 means the file is still processing. Use agents.add_file to attach a new file, or agents.remove_file to detach one.

Parameters1

agent_id

integer

required

ID of the agent whose files to list

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent whose files to list"
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_add_file

Attach a file to this agent's private knowledge (agent-specific files, not shared with other agents). Workflow: 1. Upload the file with files_upload (pass source_url for remote files) 2. Index it with files_ingest (pass the file_id) 3. Call this tool with agent_id + file_id Returns chunk_count — shows 0 while still processing. Call agents.list_files later to see the final chunk count once indexing completes.

Parameters2

agent_id	integer	required	ID of the agent to attach the file to
file_id	integer	required	file_id returned by files_upload or files_ingest

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to attach the file to"
    },
    "file_id": {
      "type": "integer",
      "description": "file_id returned by files_upload or files_ingest"
    }
  },
  "required": [
    "agent_id",
    "file_id"
  ]
}

agents_remove_file

Remove a file from this agent's private knowledge. The file itself is not deleted — it's just detached from this agent. Use agents.list_files to find the file_id to remove.

Parameters2

agent_id	integer	required	ID of the agent to remove the file from
file_id	integer	required	ID of the file to detach (from agents.list_files)

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to remove the file from"
    },
    "file_id": {
      "type": "integer",
      "description": "ID of the file to detach (from agents.list_files)"
    }
  },
  "required": [
    "agent_id",
    "file_id"
  ]
}

agents_task_complete

Report that a Claude Code agent task has been completed. Call this when you finish processing an agent_task from DialogBrain.

Parameters3

trace_id	string	required	Trace ID from the agent task event
success	boolean	required	Whether the task completed successfully
summary	string	optional	Brief summary of what was done

Raw schema

{
  "type": "object",
  "properties": {
    "trace_id": {
      "type": "string",
      "description": "Trace ID from the agent task event"
    },
    "success": {
      "type": "boolean",
      "description": "Whether the task completed successfully"
    },
    "summary": {
      "type": "string",
      "description": "Brief summary of what was done"
    }
  },
  "required": [
    "trace_id",
    "success"
  ]
}

agent_handoff

Delegate a multi-step task (research, composing messages, booking, scheduling) to the full agentic planner. Use when a user ask needs more than a direct answer. The specialist runs synchronously — its response is already shown to the user in real-time. Summarize the OUTCOME in past tense (e.g. 'The Media Creator generated your video' or 'The Document Composer failed because...'). Do NOT say 'I will delegate' — the delegation already happened. If status is `timeout` or `error`, explain what went wrong and offer to retry.

Parameters4

task_description	string	required	Plain-language description of what the planner should accomplish. Include everything the planner needs: the user's goal, constraints, and any context already gathered in this voice call.
agent_id	integer	optional	Optional ID of another agent in the same workspace to delegate the task to. When set, this becomes cross-agent delegation; the target agent runs with ITS OWN prompt, tools, and model. Use this for specialty tasks (see agents.list to discover specialists). Prefer the in-loop variant (no `agent_id`) for one-off escalations. Spawns a new trace linked back to this trace via parent_trace_id (visible in the admin lineage card).
mode	string	optional	Execution mode: 'sync' (wait for result, default) or 'async' (fire and forget, child runs in background). Async is only available in background/trigger context.
target_slug	string	optional	Optional stable slug of a system-template specialist to delegate to (e.g. 'doc-composer' for the Document Composer). Env-portable alternative to agent_id — resolves the workspace's fork of that template (auto-forking on first use). Used by async handoffs that target a specialist without knowing its per-workspace id.

Raw schema

{
  "type": "object",
  "properties": {
    "task_description": {
      "type": "string",
      "description": "Plain-language description of what the planner should accomplish. Include everything the planner needs: the user's goal, constraints, and any context already gathered in this voice call."
    },
    "agent_id": {
      "type": "integer",
      "description": "Optional ID of another agent in the same workspace to delegate the task to. When set, this becomes cross-agent delegation; the target agent runs with ITS OWN prompt, tools, and model. Use this for specialty tasks (see agents.list to discover specialists). Prefer the in-loop variant (no `agent_id`) for one-off escalations. Spawns a new trace linked back to this trace via parent_trace_id (visible in the admin lineage card)."
    },
    "mode": {
      "type": "string",
      "description": "Execution mode: 'sync' (wait for result, default) or 'async' (fire and forget, child runs in background). Async is only available in background/trigger context.",
      "enum": [
        "sync",
        "async"
      ],
      "default": "sync"
    },
    "target_slug": {
      "type": "string",
      "description": "Optional stable slug of a system-template specialist to delegate to (e.g. 'doc-composer' for the Document Composer). Env-portable alternative to agent_id — resolves the workspace's fork of that template (auto-forking on first use). Used by async handoffs that target a specialist without knowing its per-workspace id."
    }
  },
  "required": [
    "task_description"
  ]
}

agent_silence

End this turn without sending any message. Use when the thread is owned by a human operator after job.escalate, when the guest is self-resolving, when the message is a duplicate, or for observation-only turns. Calling this tool is the ONLY correct way to stay silent — narrated silence text (e.g. '*(Staying silent…)*', 'Internal:…') would be delivered to the guest verbatim.

Parameters1

reason

string

required

Free-form explanation for admin audit. Stored in trace_tool_executions.tool_params (ClickHouse String; reason filters are scan-only).

Raw schema

{
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "description": "Free-form explanation for admin audit. Stored in trace_tool_executions.tool_params (ClickHouse String; reason filters are scan-only)."
    }
  },
  "required": [
    "reason"
  ]
}

agents_traces_list

List recent execution traces for an agent — the same data as /admin/requests, scoped to one agent and readable by an LLM. Use this when an agent call timed out, drafted the wrong response, or you want to know which tool/LLM call burned the latency. Pair with `agents.trace_get` for full detail on a specific trace. Filters: `status`, `success`, `source` (single value or comma-separated: `agent,voice`), `date_from`/`date_to` (ISO-8601), pagination via `limit`/`offset`. Returns `returned_count`, `dropped_on_page` (should be 0 — positive means the backend agent_id predicate let something through), and `has_more`. Edge case: a raw page of all-dedup-dropped rows yields `returned_count=0, has_more=true`; re-call with `offset += limit`.

Parameters8

agent_id	integer	required	Agent ID to pull traces for (must belong to your workspace).
status	string	optional	Filter by status. OMIT to include all statuses.
success	boolean	optional	Filter to succeeded (true) or failed (false) runs only. OMIT to include both.
source	string	optional	Filter by trace source. Single value or comma-separated, e.g. 'agent,voice'. Values: agent / auto_reply / agentic / outreach / voice. Note: source='agent' also matches voice traces today (known upstream bug).
limit	integer	optional	Max rows per page (1–100).
offset	integer	optional	Rows to skip for pagination. OMIT to start at row 0 (default).
date_from	string	optional	ISO-8601 lower bound on created_at, e.g. '2026-04-10T00:00:00Z'.
date_to	string	optional	ISO-8601 upper bound on created_at.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID to pull traces for (must belong to your workspace)."
    },
    "status": {
      "type": "string",
      "description": "Filter by status. OMIT to include all statuses.",
      "enum": [
        "pending",
        "executing",
        "completed",
        "failed",
        "cancelled"
      ]
    },
    "success": {
      "type": "boolean",
      "description": "Filter to succeeded (true) or failed (false) runs only. OMIT to include both."
    },
    "source": {
      "type": "string",
      "description": "Filter by trace source. Single value or comma-separated, e.g. 'agent,voice'. Values: agent / auto_reply / agentic / outreach / voice. Note: source='agent' also matches voice traces today (known upstream bug)."
    },
    "limit": {
      "type": "integer",
      "description": "Max rows per page (1–100).",
      "minimum": 1,
      "maximum": 100,
      "default": 20
    },
    "offset": {
      "type": "integer",
      "description": "Rows to skip for pagination. OMIT to start at row 0 (default).",
      "minimum": 0
    },
    "date_from": {
      "type": "string",
      "description": "ISO-8601 lower bound on created_at, e.g. '2026-04-10T00:00:00Z'."
    },
    "date_to": {
      "type": "string",
      "description": "ISO-8601 upper bound on created_at."
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_trace_get

Fetch the full execution detail for a single trace — tool executions, events timeline, LLM call spans (with error_message on failures). Use after `agents.traces_list` identifies a specific trace of interest (failed run, slow run, unexpected outcome). By default LLM `system_prompt` and `prompt_messages` are stripped — set `include_llm_bodies=true` to fetch them when diagnosing prompt engineering issues (emits a WARNING audit log). Set `full=true` to disable all field truncation. `completion_text` on failed LLM calls is always returned (capped at 8 KB).

Parameters4

trace_id	string	required	Trace identifier returned by agents.traces_list.
agent_id	integer	required	Expected agent_id — used for scope validation. Mismatch returns not_found.
include_llm_bodies	boolean	optional	Include system_prompt and prompt_messages in LLM spans. Audited at WARNING level. OMIT to keep them stripped (the default).
full	boolean	optional	Disable all field truncation. Escape hatch for a human operator. OMIT for the standard truncated view.

Raw schema

{
  "type": "object",
  "properties": {
    "trace_id": {
      "type": "string",
      "description": "Trace identifier returned by agents.traces_list."
    },
    "agent_id": {
      "type": "integer",
      "description": "Expected agent_id — used for scope validation. Mismatch returns not_found."
    },
    "include_llm_bodies": {
      "type": "boolean",
      "description": "Include system_prompt and prompt_messages in LLM spans. Audited at WARNING level. OMIT to keep them stripped (the default)."
    },
    "full": {
      "type": "boolean",
      "description": "Disable all field truncation. Escape hatch for a human operator. OMIT for the standard truncated view."
    }
  },
  "required": [
    "trace_id",
    "agent_id"
  ]
}

agents_traces_stats

Aggregated trace statistics for one agent over the last N days — total runs, success rate, avg duration, error breakdown, top tools used, runs-per-day histogram. Use this when you want a bird's-eye view of an agent's health before diving into individual traces with `agents.traces_list` / `agents.trace_get`. Scoped to the target agent (exact match, no substring bleed). `days` is capped at 30 — matches the ClickHouse request_traces TTL.

Parameters2

agent_id	integer	required	Agent ID to compute stats for (must belong to your workspace).
days	integer	optional	Rolling window in days (1–30).

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID to compute stats for (must belong to your workspace)."
    },
    "days": {
      "type": "integer",
      "description": "Rolling window in days (1–30).",
      "minimum": 1,
      "maximum": 30,
      "default": 7
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_activity

See what you — or another agent in your workspace — actually did over a time window: messages sent, documents created, calls made, plus a summary (run counts, per-day, top tools). Use this to answer 'what did I do today / yesterday / last week / in the last hour?' or 'what did <agent> do?' with real data instead of guessing. Omit `agent` for your own activity, or pass another workspace agent's name, slug, or id. Pass `since`/`until` as ISO datetimes (e.g. '2026-06-03T09:00:00') for sub-day windows like the last hour, or plain dates ('2026-06-03') for whole days — compute them from the current date/time you were given. Defaults to the last 24h. Traces are retained 30 days. Times are interpreted as UTC — if the current time you were given is in another timezone, convert to UTC before passing since/until.

Parameters4

agent	string	optional	Target agent: name, slug, or numeric id. OMIT for yourself.
since	string	optional	Window start — ISO datetime or date. OMIT for last 24h.
until	string	optional	Window end — ISO datetime or date (exclusive day-end for a bare date). OMIT for now.
limit	integer	optional	Max actions / recent runs to return.

Raw schema

{
  "type": "object",
  "properties": {
    "agent": {
      "type": "string",
      "description": "Target agent: name, slug, or numeric id. OMIT for yourself."
    },
    "since": {
      "type": "string",
      "description": "Window start — ISO datetime or date. OMIT for last 24h."
    },
    "until": {
      "type": "string",
      "description": "Window end — ISO datetime or date (exclusive day-end for a bare date). OMIT for now."
    },
    "limit": {
      "type": "integer",
      "description": "Max actions / recent runs to return.",
      "minimum": 1,
      "maximum": 200,
      "default": 50
    }
  },
  "required": []
}

agents_prompt_history

List past versions of an agent's `prompt_text`. Every edit to the agent's prompt is snapshotted to an append-only table — use this tool to browse history, find a prior known-good version, and copy it into `agents.prompt_restore`.

Parameters3

agent_id	integer	required	ID of the agent
limit	integer	optional	Max versions to return (1-200, default 50)
before_version	integer	optional	Cursor: return versions strictly below this version_number

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent"
    },
    "limit": {
      "type": "integer",
      "description": "Max versions to return (1-200, default 50)",
      "minimum": 1,
      "maximum": 200,
      "default": 50
    },
    "before_version": {
      "type": "integer",
      "description": "Cursor: return versions strictly below this version_number",
      "minimum": 1
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_prompt_restore

Restore a past version of an agent's `prompt_text` by version_number. Creates a new version pointing at the restored content — history is preserved. Use `agents.prompt_history` first to find the version_number you want.

Parameters3

agent_id	integer	required	ID of the agent
version_number	integer	required	The version_number to restore (get it from agents.prompt_history)
reason	string	optional	Optional: why this restore is happening (shows up in history UI)

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent"
    },
    "version_number": {
      "type": "integer",
      "description": "The version_number to restore (get it from agents.prompt_history)",
      "minimum": 1
    },
    "reason": {
      "type": "string",
      "description": "Optional: why this restore is happening (shows up in history UI)"
    }
  },
  "required": [
    "agent_id",
    "version_number"
  ]
}

agents_simulate_inbound

Replay an inbound message on a thread through the real trigger pipeline and return what would have happened. The router auto-picks the winning enabled agent + trigger by priority/specificity (same logic as production). By default send_mode='draft' so no real message is sent; pass send_mode='auto' on a test account to let the matched agent actually deliver (drafts get overwritten by the next draft, so 'auto' is the only way to verify Telegram/email delivery end-to-end). Use to verify routing for a thread: which agent answers, which trigger wins, or — when nothing matches — the structured skip reason. Pass blockchain_tx_data instead of message_text to simulate a blockchain:transfer event on the thread. Returns: {matched: true, matched_agent: {id, name, execution_mode}, matched_trigger: {id, trigger_type, conditions, specificity_score}, routing_reason, response_text, messages[], execution_mode, send_mode, model_used, tokens_input, tokens_output, latency_ms, rag_queries_made, rag_results_used} on a hit, or {matched: false, skip_reason, simulator_warnings} on a miss.

Parameters8

thread_id	integer	optional	Thread ID to route the simulated event from. Must belong to the API key's workspace. Omit and set create_new_livechat=true to test on a FRESH thread with no history.
create_new_livechat	boolean	optional	Start a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. OMIT to reuse an existing thread_id. Ignored if thread_id is given.
channel_account_id	integer	optional	Optional. The livechat widget's channel_account_id to host the fresh chat when create_new_livechat=true. Omit to auto-pick the workspace's active livechat widget.
message_text	string	optional	Inbound message body to simulate. Defaults to '[MCP simulation test]' when omitted.
blockchain_tx_data	object	optional	When set, simulate a blockchain:transfer event instead of a channel:message:new event. Expected keys: chain, to_address / from_address, tx_hash.
attachment_file_ids	array	optional	Optional list of workspace file IDs to attach to the simulated inbound message — same shape as a real Telegram message with image/document attachments. Use this to test agent behavior on incoming messages that carry images (e.g. logos for invoices) or documents the agent must reference. File IDs must belong to the API key's workspace.
send_mode	string	optional	How the matched agent should deliver its reply. 'draft' (default, safe) creates a draft only — no real send, no idempotency key. 'auto' lets the agent deliver through the channel adapter exactly as it would in production — use this on a test account to verify Telegram/email delivery end-to-end. Drafts get overwritten by the next draft on the thread, so 'auto' is required when you want to see the message persisted.
system_message	object	optional	Tag the simulated inbound as a system/service-message row (missed call, group join, pinned message, etc.) so the `excluded_system_message_kinds` trigger filter can be exercised end-to-end. Shape: {"category": <one of call_event \| membership_change \| contact_signup \| pinned_message \| chat_metadata_change \| voice_chat_event \| other_service>, "native_kind": <free-form upstream event class name, e.g. 'MessageActionPhoneCall'>}. The category is written into `message.meta.system_message` (mirroring the real Telegram ingest path) AND surfaced on the synthetic IncomingEvent so the trigger evaluator honors the block-list. Omit for a normal text-message simulation.

Raw schema

{
  "type": "object",
  "properties": {
    "thread_id": {
      "type": "integer",
      "description": "Thread ID to route the simulated event from. Must belong to the API key's workspace. Omit and set create_new_livechat=true to test on a FRESH thread with no history."
    },
    "create_new_livechat": {
      "type": "boolean",
      "description": "Start a FRESH, history-free livechat chat instead of using an existing thread_id — creates a new visitor + thread on the workspace's livechat widget and routes your message onto it. The response's thread_id is the new thread; pass it back (with send_mode='auto') to continue the conversation. Ideal for clean multi-turn text tests. OMIT to reuse an existing thread_id. Ignored if thread_id is given."
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Optional. The livechat widget's channel_account_id to host the fresh chat when create_new_livechat=true. Omit to auto-pick the workspace's active livechat widget."
    },
    "message_text": {
      "type": "string",
      "description": "Inbound message body to simulate. Defaults to '[MCP simulation test]' when omitted."
    },
    "blockchain_tx_data": {
      "type": "object",
      "description": "When set, simulate a blockchain:transfer event instead of a channel:message:new event. Expected keys: chain, to_address / from_address, tx_hash."
    },
    "attachment_file_ids": {
      "type": "array",
      "description": "Optional list of workspace file IDs to attach to the simulated inbound message — same shape as a real Telegram message with image/document attachments. Use this to test agent behavior on incoming messages that carry images (e.g. logos for invoices) or documents the agent must reference. File IDs must belong to the API key's workspace.",
      "items": {
        "type": "integer"
      }
    },
    "send_mode": {
      "type": "string",
      "description": "How the matched agent should deliver its reply. 'draft' (default, safe) creates a draft only — no real send, no idempotency key. 'auto' lets the agent deliver through the channel adapter exactly as it would in production — use this on a test account to verify Telegram/email delivery end-to-end. Drafts get overwritten by the next draft on the thread, so 'auto' is required when you want to see the message persisted.",
      "enum": [
        "draft",
        "auto"
      ],
      "default": "draft"
    },
    "system_message": {
      "type": "object",
      "description": "Tag the simulated inbound as a system/service-message row (missed call, group join, pinned message, etc.) so the `excluded_system_message_kinds` trigger filter can be exercised end-to-end. Shape: {\"category\": <one of call_event | membership_change | contact_signup | pinned_message | chat_metadata_change | voice_chat_event | other_service>, \"native_kind\": <free-form upstream event class name, e.g. 'MessageActionPhoneCall'>}. The category is written into `message.meta.system_message` (mirroring the real Telegram ingest path) AND surfaced on the synthetic IncomingEvent so the trigger evaluator honors the block-list. Omit for a normal text-message simulation."
    }
  },
  "required": []
}

agents_update_from_template

Update a forked agent's instructions (prompt) to the latest version of the system template it was created from. Use when the platform has improved a template and the user wants their forked agent to pick up the new prompt. This OVERWRITES the agent's prompt_text with the template's current prompt — any customizations to the prompt are replaced (recoverable via prompt history). Tool/model/execution settings are NOT changed. Only works on agents forked from a template (not from-scratch agents or templates themselves).

Parameters1

agent_id

integer

required

ID of the forked agent to update from its template

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the forked agent to update from its template"
    }
  },
  "required": [
    "agent_id"
  ]
}

agents_set_integration

Enable or disable a connected workspace integration on an AI agent — this controls which ext<id>_<name> integration tools the agent (and its sandboxed workbench runs) may call. Use integrations_list to get the workspace_integration_id. When enabling with no explicit denied_tools, WRITE-class tools are auto-disabled by default (read tools stay on); pass denied_tools=[] to force-allow everything, or a list of ext slugs / bare tool names to block specific ones. Idempotent upsert — safe to call repeatedly.

Parameters4

agent_id	integer	required	ID of the agent to configure
workspace_integration_id	integer	required	ID of the connected integration (from integrations_list)
enabled	boolean	optional	True to enable the integration on this agent, False to disable
denied_tools	array	optional	Optional explicit block-list of tool names to deny (ext slugs or bare names). Omit to auto-deny WRITE-class tools on first enable; pass [] to allow all.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to configure"
    },
    "workspace_integration_id": {
      "type": "integer",
      "description": "ID of the connected integration (from integrations_list)"
    },
    "enabled": {
      "type": "boolean",
      "description": "True to enable the integration on this agent, False to disable",
      "default": true
    },
    "denied_tools": {
      "type": "array",
      "description": "Optional explicit block-list of tool names to deny (ext slugs or bare names). Omit to auto-deny WRITE-class tools on first enable; pass [] to allow all.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "agent_id",
    "workspace_integration_id"
  ]
}

agents_list_integrations

List the workspace integrations enabled (or available) for an AI agent, with each one's workspace_integration_id, provider, enabled flag, and count of denied tools. Use this to see what an agent can call before toggling with agents_set_integration.

Parameters1

agent_id

integer

required

ID of the agent to inspect

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "ID of the agent to inspect"
    }
  },
  "required": [
    "agent_id"
  ]
}

collections_list

List all knowledge collections in the workspace. Collections are named groups of files used for RAG search. Auto-created collections (per-agent, per-prompt) are hidden by default.

Parameters1

include_inactive

boolean

optional

Include inactive collections. OMIT to list only active collections (the default).

Raw schema

{
  "type": "object",
  "properties": {
    "include_inactive": {
      "type": "boolean",
      "description": "Include inactive collections. OMIT to list only active collections (the default)."
    }
  },
  "required": []
}

collections_create

Create a named knowledge collection. Collections group files for RAG search. After creating, add files with collections.add_file and assign to agents with collections.assign_agent.

Parameters2

name	string	required	Collection name (must be unique per user)
description	string	optional	Optional description of the collection

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Collection name (must be unique per user)",
      "minimum": 1,
      "maximum": 255
    },
    "description": {
      "type": "string",
      "description": "Optional description of the collection"
    }
  },
  "required": [
    "name"
  ]
}

collections_delete

Delete a knowledge collection. If the collection is assigned to agents, prompts, or channels, pass force=true to delete anyway. CASCADE removes all assignments automatically.

Parameters2

collection_id	integer	required	ID of the collection to delete
force	boolean	optional	Force delete even if collection is in use. OMIT for the safe default (refuse to delete in-use collections).

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection to delete"
    },
    "force": {
      "type": "boolean",
      "description": "Force delete even if collection is in use. OMIT for the safe default (refuse to delete in-use collections)."
    }
  },
  "required": [
    "collection_id"
  ]
}

collections_add_file

Add a file to a knowledge collection. The file must be uploaded and indexed first (files_upload + files_ingest). If the file was previously removed, it is re-enabled.

Parameters2

collection_id	integer	required	ID of the collection
file_id	integer	required	ID of the file to add (from files_upload)

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection"
    },
    "file_id": {
      "type": "integer",
      "description": "ID of the file to add (from files_upload)"
    }
  },
  "required": [
    "collection_id",
    "file_id"
  ]
}

collections_remove_file

Remove a file from a knowledge collection. The file itself is not deleted — only the collection membership is removed.

Parameters2

collection_id	integer	required	ID of the collection
file_id	integer	required	ID of the file to remove

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection"
    },
    "file_id": {
      "type": "integer",
      "description": "ID of the file to remove"
    }
  },
  "required": [
    "collection_id",
    "file_id"
  ]
}

collections_list_files

List all files in a knowledge collection with their indexing status and chunk counts. Each returned file has a `file_id` (integer) that can be passed to messages.send as `attachments=[file_id]` to send the file to a contact, or to files.read to read its text content.

Parameters1

collection_id

integer

required

ID of the collection

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection"
    }
  },
  "required": [
    "collection_id"
  ]
}

collections_assign_agent

Assign a knowledge collection to an AI agent. Once assigned, the agent's knowledge.query will automatically scope RAG search to files in its assigned collections.

Parameters2

collection_id	integer	required	ID of the collection to assign
agent_id	integer	required	ID of the AI agent

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection to assign"
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of the AI agent"
    }
  },
  "required": [
    "collection_id",
    "agent_id"
  ]
}

collections_unassign_agent

Remove a knowledge collection from an AI agent. The collection and its files are not deleted — only the agent assignment is removed.

Parameters2

collection_id	integer	required	ID of the collection to unassign
agent_id	integer	required	ID of the AI agent

Raw schema

{
  "type": "object",
  "properties": {
    "collection_id": {
      "type": "integer",
      "description": "ID of the collection to unassign"
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of the AI agent"
    }
  },
  "required": [
    "collection_id",
    "agent_id"
  ]
}

prompts_list

List all prompt templates in this workspace. Returns id + name + description + category so you know which prompt_id to use in prompts.get or prompts.update.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

prompts_get

Get full content of a prompt template: system instructions (prompt_text) and auto-reply rules. Run prompts.list first to find the prompt_id.

Parameters1

prompt_id

integer

required

ID of the prompt template to fetch

Raw schema

{
  "type": "object",
  "properties": {
    "prompt_id": {
      "type": "integer",
      "description": "ID of the prompt template to fetch"
    }
  },
  "required": [
    "prompt_id"
  ]
}

prompts_update

Update a prompt template's name, system instructions, or auto-reply rules. Changes affect every agent using this template, unless the agent has its own override (set via agents.update → prompt_text). All parameters except prompt_id are optional — only provided fields are updated.

Parameters5

prompt_id	integer	required	ID of the prompt template to update
name	string	optional	New name for the prompt template
description	string	optional	New description for the prompt template
prompt_text	string	optional	The AI system prompt: persona, tone, rules, behavior.
auto_reply_rules	string	optional	Pre-classifier rules that run BEFORE the main AI. Format: bullet list of conditions → actions (SKIP / SIMPLE_REPLY / SEARCH / CALENDAR). Pass null to clear.

Raw schema

{
  "type": "object",
  "properties": {
    "prompt_id": {
      "type": "integer",
      "description": "ID of the prompt template to update"
    },
    "name": {
      "type": "string",
      "description": "New name for the prompt template"
    },
    "description": {
      "type": "string",
      "description": "New description for the prompt template"
    },
    "prompt_text": {
      "type": "string",
      "description": "The AI system prompt: persona, tone, rules, behavior."
    },
    "auto_reply_rules": {
      "type": "string",
      "description": "Pre-classifier rules that run BEFORE the main AI. Format: bullet list of conditions → actions (SKIP / SIMPLE_REPLY / SEARCH / CALENDAR). Pass null to clear."
    }
  },
  "required": [
    "prompt_id"
  ]
}

prompts_prompt_history

List past versions of a prompt template's `prompt_text`. Every edit is snapshotted to an append-only table — use this to browse history and find a version_number for `prompts.prompt_restore`.

Parameters3

prompt_id	integer	required	ID of the prompt template
limit	integer	optional	Max versions to return (1-200, default 50)
before_version	integer	optional	Cursor: return versions strictly below this version_number

Raw schema

{
  "type": "object",
  "properties": {
    "prompt_id": {
      "type": "integer",
      "description": "ID of the prompt template"
    },
    "limit": {
      "type": "integer",
      "description": "Max versions to return (1-200, default 50)",
      "minimum": 1,
      "maximum": 200,
      "default": 50
    },
    "before_version": {
      "type": "integer",
      "description": "Cursor: return versions strictly below this version_number",
      "minimum": 1
    }
  },
  "required": [
    "prompt_id"
  ]
}

prompts_prompt_restore

Restore a past version of a prompt template by version_number. Creates a new version pointing at the restored content — history is preserved. Fans out to every agent using this template without a per-agent override; the response includes `affected_agents` as a receipt of the fan-out.

Parameters3

prompt_id	integer	required	ID of the prompt template
version_number	integer	required	The version_number to restore (get it from prompts.prompt_history)
reason	string	optional	Optional: why this restore is happening (shows up in history UI)

Raw schema

{
  "type": "object",
  "properties": {
    "prompt_id": {
      "type": "integer",
      "description": "ID of the prompt template"
    },
    "version_number": {
      "type": "integer",
      "description": "The version_number to restore (get it from prompts.prompt_history)",
      "minimum": 1
    },
    "reason": {
      "type": "string",
      "description": "Optional: why this restore is happening (shows up in history UI)"
    }
  },
  "required": [
    "prompt_id",
    "version_number"
  ]
}

widgets_list

List all livechat widgets. Returns widgets with their configuration, embed code, and status. Use this when user wants to see their widgets or chat widgets.

Parameters1

active_only

boolean

optional

Only return active widgets. OMIT to include inactive widgets too.

Raw schema

{
  "type": "object",
  "properties": {
    "active_only": {
      "type": "boolean",
      "description": "Only return active widgets. OMIT to include inactive widgets too."
    }
  },
  "required": []
}

widgets_create

Create a new livechat widget for your website. The widget will be created with default settings. You can customize theme, auto-reply mode, and more. Use this when user wants to add a chat widget to their site.

Parameters8

name	string	required	Name for the widget (e.g., 'Website Chat', 'Support Widget')
auto_reply_mode	string	optional	Auto-reply mode: 'draft' (review before sending) or 'auto' (send immediately)
primary_color	string	optional	Primary color for widget theme (hex, e.g., '#2563eb')
position	string	optional	Widget position on screen
header_title	string	optional	Title shown in chat header
display_mode	string	optional	Visual mode of the widget. Pick exactly one: - 'chat' (default): full chat panel + voice mic — use for support / sales / general. - 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget (e.g. 'just a voice button', 'no chat, just call'). - 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design' / 'no widget chrome'.
allow_voice	boolean	optional	Master switch for voice — set true to show the mic so visitors can talk to the agent. Everything else voice-related is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave voice off (the default).
voice_button_label	string	optional	Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if omitted.

Raw schema

{
  "type": "object",
  "properties": {
    "name": {
      "type": "string",
      "description": "Name for the widget (e.g., 'Website Chat', 'Support Widget')"
    },
    "auto_reply_mode": {
      "type": "string",
      "description": "Auto-reply mode: 'draft' (review before sending) or 'auto' (send immediately)",
      "enum": [
        "draft",
        "auto"
      ],
      "default": "draft"
    },
    "primary_color": {
      "type": "string",
      "description": "Primary color for widget theme (hex, e.g., '#2563eb')",
      "default": "#2563eb"
    },
    "position": {
      "type": "string",
      "description": "Widget position on screen",
      "enum": [
        "bottom-right",
        "bottom-left"
      ],
      "default": "bottom-right"
    },
    "header_title": {
      "type": "string",
      "description": "Title shown in chat header",
      "default": "Chat with us"
    },
    "display_mode": {
      "type": "string",
      "description": "Visual mode of the widget. Pick exactly one:\n- 'chat' (default): full chat panel + voice mic — use for support / sales / general.\n- 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget (e.g. 'just a voice button', 'no chat, just call').\n- 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design' / 'no widget chrome'.",
      "enum": [
        "chat",
        "voice_only",
        "headless"
      ],
      "default": "chat"
    },
    "allow_voice": {
      "type": "boolean",
      "description": "Master switch for voice — set true to show the mic so visitors can talk to the agent. Everything else voice-related is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave voice off (the default)."
    },
    "voice_button_label": {
      "type": "string",
      "description": "Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if omitted."
    }
  },
  "required": [
    "name"
  ]
}

widgets_update

Update an existing livechat widget configuration. You can change name, theme, auto-reply mode, and other settings. Only provided fields will be updated. Use this when user wants to modify their chat widget settings.

Parameters29

widget_id	integer	required	ID of the widget to update
name	string	optional	New name for the widget
auto_reply_mode	string	optional	Auto-reply mode: 'draft' or 'auto'. OMIT to leave the auto-reply mode unchanged.
primary_color	string	optional	Primary color for widget theme (hex, e.g., '#2563eb')
position	string	optional	Widget position on screen. OMIT to leave the position unchanged.
header_title	string	optional	Title shown in chat header
header_subtitle	string	optional	Subtitle shown in chat header
is_active	boolean	optional	Enable or disable the widget. OMIT to leave the active flag unchanged.
allowed_domains	array	optional	List of allowed domains for the widget
calendly_url	string	optional	Booking URL for calendar action (e.g., 'https://calendly.com/yourname')
contact_form_fields	array	optional	Fields to collect in contact form (e.g., ['name', 'email', 'phone'])
require_identification	boolean	optional	Require visitor to identify before chatting. OMIT to leave the identification policy unchanged.
identification_fields	array	optional	Fields to require for visitor identification (e.g., ['name', 'email'])
website_url	string	optional	Website URL for product/site search integration
enable_search_action	boolean	optional	Enable or disable the search action button. OMIT to leave this flag unchanged.
enable_form_action	boolean	optional	Enable or disable the contact form action button. OMIT to leave this flag unchanged.
enable_calendar_action	boolean	optional	Enable or disable the calendar booking action button. OMIT to leave this flag unchanged.
greeting_text	string	optional	Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?')
returning_greeting_text	string	optional	Greeting for returning visitors who already have chat history (e.g., 'Welcome back! How can I help you today?'). Falls back to greeting_text if not set.
greeting_enabled	boolean	optional	Enable or disable the proactive greeting. OMIT to leave this flag unchanged.
greeting_delay_seconds	integer	optional	Delay in seconds before the proactive greeting appears (0–300). 0 = send immediately on page load. Default: 30.
greeting_behavior	string	optional	notification = show badge after delay; auto_open = open widget automatically after delay; on_open = greet only when visitor manually opens. OMIT to leave the greeting behavior unchanged.
color_scheme	string	optional	Widget color scheme. 'auto' follows the visitor's OS dark/light mode preference. OMIT to leave the color scheme unchanged.
show_visitor_history	boolean	optional	Show full chat history to returning visitors. OMIT to leave this flag unchanged.
allow_voice	boolean	optional	Master switch for voice on this widget — set true to show the mic and let visitors talk to the agent. Everything else voice-related (greeting, button label, STT/TTS from the agent's own config) is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave the setting unchanged.
max_voice_duration_seconds	integer	optional	Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged.
voice_greeting	string	optional	Spoken opening line when a visitor starts a voice call through this widget. Played via TTS before the AI model runs. Empty string disables the greeting. Requires allow_voice=true to be audible.
display_mode	string	optional	Visual mode of the widget. Pick exactly one: - 'chat': full chat panel + voice mic — default for support / sales / general. - 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget. - 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design'. OMIT to leave the display mode unchanged.
voice_button_label	string	optional	Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if not set.

Raw schema

{
  "type": "object",
  "properties": {
    "widget_id": {
      "type": "integer",
      "description": "ID of the widget to update"
    },
    "name": {
      "type": "string",
      "description": "New name for the widget"
    },
    "auto_reply_mode": {
      "type": "string",
      "description": "Auto-reply mode: 'draft' or 'auto'. OMIT to leave the auto-reply mode unchanged.",
      "enum": [
        "draft",
        "auto"
      ]
    },
    "primary_color": {
      "type": "string",
      "description": "Primary color for widget theme (hex, e.g., '#2563eb')"
    },
    "position": {
      "type": "string",
      "description": "Widget position on screen. OMIT to leave the position unchanged.",
      "enum": [
        "bottom-right",
        "bottom-left"
      ]
    },
    "header_title": {
      "type": "string",
      "description": "Title shown in chat header"
    },
    "header_subtitle": {
      "type": "string",
      "description": "Subtitle shown in chat header"
    },
    "is_active": {
      "type": "boolean",
      "description": "Enable or disable the widget. OMIT to leave the active flag unchanged."
    },
    "allowed_domains": {
      "type": "array",
      "description": "List of allowed domains for the widget",
      "items": {
        "type": "string"
      }
    },
    "calendly_url": {
      "type": "string",
      "description": "Booking URL for calendar action (e.g., 'https://calendly.com/yourname')"
    },
    "contact_form_fields": {
      "type": "array",
      "description": "Fields to collect in contact form (e.g., ['name', 'email', 'phone'])",
      "items": {
        "type": "string"
      }
    },
    "require_identification": {
      "type": "boolean",
      "description": "Require visitor to identify before chatting. OMIT to leave the identification policy unchanged."
    },
    "identification_fields": {
      "type": "array",
      "description": "Fields to require for visitor identification (e.g., ['name', 'email'])",
      "items": {
        "type": "string"
      }
    },
    "website_url": {
      "type": "string",
      "description": "Website URL for product/site search integration"
    },
    "enable_search_action": {
      "type": "boolean",
      "description": "Enable or disable the search action button. OMIT to leave this flag unchanged."
    },
    "enable_form_action": {
      "type": "boolean",
      "description": "Enable or disable the contact form action button. OMIT to leave this flag unchanged."
    },
    "enable_calendar_action": {
      "type": "boolean",
      "description": "Enable or disable the calendar booking action button. OMIT to leave this flag unchanged."
    },
    "greeting_text": {
      "type": "string",
      "description": "Custom greeting message shown when visitor opens the chat (e.g., 'Hello! How can I help you today?')"
    },
    "returning_greeting_text": {
      "type": "string",
      "description": "Greeting for returning visitors who already have chat history (e.g., 'Welcome back! How can I help you today?'). Falls back to greeting_text if not set."
    },
    "greeting_enabled": {
      "type": "boolean",
      "description": "Enable or disable the proactive greeting. OMIT to leave this flag unchanged."
    },
    "greeting_delay_seconds": {
      "type": "integer",
      "description": "Delay in seconds before the proactive greeting appears (0–300). 0 = send immediately on page load. Default: 30."
    },
    "greeting_behavior": {
      "type": "string",
      "description": "notification = show badge after delay; auto_open = open widget automatically after delay; on_open = greet only when visitor manually opens. OMIT to leave the greeting behavior unchanged.",
      "enum": [
        "notification",
        "auto_open",
        "on_open"
      ]
    },
    "color_scheme": {
      "type": "string",
      "description": "Widget color scheme. 'auto' follows the visitor's OS dark/light mode preference. OMIT to leave the color scheme unchanged.",
      "enum": [
        "light",
        "dark",
        "auto"
      ]
    },
    "show_visitor_history": {
      "type": "boolean",
      "description": "Show full chat history to returning visitors. OMIT to leave this flag unchanged."
    },
    "allow_voice": {
      "type": "boolean",
      "description": "Master switch for voice on this widget — set true to show the mic and let visitors talk to the agent. Everything else voice-related (greeting, button label, STT/TTS from the agent's own config) is inert until this is on. The mic also needs a voice-capable agent in the workspace: one with an enabled incoming_call trigger. OMIT to leave the setting unchanged."
    },
    "max_voice_duration_seconds": {
      "type": "integer",
      "description": "Hard cap on a single voice call from this widget, in seconds (default 300). OMIT to leave the cap unchanged."
    },
    "voice_greeting": {
      "type": "string",
      "description": "Spoken opening line when a visitor starts a voice call through this widget. Played via TTS before the AI model runs. Empty string disables the greeting. Requires allow_voice=true to be audible."
    },
    "display_mode": {
      "type": "string",
      "description": "Visual mode of the widget. Pick exactly one:\n- 'chat': full chat panel + voice mic — default for support / sales / general.\n- 'voice_only': mic-only bubble that launches a voice call directly — pick only when the user explicitly asks for a voice-only widget.\n- 'headless': no UI; customer drives via window.DialogBrain JS API — pick only when the user explicitly says 'embed in our own design'.\nOMIT to leave the display mode unchanged.",
      "enum": [
        "chat",
        "voice_only",
        "headless"
      ]
    },
    "voice_button_label": {
      "type": "string",
      "description": "Localized aria-label and hover tooltip for the voice-only mic bubble (only used when display_mode='voice_only'). ≤ 100 chars. Defaults to 'Talk to agent' if not set."
    }
  },
  "required": [
    "widget_id"
  ]
}

widgets_delete

Delete a livechat widget permanently. This will remove the widget and its embed code will stop working. Existing chat history will be preserved. Use this when user wants to remove a chat widget.

Parameters1

widget_id

integer

required

ID of the widget to delete

Raw schema

{
  "type": "object",
  "properties": {
    "widget_id": {
      "type": "integer",
      "description": "ID of the widget to delete"
    }
  },
  "required": [
    "widget_id"
  ]
}

widgets_get_embed_code

Get the embed code snippet for a livechat widget. Returns HTML/JavaScript code to add to your website. The code should be placed before the closing </body> tag. Use this when user wants to install the chat widget on their site.

Parameters1

widget_id

integer

required

ID of the widget to get embed code for

Raw schema

{
  "type": "object",
  "properties": {
    "widget_id": {
      "type": "integer",
      "description": "ID of the widget to get embed code for"
    }
  },
  "required": [
    "widget_id"
  ]
}

widgets_get

Get full configuration of a single livechat widget. Returns all settings including theme, identification, actions, and more. Use this when user wants to see or verify a specific widget's settings.

Parameters1

widget_id

integer

required

ID of the widget to retrieve

Raw schema

{
  "type": "object",
  "properties": {
    "widget_id": {
      "type": "integer",
      "description": "ID of the widget to retrieve"
    }
  },
  "required": [
    "widget_id"
  ]
}

linkedin_search

Search LinkedIn for people, companies, jobs, or posts. Supports filtering by keywords, location, industry, network distance, and more. Use linkedin.search_filters first to resolve filter keywords to LinkedIn parameter IDs.

Parameters10

category	string	optional	What to search for
keywords	string	optional	Search keywords
api	string	optional	LinkedIn product to search with
location	array	optional	Location filter IDs (use linkedin.search_filters to resolve)
industry	array	optional	Industry filter IDs
network_distance	string	optional	Connection degree: F=1st, S=2nd, O=3rd+
has_job_offers	boolean	optional	Filter for people with job offers
role	string	optional	Role/title filter
url	string	optional	Direct LinkedIn search URL (alternative to keyword/filter search)
limit	integer	optional	Maximum results to return

Raw schema

{
  "type": "object",
  "properties": {
    "category": {
      "type": "string",
      "enum": [
        "people",
        "companies",
        "jobs",
        "posts"
      ],
      "default": "people",
      "description": "What to search for"
    },
    "keywords": {
      "type": "string",
      "description": "Search keywords"
    },
    "api": {
      "type": "string",
      "enum": [
        "classic",
        "sales_navigator",
        "recruiter"
      ],
      "default": "classic",
      "description": "LinkedIn product to search with"
    },
    "location": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Location filter IDs (use linkedin.search_filters to resolve)"
    },
    "industry": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Industry filter IDs"
    },
    "network_distance": {
      "type": "string",
      "enum": [
        "F",
        "S",
        "O"
      ],
      "description": "Connection degree: F=1st, S=2nd, O=3rd+"
    },
    "has_job_offers": {
      "type": "boolean",
      "description": "Filter for people with job offers"
    },
    "role": {
      "type": "string",
      "description": "Role/title filter"
    },
    "url": {
      "type": "string",
      "description": "Direct LinkedIn search URL (alternative to keyword/filter search)"
    },
    "limit": {
      "type": "integer",
      "default": 25,
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum results to return"
    }
  },
  "required": []
}

linkedin_search_filters

Get LinkedIn search filter parameter IDs. LinkedIn uses internal IDs instead of text for search filters (location, industry, etc.). Call this before linkedin.search to resolve filter keywords to their LinkedIn parameter IDs.

Parameters3

type	string	required	Filter category to resolve (e.g. LOCATION, INDUSTRY, SKILL)
keywords	string	required	Keywords to resolve to parameter IDs (e.g. 'Thailand' for LOCATION)
limit	integer	optional	Max results per filter category

Raw schema

{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "LOCATION",
        "PEOPLE",
        "CONNECTIONS",
        "COMPANY",
        "SCHOOL",
        "INDUSTRY",
        "SERVICE",
        "JOB_FUNCTION",
        "JOB_TITLE",
        "EMPLOYMENT_TYPE",
        "SKILL"
      ],
      "description": "Filter category to resolve (e.g. LOCATION, INDUSTRY, SKILL)"
    },
    "keywords": {
      "type": "string",
      "description": "Keywords to resolve to parameter IDs (e.g. 'Thailand' for LOCATION)"
    },
    "limit": {
      "type": "integer",
      "default": 10,
      "minimum": 1,
      "maximum": 50,
      "description": "Max results per filter category"
    }
  },
  "required": [
    "type",
    "keywords"
  ]
}

linkedin_get_profile

Get a LinkedIn user profile by ID, public identifier (vanity name), or profile URL. Returns name, headline, location, and other profile information.

Parameters1

identifier

string

required

LinkedIn member ID, public identifier (vanity name), or full profile URL

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "LinkedIn member ID, public identifier (vanity name), or full profile URL"
    }
  },
  "required": [
    "identifier"
  ]
}

linkedin_get_company

Get a LinkedIn company profile by company ID or vanity name. Returns company name, description, industry, size, and other details.

Parameters1

identifier

string

required

Company ID or vanity name

Raw schema

{
  "type": "object",
  "properties": {
    "identifier": {
      "type": "string",
      "description": "Company ID or vanity name"
    }
  },
  "required": [
    "identifier"
  ]
}

linkedin_update_profile

Update the authenticated user's own LinkedIn profile. Supports adding/editing experience entries (role, company, skills, dates). Also supports updating location. Headline, summary, education are NOT supported by the API.

Parameters2

location	object	optional	Location to set on profile (requires LinkedIn location ID)
experience	object	optional	Add or edit a professional experience entry

Raw schema

{
  "type": "object",
  "properties": {
    "location": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "LinkedIn location ID (use linkedin.search_filters with type=LOCATION to find)"
        },
        "postal_code": {
          "type": "string",
          "description": "5-digit postal code (optional)"
        }
      },
      "required": [
        "id"
      ],
      "description": "Location to set on profile (requires LinkedIn location ID)"
    },
    "experience": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string",
          "description": "ID of existing experience to edit (omit to add new)"
        },
        "role": {
          "type": "string",
          "description": "Job title (required for new experience)"
        },
        "company": {
          "type": "string",
          "description": "Company name (required for new experience)"
        },
        "company_id": {
          "type": "string",
          "description": "LinkedIn company ID (optional)"
        },
        "description": {
          "type": "string",
          "description": "Role description"
        },
        "skills": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Skills for this experience"
        },
        "seniority": {
          "type": "object",
          "properties": {
            "start_date": {
              "type": "object",
              "properties": {
                "month": {
                  "type": "number"
                },
                "year": {
                  "type": "number"
                }
              },
              "required": [
                "month",
                "year"
              ]
            },
            "end_date": {
              "type": "object",
              "properties": {
                "month": {
                  "type": "number"
                },
                "year": {
                  "type": "number"
                }
              }
            }
          },
          "required": [
            "start_date"
          ],
          "description": "Start/end dates for the experience"
        },
        "presence": {
          "type": "string",
          "enum": [
            "ON_SITE",
            "HYBRID",
            "REMOTE"
          ],
          "description": "Work location type"
        }
      },
      "description": "Add or edit a professional experience entry"
    }
  },
  "required": []
}

linkedin_invite

Send a connection invitation to a LinkedIn user. Optionally include a personalized message (max 300 characters). Rate limited: LinkedIn allows 80-100 invitations per day, max 200 per week.

Parameters2

provider_id	string	required	LinkedIn provider ID of the person to invite (from search results or profile)
message	string	optional	Optional personalized invitation message (max 300 characters)

Raw schema

{
  "type": "object",
  "properties": {
    "provider_id": {
      "type": "string",
      "description": "LinkedIn provider ID of the person to invite (from search results or profile)"
    },
    "message": {
      "type": "string",
      "maxLength": 300,
      "description": "Optional personalized invitation message (max 300 characters)"
    }
  },
  "required": [
    "provider_id"
  ]
}

linkedin_list_connections

List your LinkedIn connections, sorted by most recently added.

Parameters2

limit	integer	optional	Maximum connections to return
cursor	string	optional	Pagination cursor from previous response

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum connections to return"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from previous response"
    }
  },
  "required": []
}

linkedin_list_invitations_sent

List your pending sent connection invitations on LinkedIn.

Parameters2

limit	integer	optional	Maximum invitations to return
cursor	string	optional	Pagination cursor from previous response

Raw schema

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "default": 50,
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum invitations to return"
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor from previous response"
    }
  },
  "required": []
}

linkedin_list_reactions

List all reactions (likes, celebrates, etc.) on a specific LinkedIn post.

Parameters2

post_id	string	required	LinkedIn post/activity ID
limit	integer	optional	Maximum reactions to return

Raw schema

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "LinkedIn post/activity ID"
    },
    "limit": {
      "type": "integer",
      "default": 50,
      "minimum": 1,
      "maximum": 100,
      "description": "Maximum reactions to return"
    }
  },
  "required": [
    "post_id"
  ]
}

linkedin_add_comment

Add a comment to a LinkedIn post. Use post_id from search results or thread data.

Parameters2

post_id	string	required	LinkedIn post/activity ID (from search results or thread metadata)
text	string	required	Comment text to post

Raw schema

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "LinkedIn post/activity ID (from search results or thread metadata)"
    },
    "text": {
      "type": "string",
      "description": "Comment text to post"
    }
  },
  "required": [
    "post_id",
    "text"
  ]
}

linkedin_raw_request

Send an arbitrary LinkedIn API request via Unipile's magic route. Only GET and POST methods are allowed. WARNING: This bypasses structured rate limiting and can perform destructive actions. Use this only when no other LinkedIn tool covers the needed functionality.

Parameters4

request_url	string	required	Target LinkedIn API endpoint URL
method	string	optional	HTTP method (only GET and POST allowed)
query_params	object	optional	URL query parameters
body	object	optional	Request body (for POST requests)

Raw schema

{
  "type": "object",
  "properties": {
    "request_url": {
      "type": "string",
      "description": "Target LinkedIn API endpoint URL"
    },
    "method": {
      "type": "string",
      "enum": [
        "GET",
        "POST"
      ],
      "default": "GET",
      "description": "HTTP method (only GET and POST allowed)"
    },
    "query_params": {
      "type": "object",
      "description": "URL query parameters"
    },
    "body": {
      "type": "object",
      "description": "Request body (for POST requests)"
    }
  },
  "required": [
    "request_url"
  ]
}

search_messages

Search message content across all chats — semantic + keyword. Use to find what was said: quotes, topics, info exchanged. For chats/threads themselves use search.threads; for files use search.files; for links use search.links.

Parameters5

query	string	optional	What to search for in message content.
participant_name	string	optional	Filter to messages involving this participant/contact name. OMIT to search across everyone (do NOT pass an empty string).
date_from	string	optional	ISO8601 date (YYYY-MM-DD) lower bound. OMIT to skip.
date_to	string	optional	ISO8601 date (YYYY-MM-DD) upper bound. OMIT to skip.
limit	integer	optional	Maximum messages to return.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to search for in message content."
    },
    "participant_name": {
      "type": "string",
      "description": "Filter to messages involving this participant/contact name. OMIT to search across everyone (do NOT pass an empty string)."
    },
    "date_from": {
      "type": "string",
      "description": "ISO8601 date (YYYY-MM-DD) lower bound. OMIT to skip."
    },
    "date_to": {
      "type": "string",
      "description": "ISO8601 date (YYYY-MM-DD) upper bound. OMIT to skip."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum messages to return.",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": []
}

search_threads

Find or list chat threads/conversations — by topic, participant, unread/unanswered status, or recency. Omit `query` to list threads by filter. For message content use search.messages; for files use search.files. `since` filters by recency and pairs with only_unread / only_unanswered.

Parameters7

query	string	optional	Topic/keyword to search threads for. OMIT to list threads by filter.
participant_name	string	optional	Filter to threads with this participant/contact. OMIT to include everyone (do NOT pass an empty string).
only_unread	boolean	optional	Limit to threads with unread messages. OMIT to include read threads.
only_unanswered	boolean	optional	Limit to threads where the last message is incoming (you haven't replied). Covers 'threads I haven't replied to'. OMIT to include answered threads too.
since	string	optional	ISO date (YYYY-MM-DD). Only threads with any message activity since this date (recency filter, not 'unanswered'). OMIT to skip.
limit	integer	optional	Maximum threads to return.
include_last_messages	integer	optional	With only_unanswered: inline the most recent N messages (0-2) per thread so one call is enough to draft replies. Text truncated to 150 chars; full body via messages.read_history.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Topic/keyword to search threads for. OMIT to list threads by filter."
    },
    "participant_name": {
      "type": "string",
      "description": "Filter to threads with this participant/contact. OMIT to include everyone (do NOT pass an empty string)."
    },
    "only_unread": {
      "type": "boolean",
      "description": "Limit to threads with unread messages. OMIT to include read threads."
    },
    "only_unanswered": {
      "type": "boolean",
      "description": "Limit to threads where the last message is incoming (you haven't replied). Covers 'threads I haven't replied to'. OMIT to include answered threads too."
    },
    "since": {
      "type": "string",
      "description": "ISO date (YYYY-MM-DD). Only threads with any message activity since this date (recency filter, not 'unanswered'). OMIT to skip."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum threads to return.",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    },
    "include_last_messages": {
      "type": "integer",
      "description": "With only_unanswered: inline the most recent N messages (0-2) per thread so one call is enough to draft replies. Text truncated to 150 chars; full body via messages.read_history.",
      "minimum": 0,
      "maximum": 2
    }
  },
  "required": []
}

search_files

Search files and attachments across the workspace — by content, filename, document type, or origin. For message content use search.messages; for links use search.links.

Parameters5

query	string	optional	What to search for (content or filename).
attachment_name	string	optional	Exact filename filter. OMIT to skip (do NOT pass an empty string).
document_type	string	optional	Filter by document category. OMIT unless the user explicitly mentions one — picking a value narrows the search and is a common cause of zero-result mistakes.
file_origin	string	optional	File origin: 'generated' (created by tools), 'received' (from messages), 'uploaded' (manual). Use 'generated' for files the user created/sent. OMIT to include all origins.
limit	integer	optional	Maximum files to return.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to search for (content or filename)."
    },
    "attachment_name": {
      "type": "string",
      "description": "Exact filename filter. OMIT to skip (do NOT pass an empty string)."
    },
    "document_type": {
      "type": "string",
      "description": "Filter by document category. OMIT unless the user explicitly mentions one — picking a value narrows the search and is a common cause of zero-result mistakes.",
      "enum": [
        "invoice",
        "contract",
        "presentation",
        "report",
        "proposal",
        "resume",
        "letter",
        "manual",
        "spreadsheet"
      ]
    },
    "file_origin": {
      "type": "string",
      "description": "File origin: 'generated' (created by tools), 'received' (from messages), 'uploaded' (manual). Use 'generated' for files the user created/sent. OMIT to include all origins.",
      "enum": [
        "generated",
        "received",
        "uploaded"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Maximum files to return.",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": []
}

search_links

Search links/URLs shared across the workspace — by type, owner, or associated contact. For files use search.files; for message content use search.messages.

Parameters5

query	string	optional	What to search for in shared links.
link_kind	string	optional	Filter links by type. OMIT to include all kinds — picking a value narrows the search and is a common cause of zero-result mistakes.
owner	string	optional	Link owner: 'self' (user's own) or 'contact' (from others). OMIT to include links regardless of owner.
contact_hint	string	optional	Name hint to filter links for a specific contact. OMIT to skip.
limit	integer	optional	Maximum links to return.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "What to search for in shared links."
    },
    "link_kind": {
      "type": "string",
      "description": "Filter links by type. OMIT to include all kinds — picking a value narrows the search and is a common cause of zero-result mistakes.",
      "enum": [
        "email",
        "calendly",
        "twitter",
        "telegram",
        "linkedin",
        "github",
        "google_doc",
        "google_sheet",
        "google_slides",
        "google_drive",
        "google_meet",
        "instagram",
        "facebook",
        "youtube",
        "tiktok",
        "whatsapp",
        "vk",
        "reddit",
        "medium",
        "discord",
        "notion",
        "figma",
        "telegraph",
        "luma",
        "etherscan",
        "website"
      ]
    },
    "owner": {
      "type": "string",
      "description": "Link owner: 'self' (user's own) or 'contact' (from others). OMIT to include links regardless of owner.",
      "enum": [
        "self",
        "contact",
        "unknown"
      ]
    },
    "contact_hint": {
      "type": "string",
      "description": "Name hint to filter links for a specific contact. OMIT to skip."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum links to return.",
      "minimum": 1,
      "maximum": 50,
      "default": 10
    }
  },
  "required": []
}

workspace_list

List every workspace the caller is a member of, with `is_current` marking the workspace this MCP key is currently routed to. Pair with `workspace.switch` to change the active workspace without reconnecting.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

workspace_current

Return the workspace this MCP API key is currently routed to, with the caller's role inside it. Use this to confirm context before/after `workspace.switch`.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

workspace_switch

Re-point the active MCP API key to a different workspace. Pass exactly one of `workspace_id` or `slug` (find them via `workspace.list`). Takes effect on the very next tool call — no MCP reconnect, no new API key. Sequential checkpoint: do not parallelize tool calls across a switch — calls already in flight when the switch commits will run against the previous workspace. Keys created with workspace_locked=true refuse to switch (they are pinned to their workspace so concurrent sessions sharing a key cannot re-route each other); use a key belonging to the target workspace instead.

Parameters2

workspace_id	integer	optional	Numeric workspace id to switch to. Mutually exclusive with `slug`.
slug	string	optional	Workspace slug to switch to. Resolved within the caller's memberships, so cross-tenant slug collisions are not possible. Mutually exclusive with `workspace_id`.

Raw schema

{
  "type": "object",
  "properties": {
    "workspace_id": {
      "type": "integer",
      "description": "Numeric workspace id to switch to. Mutually exclusive with `slug`."
    },
    "slug": {
      "type": "string",
      "description": "Workspace slug to switch to. Resolved within the caller's memberships, so cross-tenant slug collisions are not possible. Mutually exclusive with `workspace_id`."
    }
  },
  "required": []
}

integrations_list

List the workspace's external integrations (HTTP-API + MCP), each with its id, provider name, base_url, transport, status, and registered tool count. Use before integrations.add_endpoints to find the integration id / base_url.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": []
}

integrations_get_endpoints

List every endpoint (operationId, method, path) registered on an HTTP-API integration. Identify it by `integration_id` or `base_url`. Use this to review what tools exist before integrations.remove_endpoints or add_endpoints.

Parameters2

integration_id	integer	optional	Integration id (from integrations.list).
base_url	string	optional	Or the integration's base URL, e.g. https://api.boomnow.com

Raw schema

{
  "type": "object",
  "properties": {
    "integration_id": {
      "type": "integer",
      "description": "Integration id (from integrations.list)."
    },
    "base_url": {
      "type": "string",
      "description": "Or the integration's base URL, e.g. https://api.boomnow.com"
    }
  },
  "required": []
}

integrations_add_endpoints

Add one or more API endpoints to an HTTP-API integration as callable tools, merged additively into the integration for `base_url` (created if none exists). Each endpoint becomes a tool with params + request/response schemas inferred from the samples you pass. When CREATING a new integration, provide auth: either `identity` (saved Browser Identity name/id) for cookie-session APIs, OR an `auth` block for token/header APIs, e.g. {type:'bearer', token:'...'} or {type:'api_key', token:'...', header_name:'X-API-Key'}. Updates keep the existing auth unless a new `auth` is passed. Returns the new tool count and names. Refresh the tools list afterwards to use them.

Parameters6

base_url	string	required	API base URL of the integration, e.g. https://api.boomnow.com
endpoints	array	required	Endpoints to add. Each: {method, path, query?(object), request_body?(object sample), response_body?(object/array sample)}. path is relative to base_url, e.g. /api/conversations/all.
identity	string	optional	Saved Browser Identity name or numeric id — one way to auth a NEW cookie-session integration (updates reuse existing auth). For token/header APIs use `auth` instead.
auth	object	optional	Auth block for a NEW token/header integration (or to change auth on update): {type: none\|bearer\|api_key\|basic\|custom_headers, ...}. bearer/basic → {token}; api_key → {token, header_name?}; custom_headers → {headers:{name:value,...}}. Token values are encrypted. Omit for browser_identity (use `identity`) or to keep existing auth.
name	string	optional	Display name when creating a new integration. OMIT to default to the host.
extract	object	optional	Explicit browser_identity auth extract for a NEW integration when auto-detect can't find one, e.g. {kind:'cookie', name:'_session', value_format:'raw', header_name:'Cookie', header_template:'{{name}}={{value}}'}. Updates reuse existing auth, so omit then.

Raw schema

{
  "type": "object",
  "properties": {
    "base_url": {
      "type": "string",
      "description": "API base URL of the integration, e.g. https://api.boomnow.com"
    },
    "endpoints": {
      "type": "array",
      "description": "Endpoints to add. Each: {method, path, query?(object), request_body?(object sample), response_body?(object/array sample)}. path is relative to base_url, e.g. /api/conversations/all.",
      "items": {
        "type": "object"
      }
    },
    "identity": {
      "type": "string",
      "description": "Saved Browser Identity name or numeric id — one way to auth a NEW cookie-session integration (updates reuse existing auth). For token/header APIs use `auth` instead."
    },
    "auth": {
      "type": "object",
      "description": "Auth block for a NEW token/header integration (or to change auth on update): {type: none|bearer|api_key|basic|custom_headers, ...}. bearer/basic → {token}; api_key → {token, header_name?}; custom_headers → {headers:{name:value,...}}. Token values are encrypted. Omit for browser_identity (use `identity`) or to keep existing auth."
    },
    "name": {
      "type": "string",
      "description": "Display name when creating a new integration. OMIT to default to the host."
    },
    "extract": {
      "type": "object",
      "description": "Explicit browser_identity auth extract for a NEW integration when auto-detect can't find one, e.g. {kind:'cookie', name:'_session', value_format:'raw', header_name:'Cookie', header_template:'{{name}}={{value}}'}. Updates reuse existing auth, so omit then."
    }
  },
  "required": [
    "base_url",
    "endpoints"
  ]
}

integrations_remove_endpoints

Remove endpoints (tools) from an HTTP-API integration — e.g. junk paths like static assets, /socket.io, or SPA routes that aren't real API calls. Identify the integration by `integration_id` or `base_url`, and the endpoints to drop by `operation_ids` (e.g. getSocketIo) and/or `paths` (e.g. /socket.io/). Re-registers the catalog so the removed tools disappear. Returns removed + remaining counts.

Parameters4

integration_id	integer	optional	Integration id (from integrations.list).
base_url	string	optional	Or the integration's base URL.
operation_ids	array	optional	operationIds to remove, e.g. ["getSocketIo","getPieScreensMenu"].
paths	array	optional	Exact spec paths to remove (all methods), e.g. ["/socket.io/"].

Raw schema

{
  "type": "object",
  "properties": {
    "integration_id": {
      "type": "integer",
      "description": "Integration id (from integrations.list)."
    },
    "base_url": {
      "type": "string",
      "description": "Or the integration's base URL."
    },
    "operation_ids": {
      "type": "array",
      "description": "operationIds to remove, e.g. [\"getSocketIo\",\"getPieScreensMenu\"].",
      "items": {
        "type": "string"
      }
    },
    "paths": {
      "type": "array",
      "description": "Exact spec paths to remove (all methods), e.g. [\"/socket.io/\"].",
      "items": {
        "type": "string"
      }
    }
  },
  "required": []
}

integrations_set_auth

Set or update the authentication on an HTTP-API integration, generically. Identify it by `integration_id` or `base_url`. Pass `auth` = {type: bearer|api_key|basic|custom_headers|browser_identity|none, ...}: bearer/basic → {token}; api_key → {token, header_name?}; custom_headers → {headers:{name:value,...}}; browser_identity → {identity_id|identity_name, extract}. Token values are encrypted; nothing is stored in cleartext. To only refresh a browser_identity session, OMIT `auth` and pass `cookies` (and/or `local_storage`) — they are merged into the bound identity without touching its config. (oauth2 / service_account use the REST settings flow.)

Parameters5

integration_id	integer	optional	Integration id (from integrations.list).
base_url	string	optional	Or the integration's base URL, e.g. https://api.boomnow.com.
auth	object	optional	Auth to set: {type, token?, header_name?, headers?(object), identity_id?, identity_name?, extract?(object)}. Omit to only refresh cookies on an existing browser_identity integration.
cookies	array	optional	Cookies to merge into the bound browser identity. Each {name, value, domain?, path?, expires?}. Existing names are overwritten; new ones added.
local_storage	array	optional	localStorage entries to merge. Each {origin, name, value}.

Raw schema

{
  "type": "object",
  "properties": {
    "integration_id": {
      "type": "integer",
      "description": "Integration id (from integrations.list)."
    },
    "base_url": {
      "type": "string",
      "description": "Or the integration's base URL, e.g. https://api.boomnow.com."
    },
    "auth": {
      "type": "object",
      "description": "Auth to set: {type, token?, header_name?, headers?(object), identity_id?, identity_name?, extract?(object)}. Omit to only refresh cookies on an existing browser_identity integration."
    },
    "cookies": {
      "type": "array",
      "description": "Cookies to merge into the bound browser identity. Each {name, value, domain?, path?, expires?}. Existing names are overwritten; new ones added.",
      "items": {
        "type": "object"
      }
    },
    "local_storage": {
      "type": "array",
      "description": "localStorage entries to merge. Each {origin, name, value}.",
      "items": {
        "type": "object"
      }
    }
  },
  "required": []
}

integrations_capture_session

Restore an expired integration session by capturing the LIVE auth of an open browser page — works for COOKIE sessions (browser_identity) AND TOKEN/HEADER sessions (bearer / api_key / custom_headers, e.g. Devise access-token/client/uid). First call browser_open(url, identity_name) for the integration's site (the page must be logged in AND have called its API), then pass that `page_id` here with `integration_id` or `base_url`. For cookie sessions it captures the full storage_state (incl httpOnly cookies page JS can't read) into the bound identity; for token sessions it captures the auth headers the page sends to the API host and binds them. Re-connects the integration. The captured secret never leaves the server (returns counts only). Generic — any site, any auth scheme, no local Playwright.

Parameters3

page_id	string	required	page_id from a prior browser_open of the integration's site (logged in).
integration_id	integer	optional	Integration id (from integrations.list).
base_url	string	optional	Or the integration's base URL, e.g. https://api.boomnow.com.

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "description": "page_id from a prior browser_open of the integration's site (logged in)."
    },
    "integration_id": {
      "type": "integer",
      "description": "Integration id (from integrations.list)."
    },
    "base_url": {
      "type": "string",
      "description": "Or the integration's base URL, e.g. https://api.boomnow.com."
    }
  },
  "required": [
    "page_id"
  ]
}

job_read_context

Read the current job context. Returns the full state of your active job including assignments, escalations, and any data you previously stored.

Parameters1

job_id

integer

optional

The ID of the job to read

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "description": "The ID of the job to read"
    }
  },
  "required": []
}

job_update_context

Update the job context by merging new data. Existing keys are preserved unless explicitly overwritten. Use this to record progress, update assignment statuses, or store intermediate results.

Parameters2

job_id	integer	optional	The ID of the job to update
updates	object	required	Key-value pairs to merge into job context

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "description": "The ID of the job to update"
    },
    "updates": {
      "type": "object",
      "description": "Key-value pairs to merge into job context"
    }
  },
  "required": [
    "updates"
  ]
}

job_complete

Mark the job as completed. This sanitizes PII from the context and records a completion summary. Use when all tasks in the job are done.

Parameters2

job_id	integer	optional	The ID of the job to complete
summary	string	optional	Brief summary of what was accomplished

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "description": "The ID of the job to complete"
    },
    "summary": {
      "type": "string",
      "description": "Brief summary of what was accomplished"
    }
  },
  "required": []
}

job_escalate

Escalate the job to a human. Use when you cannot resolve an issue, someone is not responding, or a situation requires human judgment.

Parameters2

job_id	integer	optional	The ID of the job to escalate
reason	string	required	Why escalation is needed

Raw schema

{
  "type": "object",
  "properties": {
    "job_id": {
      "type": "integer",
      "description": "The ID of the job to escalate"
    },
    "reason": {
      "type": "string",
      "description": "Why escalation is needed"
    }
  },
  "required": [
    "reason"
  ]
}

notes_save

Save a fact or note into the agent's memory. Use scope to choose visibility: 'workspace' = visible to every agent in this workspace (use for shared facts, project conventions); 'agent' = private to this agent (use for personal working notes); 'thread' = scoped to one conversation (use for thread-specific reminders); 'person' = scoped to one contact (use for per-contact context). If a note with the same key+scope exists it will be updated. Do NOT use this tool for behavioral rules or corrections — use feedback.save for those.

Parameters7

target_agent_id	integer	optional	Target notebook. In agent mode optional (defaults to your own); required from MCP. Agents cannot target other agents' notebooks. Ignored when scope='workspace' (workspace memory is shared).
key	string	required	Short identifier for this note (must not start with '__' — reserved)
value	string	required	The note content
scope	string	required	Scope of the note. 'workspace' = shared across all agents; 'agent' = private to this agent (was 'global' pre-PR1); 'thread' = per-conversation; 'person' = per-contact. 'global' is accepted as a deprecation alias for 'agent'.
scope_ref_id	string	optional	Reference ID — thread_id (for scope=thread) or person_id (for scope=person). Required for thread/person scope. In MCP mode (no thread context), must be passed explicitly.
expires_in_hours	integer	optional	Auto-delete after N hours. Omit for permanent notes.
pinned	boolean	optional	Pin this note so it's always loaded first. Default false.

Raw schema

{
  "type": "object",
  "properties": {
    "target_agent_id": {
      "type": "integer",
      "description": "Target notebook. In agent mode optional (defaults to your own); required from MCP. Agents cannot target other agents' notebooks. Ignored when scope='workspace' (workspace memory is shared)."
    },
    "key": {
      "type": "string",
      "description": "Short identifier for this note (must not start with '__' — reserved)"
    },
    "value": {
      "type": "string",
      "description": "The note content"
    },
    "scope": {
      "type": "string",
      "enum": [
        "workspace",
        "agent",
        "thread",
        "person",
        "global"
      ],
      "description": "Scope of the note. 'workspace' = shared across all agents; 'agent' = private to this agent (was 'global' pre-PR1); 'thread' = per-conversation; 'person' = per-contact. 'global' is accepted as a deprecation alias for 'agent'."
    },
    "scope_ref_id": {
      "type": "string",
      "description": "Reference ID — thread_id (for scope=thread) or person_id (for scope=person). Required for thread/person scope. In MCP mode (no thread context), must be passed explicitly."
    },
    "expires_in_hours": {
      "type": "integer",
      "description": "Auto-delete after N hours. Omit for permanent notes."
    },
    "pinned": {
      "type": "boolean",
      "description": "Pin this note so it's always loaded first. Default false."
    }
  },
  "required": [
    "key",
    "value",
    "scope"
  ]
}

notes_recall

Recall notes from your notebook. By default returns only your own notes (all scopes, newest first). Pass filter_agent_id=<int> to read another agent's notebook, or filter_agent_id="all" (or "*") to read across every agent in the workspace. Pass scope to narrow to global/thread/person. Each result includes agent_id and agent_name of the author.

Parameters5

filter_agent_id	string	optional	Optional. Omit to read only your own notes. Pass a numeric agent_id as a string (e.g. "57") to read another agent's notebook (read-only). Pass "all" or "*" to read across all agents in the workspace.
scope	string	optional	Optional filter: global \| thread \| person. Omit for all scopes.
scope_ref_id	string	optional	Filter by specific thread_id or person_id
key	string	optional	Recall a specific note by key
limit	integer	optional	Max notes (default 20, max 50). Newest first.

Raw schema

{
  "type": "object",
  "properties": {
    "filter_agent_id": {
      "type": "string",
      "description": "Optional. Omit to read only your own notes. Pass a numeric agent_id as a string (e.g. \"57\") to read another agent's notebook (read-only). Pass \"all\" or \"*\" to read across all agents in the workspace."
    },
    "scope": {
      "type": "string",
      "enum": [
        "global",
        "thread",
        "person"
      ],
      "description": "Optional filter: global | thread | person. Omit for all scopes."
    },
    "scope_ref_id": {
      "type": "string",
      "description": "Filter by specific thread_id or person_id"
    },
    "key": {
      "type": "string",
      "description": "Recall a specific note by key"
    },
    "limit": {
      "type": "integer",
      "description": "Max notes (default 20, max 50). Newest first."
    }
  },
  "required": []
}

notes_search

Full-text search in your notebook. By default searches only your own notes. Pass filter_agent_id=<int> to search another agent's notebook, or "all" (or "*") for workspace-wide. Or list all notes for a person/thread by scope_ref_id.

Parameters5

filter_agent_id	string	optional	Optional. Omit to search only your own notes. Pass a numeric agent_id as a string (e.g. "57") to search another agent's notebook (read-only). Pass "all" or "*" to search across all agents in the workspace.
query	string	optional	Text to search for in note keys and values. Optional if scope_ref_id is provided.
scope	string	optional	Limit search to scope
scope_ref_id	string	optional	Filter by specific thread_id or person_id. If provided without query, lists all notes for that ref.
limit	integer	optional	Max results (default 10, max 50)

Raw schema

{
  "type": "object",
  "properties": {
    "filter_agent_id": {
      "type": "string",
      "description": "Optional. Omit to search only your own notes. Pass a numeric agent_id as a string (e.g. \"57\") to search another agent's notebook (read-only). Pass \"all\" or \"*\" to search across all agents in the workspace."
    },
    "query": {
      "type": "string",
      "description": "Text to search for in note keys and values. Optional if scope_ref_id is provided."
    },
    "scope": {
      "type": "string",
      "enum": [
        "global",
        "thread",
        "person"
      ],
      "description": "Limit search to scope"
    },
    "scope_ref_id": {
      "type": "string",
      "description": "Filter by specific thread_id or person_id. If provided without query, lists all notes for that ref."
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 10, max 50)"
    }
  },
  "required": []
}

notes_delete

Delete a note by ID from the target notebook. Same identity rules as notes.save — agents can only delete from their own notebook.

Parameters2

target_agent_id	integer	optional	Target notebook. In agent mode optional (defaults to your own); required from MCP. Agents cannot target other agents' notebooks.
note_id	integer	required	ID of the note to delete

Raw schema

{
  "type": "object",
  "properties": {
    "target_agent_id": {
      "type": "integer",
      "description": "Target notebook. In agent mode optional (defaults to your own); required from MCP. Agents cannot target other agents' notebooks."
    },
    "note_id": {
      "type": "integer",
      "description": "ID of the note to delete"
    }
  },
  "required": [
    "note_id"
  ]
}

feedback_save

Save a behavioral rule, preference, or correction that should guide future agent behavior. Use this when the user gives explicit guidance like 'always reply in Russian', 'don't suggest meetings before 11am', or 'invoice link goes via email, not chat'. Structure the rule as: the rule itself, why it matters (if stated), and how to apply it. Scope: 'workspace' for org-wide rules, 'agent' for per-agent overrides, 'person' for per-contact preferences. Prefer feedback.save over notes.save for anything that's instructive rather than informational.

Parameters7

target_agent_id	integer	optional	Target agent. In agent mode optional (defaults to self); required from MCP. Ignored when scope='workspace'.
key	string	required	Short identifier for this rule (e.g. 'reply_language', 'meeting_hours'). Must not start with '__' (reserved).
rule	string	required	The rule itself, in imperative form. Required.
why	string	optional	Why this rule matters (optional but recommended for the distiller).
how_to_apply	string	optional	When/how to apply the rule (optional). Helpful for conditional rules like 'apply when speaking to Russian-speaking customers'.
scope	string	required	Scope of the rule. 'workspace' for org-wide rules; 'agent' for per-agent overrides; 'thread' for conversation-specific guidance; 'person' for per-contact preferences. 'global' accepted as deprecation alias for 'agent'.
scope_ref_id	string	optional	Required for scope='thread' (thread_id) and scope='person' (person_id).

Raw schema

{
  "type": "object",
  "properties": {
    "target_agent_id": {
      "type": "integer",
      "description": "Target agent. In agent mode optional (defaults to self); required from MCP. Ignored when scope='workspace'."
    },
    "key": {
      "type": "string",
      "description": "Short identifier for this rule (e.g. 'reply_language', 'meeting_hours'). Must not start with '__' (reserved)."
    },
    "rule": {
      "type": "string",
      "description": "The rule itself, in imperative form. Required."
    },
    "why": {
      "type": "string",
      "description": "Why this rule matters (optional but recommended for the distiller)."
    },
    "how_to_apply": {
      "type": "string",
      "description": "When/how to apply the rule (optional). Helpful for conditional rules like 'apply when speaking to Russian-speaking customers'."
    },
    "scope": {
      "type": "string",
      "enum": [
        "workspace",
        "agent",
        "thread",
        "person",
        "global"
      ],
      "description": "Scope of the rule. 'workspace' for org-wide rules; 'agent' for per-agent overrides; 'thread' for conversation-specific guidance; 'person' for per-contact preferences. 'global' accepted as deprecation alias for 'agent'."
    },
    "scope_ref_id": {
      "type": "string",
      "description": "Required for scope='thread' (thread_id) and scope='person' (person_id)."
    }
  },
  "required": [
    "key",
    "rule",
    "scope"
  ]
}

tasks_create

Create a new task in your to-do list.

Parameters9

agent_id	integer	optional	Agent ID whose tasks to access. Required when calling from MCP.
title	string	required	Task title
description	string	optional	Detailed description
priority	string	optional	Task priority (default: medium)
due_at	string	optional	ISO datetime when task is due (e.g. '2026-03-31T15:00:00')
due_date	string	optional	Date when task is due (e.g. '2026-03-31'). Use with due_time or alone.
due_time	string	optional	Time when task is due (e.g. '15:00'). Used with due_date.
assigned_to_contact_id	integer	optional	Contact ID if assigned to someone
thread_id	integer	optional	Related thread ID

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID whose tasks to access. Required when calling from MCP."
    },
    "title": {
      "type": "string",
      "description": "Task title"
    },
    "description": {
      "type": "string",
      "description": "Detailed description"
    },
    "priority": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "urgent"
      ],
      "description": "Task priority (default: medium)"
    },
    "due_at": {
      "type": "string",
      "description": "ISO datetime when task is due (e.g. '2026-03-31T15:00:00')"
    },
    "due_date": {
      "type": "string",
      "description": "Date when task is due (e.g. '2026-03-31'). Use with due_time or alone."
    },
    "due_time": {
      "type": "string",
      "description": "Time when task is due (e.g. '15:00'). Used with due_date."
    },
    "assigned_to_contact_id": {
      "type": "integer",
      "description": "Contact ID if assigned to someone"
    },
    "thread_id": {
      "type": "integer",
      "description": "Related thread ID"
    }
  },
  "required": [
    "title"
  ]
}

tasks_update

Update an existing task. Set status='done' to complete it, 'cancelled' to cancel. Use summary for completion notes.

Parameters7

agent_id	integer	optional	Agent ID whose task to update. Required when calling from MCP.
task_id	integer	required	ID of the task to update
status	string	optional
priority	string	optional
description	string	optional
due_at	string	optional	ISO datetime
summary	string	optional	Completion note (stored when marking done)

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID whose task to update. Required when calling from MCP."
    },
    "task_id": {
      "type": "integer",
      "description": "ID of the task to update"
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "done",
        "cancelled"
      ]
    },
    "priority": {
      "type": "string",
      "enum": [
        "low",
        "medium",
        "high",
        "urgent"
      ]
    },
    "description": {
      "type": "string"
    },
    "due_at": {
      "type": "string",
      "description": "ISO datetime"
    },
    "summary": {
      "type": "string",
      "description": "Completion note (stored when marking done)"
    }
  },
  "required": [
    "task_id"
  ]
}

tasks_list

List your tasks, or another agent's tasks (read-only) using from_agent_id. Use filters to narrow results.

Parameters7

agent_id	integer	optional	Agent ID whose tasks to list. Required when calling from MCP.
status	string	optional
overdue	boolean	optional	If true, only return tasks past due_at that are not done
thread_id	integer	optional	Filter by related thread
assigned_to_contact_id	integer	optional	Filter by assigned contact
limit	integer	optional	Max results (default 20)
from_agent_id	integer	optional	List tasks of another agent (read-only). Omit to list your own.

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID whose tasks to list. Required when calling from MCP."
    },
    "status": {
      "type": "string",
      "enum": [
        "pending",
        "in_progress",
        "done",
        "cancelled"
      ]
    },
    "overdue": {
      "type": "boolean",
      "description": "If true, only return tasks past due_at that are not done"
    },
    "thread_id": {
      "type": "integer",
      "description": "Filter by related thread"
    },
    "assigned_to_contact_id": {
      "type": "integer",
      "description": "Filter by assigned contact"
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 20)"
    },
    "from_agent_id": {
      "type": "integer",
      "description": "List tasks of another agent (read-only). Omit to list your own."
    }
  },
  "required": []
}

tasks_delete

Delete a task from your to-do list by its ID.

Parameters2

agent_id	integer	optional	Agent ID whose task to delete. Required when calling from MCP.
task_id	integer	required	ID of the task to delete

Raw schema

{
  "type": "object",
  "properties": {
    "agent_id": {
      "type": "integer",
      "description": "Agent ID whose task to delete. Required when calling from MCP."
    },
    "task_id": {
      "type": "integer",
      "description": "ID of the task to delete"
    }
  },
  "required": [
    "task_id"
  ]
}

reminder_set

Schedule a reminder. One-time reminders fire at a specific datetime. Recurring reminders fire on a schedule (daily, weekly, every N days, or every N minutes). Optionally scope to a thread or target another agent.

Parameters11

reason	string	required	What this reminder is for (you'll see this when it fires)
schedule_type	string	required	one_time = fires once at datetime. daily = fires daily at time. weekly = fires on specific days_of_week at time. every_n_days = fires every N days at time. interval = fires every N minutes.
datetime	string	optional	ISO datetime for one_time (e.g. '2026-04-01T09:00:00+03:00'). Required for one_time.
time	string	optional	Time of day HH:MM for daily/weekly/every_n_days (e.g. '09:00'). Required for daily/weekly/every_n_days.
timezone	string	optional	IANA timezone (e.g. 'Europe/Moscow'). Defaults to UTC.
days_of_week	array	optional	Days for weekly: 0=Mon, 1=Tue, 2=Wed, 3=Thu, 4=Fri, 5=Sat, 6=Sun. Required for weekly.
interval_days	integer	optional	For every_n_days: fire every N days (min 2).
interval_minutes	integer	optional	For interval: fire every N minutes (5-1440).
thread_id	integer	optional	Optional thread ID to scope the reminder to. Omit for workspace-level reminders.
target_agent_slug	string	optional	Optional: activate a different staff member instead of yourself when the reminder fires.
agent_id	integer	optional	Agent ID (required when calling from MCP; ignored in agentic mode).

Raw schema

{
  "type": "object",
  "properties": {
    "reason": {
      "type": "string",
      "description": "What this reminder is for (you'll see this when it fires)"
    },
    "schedule_type": {
      "type": "string",
      "enum": [
        "one_time",
        "daily",
        "weekly",
        "every_n_days",
        "interval"
      ],
      "description": "one_time = fires once at datetime. daily = fires daily at time. weekly = fires on specific days_of_week at time. every_n_days = fires every N days at time. interval = fires every N minutes."
    },
    "datetime": {
      "type": "string",
      "description": "ISO datetime for one_time (e.g. '2026-04-01T09:00:00+03:00'). Required for one_time."
    },
    "time": {
      "type": "string",
      "description": "Time of day HH:MM for daily/weekly/every_n_days (e.g. '09:00'). Required for daily/weekly/every_n_days."
    },
    "timezone": {
      "type": "string",
      "description": "IANA timezone (e.g. 'Europe/Moscow'). Defaults to UTC."
    },
    "days_of_week": {
      "type": "array",
      "items": {
        "type": "integer"
      },
      "description": "Days for weekly: 0=Mon, 1=Tue, 2=Wed, 3=Thu, 4=Fri, 5=Sat, 6=Sun. Required for weekly."
    },
    "interval_days": {
      "type": "integer",
      "description": "For every_n_days: fire every N days (min 2)."
    },
    "interval_minutes": {
      "type": "integer",
      "description": "For interval: fire every N minutes (5-1440)."
    },
    "thread_id": {
      "type": "integer",
      "description": "Optional thread ID to scope the reminder to. Omit for workspace-level reminders."
    },
    "target_agent_slug": {
      "type": "string",
      "description": "Optional: activate a different staff member instead of yourself when the reminder fires."
    },
    "agent_id": {
      "type": "integer",
      "description": "Agent ID (required when calling from MCP; ignored in agentic mode)."
    }
  },
  "required": [
    "reason",
    "schedule_type"
  ]
}

reminder_list

List your active reminders (both one-time and recurring).

Parameters4

include_fired	boolean	optional	Include already-fired one-time reminders (default false)
thread_id	integer	optional	Filter by thread
limit	integer	optional	Max results (default 20)
agent_id	integer	optional	Agent ID (required when calling from MCP; ignored in agentic mode).

Raw schema

{
  "type": "object",
  "properties": {
    "include_fired": {
      "type": "boolean",
      "description": "Include already-fired one-time reminders (default false)"
    },
    "thread_id": {
      "type": "integer",
      "description": "Filter by thread"
    },
    "limit": {
      "type": "integer",
      "description": "Max results (default 20)"
    },
    "agent_id": {
      "type": "integer",
      "description": "Agent ID (required when calling from MCP; ignored in agentic mode)."
    }
  },
  "required": []
}

reminder_cancel

Cancel an active reminder by its trigger ID.

Parameters2

trigger_id	integer	required	ID of the reminder to cancel
agent_id	integer	optional	Agent ID (required when calling from MCP; ignored in agentic mode).

Raw schema

{
  "type": "object",
  "properties": {
    "trigger_id": {
      "type": "integer",
      "description": "ID of the reminder to cancel"
    },
    "agent_id": {
      "type": "integer",
      "description": "Agent ID (required when calling from MCP; ignored in agentic mode)."
    }
  },
  "required": [
    "trigger_id"
  ]
}

system_sleep

Pause execution for a given number of seconds (max 30). Use when you need to wait for an external process to complete before retrying — e.g. message sync, backfill, or API propagation. Total sleep per run is capped at 60 seconds.

Parameters2

seconds	integer	required	Number of seconds to sleep (1-30)
reason	string	optional	Why you are waiting (logged for debugging)

Raw schema

{
  "type": "object",
  "properties": {
    "seconds": {
      "type": "integer",
      "description": "Number of seconds to sleep (1-30)"
    },
    "reason": {
      "type": "string",
      "description": "Why you are waiting (logged for debugging)"
    }
  },
  "required": [
    "seconds"
  ]
}

calls_make

Place an outbound AUDIO/VOICE phone call via Twilio (PSTN) or Telegram (MTProto 1:1 call). Use this any time the user asks to 'call', 'ring', 'phone', 'dial', or have a spoken conversation. Do NOT use messages.send when the user asks to call someone — a call is real-time voice, not a text message. You conduct the conversation as the voice agent using the provided greeting and instructions.

Parameters11

channel	string	optional	Voice transport: 'twilio' (phone via PSTN — requires phone_number in E.164) or 'telegram' (MTProto 1:1 call — requires telegram_user_id, NOT a phone number or thread_id) or 'android' (Android device voice call — requires phone_number in E.164). OMIT to use the current conversation's channel (e.g. a Telegram DM → a Telegram call to that contact).
phone_number	string	optional	Destination phone number in E.164 format (e.g., '+15551234567', '+66812345678'). Required when channel='twilio'.
telegram_user_id	string	optional	Destination Telegram user ID (decimal int64 as string, e.g. '123456789'). Required when channel='telegram'. The caller account must have had prior interaction with this user — a cold contact cannot be reached via voice.
app	string	optional	Android package that places the call (generic — any app with a dispatch recipe, or manual UI dispatch). Example: 'com.whatsapp'. Used only when channel='android'. Ignored for other channels.
target_display_name	string	optional	LINE only: the contact's LINE display name to place the voice call to (resolved by the planner from the contact). Ignored for other channels/apps.
contact_id	integer	optional	LINE only: the contact entity ID for storing the confirmed display name after placement. Ignored for other channels/apps.
skip_dispatch	boolean	optional	Set true after you placed the call manually with the android_* UI tools — skips the automatic recipe and attaches straight to the already-live call. OMIT for the normal automatic dispatch. Used only when channel='android'. Ignored for other channels.
instructions	string	optional	What to do during the call — objective, questions, tone. The AI generates a natural opening and guides the conversation. Example: 'Call about invoice #1234. Ask if they received it and when payment is expected. Be friendly and professional.'
greeting	string	required	The first sentence the agent speaks immediately when the call connects. ALWAYS provide a greeting — without it the caller hears silence. Keep it short and natural. Example: 'Hi, this is Diana calling from DialogBrain. Do you have a moment to chat?'
report_back	string	optional	When to re-invoke you after the call ends. 'on_answer' (default) = only if the call was answered, 'always' = even on missed/failed calls, 'never' = fire and forget. Transcript is always stored regardless of this setting.
voice_agent_id	integer	optional	ID of the agent that conducts the call (an `id` from agents.list). If omitted, uses the workspace's default voice-capable agent when one exists. Pass this when the call fails with 'No voice agent configured'.

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "description": "Voice transport: 'twilio' (phone via PSTN — requires phone_number in E.164) or 'telegram' (MTProto 1:1 call — requires telegram_user_id, NOT a phone number or thread_id) or 'android' (Android device voice call — requires phone_number in E.164). OMIT to use the current conversation's channel (e.g. a Telegram DM → a Telegram call to that contact).",
      "enum": [
        "twilio",
        "telegram",
        "android"
      ]
    },
    "phone_number": {
      "type": "string",
      "description": "Destination phone number in E.164 format (e.g., '+15551234567', '+66812345678'). Required when channel='twilio'.",
      "pattern": "^\\+[1-9]\\d{9,14}$"
    },
    "telegram_user_id": {
      "type": "string",
      "description": "Destination Telegram user ID (decimal int64 as string, e.g. '123456789'). Required when channel='telegram'. The caller account must have had prior interaction with this user — a cold contact cannot be reached via voice.",
      "pattern": "^[1-9]\\d{0,18}$"
    },
    "app": {
      "type": "string",
      "description": "Android package that places the call (generic — any app with a dispatch recipe, or manual UI dispatch). Example: 'com.whatsapp'. Used only when channel='android'. Ignored for other channels."
    },
    "target_display_name": {
      "type": "string",
      "description": "LINE only: the contact's LINE display name to place the voice call to (resolved by the planner from the contact). Ignored for other channels/apps.",
      "maximum": 200
    },
    "contact_id": {
      "type": "integer",
      "description": "LINE only: the contact entity ID for storing the confirmed display name after placement. Ignored for other channels/apps."
    },
    "skip_dispatch": {
      "type": "boolean",
      "description": "Set true after you placed the call manually with the android_* UI tools — skips the automatic recipe and attaches straight to the already-live call. OMIT for the normal automatic dispatch. Used only when channel='android'. Ignored for other channels."
    },
    "instructions": {
      "type": "string",
      "description": "What to do during the call — objective, questions, tone. The AI generates a natural opening and guides the conversation. Example: 'Call about invoice #1234. Ask if they received it and when payment is expected. Be friendly and professional.'",
      "maximum": 2000
    },
    "greeting": {
      "type": "string",
      "description": "The first sentence the agent speaks immediately when the call connects. ALWAYS provide a greeting — without it the caller hears silence. Keep it short and natural. Example: 'Hi, this is Diana calling from DialogBrain. Do you have a moment to chat?'",
      "maximum": 500
    },
    "report_back": {
      "type": "string",
      "description": "When to re-invoke you after the call ends. 'on_answer' (default) = only if the call was answered, 'always' = even on missed/failed calls, 'never' = fire and forget. Transcript is always stored regardless of this setting."
    },
    "voice_agent_id": {
      "type": "integer",
      "description": "ID of the agent that conducts the call (an `id` from agents.list). If omitted, uses the workspace's default voice-capable agent when one exists. Pass this when the call fails with 'No voice agent configured'."
    }
  },
  "required": [
    "greeting"
  ]
}

calls_agent_duel

Start an agent-vs-agent VOICE test call: two AI voice agents share one LiveKit room — a 'caller' persona agent pursues a task brief against the 'callee' business agent under test. Use to evaluate booking flows, latency, and conversation quality without a human caller. The CALLER agent should have an EMPTY voice_greeting (it must stay silent until the callee greets) and voice_filler_enabled=false. Afterwards inspect both call_ids with agents.traces_list / calls.get_transcript. A subscribe-only `listen` token is returned for listening in live.

Parameters4

callee_agent_id	integer	required	Agent under test (answers and greets first). From agents.list.
caller_agent_id	integer	required	Customer-persona agent that places the call. Must be a different agent, active, with empty voice_greeting.
task	string	required	The caller's brief — objective, persona details (name, phone), and when to end the call. Woven into its prompt as call instructions.
max_duration_s	integer	optional	Hard cap on the call in seconds (30-900, default 300).

Raw schema

{
  "type": "object",
  "properties": {
    "callee_agent_id": {
      "type": "integer",
      "description": "Agent under test (answers and greets first). From agents.list."
    },
    "caller_agent_id": {
      "type": "integer",
      "description": "Customer-persona agent that places the call. Must be a different agent, active, with empty voice_greeting."
    },
    "task": {
      "type": "string",
      "description": "The caller's brief — objective, persona details (name, phone), and when to end the call. Woven into its prompt as call instructions."
    },
    "max_duration_s": {
      "type": "integer",
      "description": "Hard cap on the call in seconds (30-900, default 300).",
      "minimum": 30,
      "maximum": 900
    }
  },
  "required": [
    "callee_agent_id",
    "caller_agent_id",
    "task"
  ]
}

background_run

Run ANOTHER tool off the critical path: returns INSTANTLY while the target tool runs in the background, so a slow write/log/notify never delays your reply. Pass `tool` (the id of a tool you already have) and `args` (the target tool's arguments as a JSON object STRING). Optional `serialize_key` serializes background runs that share the key (e.g. the spreadsheet id when appending rows). Use ONLY for tools whose result you don't need this turn (logging, side-effect writes). Cannot run a tool you don't already have, cannot run a tool that requires approval, and cannot run a tool that deletes data — call those directly. Only callable from within an agent turn.

Parameters3

tool	string	required	Id of the tool to run in the background. Must be a tool you already have.
args	string	required	The target tool's arguments as a JSON object STRING, e.g. '{"spreadsheet_id":"abc","values":[["a","b"]]}'. (A JSON string — not a bare object — so the schema stays valid for strict function-calling on voice.)
serialize_key	string	optional	Optional. Background runs sharing this key run one-at-a-time (e.g. pass the spreadsheet id when appending rows).

Raw schema

{
  "type": "object",
  "properties": {
    "tool": {
      "type": "string",
      "description": "Id of the tool to run in the background. Must be a tool you already have."
    },
    "args": {
      "type": "string",
      "description": "The target tool's arguments as a JSON object STRING, e.g. '{\"spreadsheet_id\":\"abc\",\"values\":[[\"a\",\"b\"]]}'. (A JSON string — not a bare object — so the schema stays valid for strict function-calling on voice.)"
    },
    "serialize_key": {
      "type": "string",
      "description": "Optional. Background runs sharing this key run one-at-a-time (e.g. pass the spreadsheet id when appending rows)."
    }
  },
  "required": [
    "tool",
    "args"
  ]
}

calls_send_to_meet

Dispatch a workspace AI agent into an active Google Meet call. The agent joins as a participant — it can hear the conversation, respond via TTS, see the shared screen (when vision is enabled on the agent), and answer questions about what's on screen. Use when the operator wants to delegate live meeting attendance to an agent (notes, Q&A, summarization, real-time support). The Meet URL must be in canonical 3-4-3 form, e.g. https://meet.google.com/abc-defg-hij. Lookup-redirect URLs are not supported — operator must use the share-link form.

Parameters10

meet_url	string	required	Canonical Google Meet URL — must match https://meet.google.com/<3 letters>-<4 letters>-<3 letters>, e.g. https://meet.google.com/abc-defg-hij. lookup/ redirects are NOT supported.
agent_id	integer	required	ID of an active agent in this workspace. Get it from agents.list. Any active agent can be dispatched — a voice trigger is NOT required (the runner attaches the agent you name directly).
vision_mode	string	optional	Screen-share capture mode. 'off' = no vision (default), 'on_demand' = the agent can call the vision_query tool for fine-detail reads, 'continuous_0_3fps' = the bot captures the screen at 1 fps with phash dedupe and the executor splices the latest scene-change into each agent turn as ambient low-detail context. OMIT to use 'off' (the default).
instructions	string	optional	What the agent should do once it joins — its task brief, e.g. 'greet everyone and present the overview deck' or 'take notes and answer questions about the roadmap'. Woven into the agent's system prompt for the session. OMIT for a generic listening agent. Do NOT set with translation_mode — it is ignored there (translator mode needs no task brief).
start_immediately	boolean	optional	If true, the agent starts talking as soon as it joins — it greets everyone and begins the task in `instructions` without waiting for someone to say a wake-word. OMIT (default false) to stay silent until addressed. MUTUALLY EXCLUSIVE with translation_mode — do NOT set both; translator mode is already hands-free and this is ignored (setting it would break translation).
translation_mode	boolean	optional	If true, pre-arm translator mode (auto-target language) on join with zero verbal trigger. Forces the original-speaker audio track to exist. Requires target_language. OMIT (default false) for normal dispatch. This is the COMPLETE way to dispatch a live translator — do NOT also pass start_immediately or instructions (they are ignored here, and would otherwise start an agentic chat session instead of translating).
target_language	string	optional	PRIMARY target language spoken INTO the Meet call when translation_mode=true (e.g. 'en', 'es', 'fr'). OMIT to not use translation.
app_languages	array	optional	Extra target languages translated for the APP ONLY (shown as subtitles + listenable audio in the inbox), never spoken into the Meet call. Operators switch between them in the UI. ISO codes, e.g. ['de', 'fr']. Max 4. Only with translation_mode=true. OMIT for a single spoken language.
silent	boolean	optional	Silent translator dispatch — the translator NEVER speaks into the Meet call (participants hear no bot voice); translation audio + subtitles stay available inside the app (listen overlay / translator-tts tracks). Only valid with translation_mode=true. OMIT (default false) for a normal spoken translator. Togglable live via calls.mute_translation_tts.
comeback_phrase	string	optional	Optional phrase to trigger return to original language during translation (e.g. 'Back to English'). Only used with translation_mode=true.

Raw schema

{
  "type": "object",
  "properties": {
    "meet_url": {
      "type": "string",
      "description": "Canonical Google Meet URL — must match https://meet.google.com/<3 letters>-<4 letters>-<3 letters>, e.g. https://meet.google.com/abc-defg-hij. lookup/ redirects are NOT supported.",
      "maximum": 120
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of an active agent in this workspace. Get it from agents.list. Any active agent can be dispatched — a voice trigger is NOT required (the runner attaches the agent you name directly)."
    },
    "vision_mode": {
      "type": "string",
      "description": "Screen-share capture mode. 'off' = no vision (default), 'on_demand' = the agent can call the vision_query tool for fine-detail reads, 'continuous_0_3fps' = the bot captures the screen at 1 fps with phash dedupe and the executor splices the latest scene-change into each agent turn as ambient low-detail context. OMIT to use 'off' (the default).",
      "enum": [
        "off",
        "on_demand",
        "continuous_0_3fps"
      ]
    },
    "instructions": {
      "type": "string",
      "description": "What the agent should do once it joins — its task brief, e.g. 'greet everyone and present the overview deck' or 'take notes and answer questions about the roadmap'. Woven into the agent's system prompt for the session. OMIT for a generic listening agent. Do NOT set with translation_mode — it is ignored there (translator mode needs no task brief)."
    },
    "start_immediately": {
      "type": "boolean",
      "description": "If true, the agent starts talking as soon as it joins — it greets everyone and begins the task in `instructions` without waiting for someone to say a wake-word. OMIT (default false) to stay silent until addressed. MUTUALLY EXCLUSIVE with translation_mode — do NOT set both; translator mode is already hands-free and this is ignored (setting it would break translation)."
    },
    "translation_mode": {
      "type": "boolean",
      "description": "If true, pre-arm translator mode (auto-target language) on join with zero verbal trigger. Forces the original-speaker audio track to exist. Requires target_language. OMIT (default false) for normal dispatch. This is the COMPLETE way to dispatch a live translator — do NOT also pass start_immediately or instructions (they are ignored here, and would otherwise start an agentic chat session instead of translating)."
    },
    "target_language": {
      "type": "string",
      "description": "PRIMARY target language spoken INTO the Meet call when translation_mode=true (e.g. 'en', 'es', 'fr'). OMIT to not use translation."
    },
    "app_languages": {
      "type": "array",
      "description": "Extra target languages translated for the APP ONLY (shown as subtitles + listenable audio in the inbox), never spoken into the Meet call. Operators switch between them in the UI. ISO codes, e.g. ['de', 'fr']. Max 4. Only with translation_mode=true. OMIT for a single spoken language.",
      "items": {
        "type": "string"
      }
    },
    "silent": {
      "type": "boolean",
      "description": "Silent translator dispatch — the translator NEVER speaks into the Meet call (participants hear no bot voice); translation audio + subtitles stay available inside the app (listen overlay / translator-tts tracks). Only valid with translation_mode=true. OMIT (default false) for a normal spoken translator. Togglable live via calls.mute_translation_tts."
    },
    "comeback_phrase": {
      "type": "string",
      "description": "Optional phrase to trigger return to original language during translation (e.g. 'Back to English'). Only used with translation_mode=true."
    }
  },
  "required": [
    "meet_url",
    "agent_id"
  ]
}

calls_dispatch_translator

Send a live speech translator to a call. `target` decides where: a meet.google.com link → Google Meet bot; a Telegram @group / t.me link / chat_id → Telegram group voice chat; 'new' (or omitted) → creates a native DialogBrain meeting with translation on and returns the join + guest links; a native meeting call_id or /meeting/ URL → enables translation on that running meeting. Always pass target_language (ISO code); optional app_languages (extra subtitle-only languages), sentence_length (short|medium|long, native only), silent (subtitles without voice, Google Meet only).

Parameters7

target	string	optional	Where to send the translator: a meet.google.com link, a Telegram @group / t.me link / chat_id, 'new' for a fresh native meeting, or an existing native meeting call_id or /meeting/ URL. Omit for a new native meeting.
target_language	string	required	Primary spoken translation target (ISO code, e.g. 'th').
app_languages	array	optional	Extra subtitle-only languages (max 4).
sentence_length	string	optional	Native meetings only: short\|medium\|long buffering (default medium).
silent	boolean	optional	Google Meet only: true = subtitles without speaking into the call. OMIT for a normal speaking translator.
comeback_phrase	string	optional	Attention-recall phrase.
title	string	optional	native_new only: meeting title.

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "Where to send the translator: a meet.google.com link, a Telegram @group / t.me link / chat_id, 'new' for a fresh native meeting, or an existing native meeting call_id or /meeting/ URL. Omit for a new native meeting."
    },
    "target_language": {
      "type": "string",
      "description": "Primary spoken translation target (ISO code, e.g. 'th')."
    },
    "app_languages": {
      "type": "array",
      "description": "Extra subtitle-only languages (max 4).",
      "items": {
        "type": "string"
      }
    },
    "sentence_length": {
      "type": "string",
      "description": "Native meetings only: short|medium|long buffering (default medium)."
    },
    "silent": {
      "type": "boolean",
      "description": "Google Meet only: true = subtitles without speaking into the call. OMIT for a normal speaking translator."
    },
    "comeback_phrase": {
      "type": "string",
      "description": "Attention-recall phrase."
    },
    "title": {
      "type": "string",
      "description": "native_new only: meeting title."
    }
  },
  "required": [
    "target_language"
  ]
}

workbench_run_python

Run Python in an isolated sandbox to process LARGE or paginated tool results without pulling every row into the conversation. Inside the code, call your connected integration tools with `call_tool('ext<id>_<name>', {..})`. RETURN SHAPE: call_tool ALWAYS returns a dict with a boolean r['success']. On SUCCESS the API's JSON is under r['body'], e.g. {'success': True, 'status': 200, 'body': {'results': [{'title': ...}, ...]}} — so read r['body']['results']. On FAILURE r['success'] is False and r['error'] explains. If unsure of the shape, print(r) once and inspect before extracting. Aggregate/filter/paginate in the sandbox, then assign ONLY the small summary you want back to a variable named `result`. FIRST discover exact tool slugs with integrations_search_tools, THEN write code that calls them. pandas/numpy available.

Parameters2

code	string	required	Python source to execute. call_tool('ext<id>_<name>', {..}) returns the integration's raw dict — HTTP success payload is under r['body'] (e.g. r['body']['results']); failure is {'success': False, 'error': ...}. Assign the small summary to `result`. pandas/numpy available.
agent_id	integer	optional	Which agent's tool policy the sandbox runs under — this scopes which ext* integrations call_tool may reach (enabled + denied_tools for that agent). Only needed when calling this tool OUTSIDE a normal agent run (e.g. directly from an external MCP client); during an agent run the running agent is used and this is ignored. Without it, call_tool can reach no integrations.

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Python source to execute. call_tool('ext<id>_<name>', {..}) returns the integration's raw dict — HTTP success payload is under r['body'] (e.g. r['body']['results']); failure is {'success': False, 'error': ...}. Assign the small summary to `result`. pandas/numpy available."
    },
    "agent_id": {
      "type": "integer",
      "description": "Which agent's tool policy the sandbox runs under — this scopes which ext* integrations call_tool may reach (enabled + denied_tools for that agent). Only needed when calling this tool OUTSIDE a normal agent run (e.g. directly from an external MCP client); during an agent run the running agent is used and this is ignored. Without it, call_tool can reach no integrations."
    }
  },
  "required": [
    "code"
  ]
}

analytics_query

Answer analytics questions about this workspace's own data (conversations, messages, voice calls) — e.g. 'how many new conversations this week by channel' or 'inbound vs outbound messages per day this month'. Returns rows plus a chart hint. Read-only and scoped to the current workspace.

Parameters1

question

string

required

The analytics question in natural language, e.g. 'how many conversations started this week, by channel?'

Raw schema

{
  "type": "object",
  "properties": {
    "question": {
      "type": "string",
      "description": "The analytics question in natural language, e.g. 'how many conversations started this week, by channel?'"
    }
  },
  "required": [
    "question"
  ]
}

calls_meet_browser

Attach to a Google Meet bot's live browser to diagnose and recover a bot that isn't visibly joining. Pass the meet session's call_id; returns a page_id. Then drive the bot's Meet page with the generic browser tools (browser.snapshot / browser.click / browser.take_screenshot / browser.evaluate / browser.console_messages / browser.network_requests) using that page_id — read the snapshot to see whether the bot is in the lobby, blocked, or admitted, and click guest-side controls to recover a stalled join. Note: host admission ('Admit') happens in the host's own browser and is not present on the bot's page.

Parameters1

call_id

string

required

The meet session's call_id (UUID), e.g. from calls.send_to_meet's session_id or calls.list_active.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The meet session's call_id (UUID), e.g. from calls.send_to_meet's session_id or calls.list_active."
    }
  },
  "required": [
    "call_id"
  ]
}

calls_set_translation_language

Change the target language of an active voice/Meet call's live translator on the fly — no hangup or re-dispatch (also arms translator mode if it isn't already on). Pass the call_id and an ISO language code, e.g. 'th' (Thai), 'ru' (Russian), 'es' (Spanish), 'en' (English). Takes effect within ~10ms — speak and the translation switches to the new language.

Parameters2

call_id	string	required	The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active.
language	string	required	Target language ISO code: 'th' (Thai), 'ru' (Russian), 'es' (Spanish), 'en' (English), etc.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active."
    },
    "language": {
      "type": "string",
      "description": "Target language ISO code: 'th' (Thai), 'ru' (Russian), 'es' (Spanish), 'en' (English), etc."
    }
  },
  "required": [
    "call_id",
    "language"
  ]
}

calls_set_translation_languages

Set the EXTRA target languages an active voice/Meet call's translator produces for the APP ONLY (subtitles + listenable audio in the inbox — NOT spoken into the call). Operators switch between them in the UI. Pass call_id and `app_languages` (ISO codes, e.g. ['de','fr']); pass [] to drop all extras. Max 4. The primary spoken language is managed by calls.set_translation_language. Takes effect within ~10ms; new languages translate NEW speech only.

Parameters2

call_id	string	required	The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active.
app_languages	array	required	Extra app-only target languages (ISO codes), e.g. ['de','fr','es']. Pass [] to remove all extras. Max 4.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active."
    },
    "app_languages": {
      "type": "array",
      "description": "Extra app-only target languages (ISO codes), e.g. ['de','fr','es']. Pass [] to remove all extras. Max 4.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "call_id",
    "app_languages"
  ]
}

calls_mute_translation_tts

Mute or unmute an active call's live-translation TTS. scope='call' (default, Google Meet sessions ONLY): the translator goes silent INSIDE the call — participants hear no bot voice, in-flight audio is cut immediately, but translation audio + subtitles remain available in the app (listen overlay). scope='everywhere' (any channel): stop synthesizing entirely from the next utterance — subtitles only, no audio anywhere. muted=false reverses either. Translation itself keeps running throughout.

Parameters3

call_id	string	required	The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active.
muted	boolean	required	true to mute, false to unmute.
scope	string	optional	'call' (default; Google Meet only): silent in the call only — app audio + subtitles keep flowing. 'everywhere' (any channel): no TTS synthesis at all (subtitles only). OMIT to use the 'call' default.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "The active call / Meet session call_id (UUID) — e.g. from calls.send_to_meet's session_id or calls.list_active."
    },
    "muted": {
      "type": "boolean",
      "description": "true to mute, false to unmute."
    },
    "scope": {
      "type": "string",
      "description": "'call' (default; Google Meet only): silent in the call only — app audio + subtitles keep flowing. 'everywhere' (any channel): no TTS synthesis at all (subtitles only). OMIT to use the 'call' default.",
      "enum": [
        "call",
        "everywhere"
      ]
    }
  },
  "required": [
    "call_id",
    "muted"
  ]
}

present_tab

Share the agent's browser tab on the live call so everyone sees it as a real screen-share. Pass the page_id you got from browser.open. Only usable while the agent is in an active voice call. The shared tab stays the active share until you call present_tab with a different page_id, close the tab via browser.close, or the call ends.

Parameters1

page_id

string

required

page_id returned by browser.open for the tab you want to share. Must be a tab still open in the agent's browser context.

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "type": "string",
      "description": "page_id returned by browser.open for the tab you want to share. Must be a tab still open in the agent's browser context.",
      "maximum": 128
    }
  },
  "required": [
    "page_id"
  ]
}

calls_send_to_telegram_call

Dispatch a workspace AI agent into a live Telegram GROUP voice chat OR an encrypted call-link conference. FOUR ways to target the call: (1) chat_id — the group's numeric id, e.g. -1001234567890 (use for a private group with no @username); (2) target=@username or a t.me/<group> link; (3) omit both target and chat_id to use the CURRENT thread (when it's a Telegram group); (4) target=t.me/call/<slug> encrypted group-call link. start_if_none=true spawns a new voice chat if the group has none active. The agent joins via the workspace's Telegram account — hears the call, replies via TTS, and sees shared screens (when vision is enabled). NOTE: joining a regular in-group voice chat does NOT need a slug link — pass chat_id directly.

Parameters7

target	string	optional	Telegram call or group to join. Either: (1) encrypted group-call slug (https://t.me/call/<slug> URL or bare slug token, 12-64 chars), (2) group reference (@username or https://t.me/<group> URL), or (3) omit this (and chat_id) to use the current thread (must be a Telegram group chat). Max ~200 chars.
chat_id	integer	optional	Telegram group chat id to join the voice chat of (e.g. -1001234567890 for a supergroup, -4766727451 for a basic group). Use this to target a PRIVATE group that has no @username and isn't the current thread. Overrides `target` when both are given. Group mode only (ignored for slug links).
agent_id	integer	required	ID of an active agent in this workspace. Get it from agents.list. Any active agent can be dispatched — a voice trigger is NOT required (the runner attaches the agent you name directly).
channel_account_id	integer	optional	Workspace Telegram channel account ID that joins as the bot. Optional — when the workspace has exactly one Telegram account, it's used by default. Required when multiple Telegram accounts exist.
vision_mode	string	optional	Screen-share capture mode. 'off' = no vision (default), 'on_demand' = the agent can call vision_query for fine-detail reads, 'continuous_0_3fps' = the bot captures the screen at 1 fps with phash dedupe and splices the latest scene-change into each agent turn. OMIT to use 'off' (the default).
instructions	string	optional	What the agent should do once it joins — its task brief, woven into the voice system prompt. e.g. 'present the overview deck' or 'greet everyone and summarize the discussion'. Optional.
start_if_none	boolean	optional	When joining a group voice chat (not a slug-based encrypted call), spawn a new voice chat if none is active. Default false. Ignored when target is a call slug (a slug IS the call).

Raw schema

{
  "type": "object",
  "properties": {
    "target": {
      "type": "string",
      "description": "Telegram call or group to join. Either: (1) encrypted group-call slug (https://t.me/call/<slug> URL or bare slug token, 12-64 chars), (2) group reference (@username or https://t.me/<group> URL), or (3) omit this (and chat_id) to use the current thread (must be a Telegram group chat). Max ~200 chars.",
      "maximum": 200
    },
    "chat_id": {
      "type": "integer",
      "description": "Telegram group chat id to join the voice chat of (e.g. -1001234567890 for a supergroup, -4766727451 for a basic group). Use this to target a PRIVATE group that has no @username and isn't the current thread. Overrides `target` when both are given. Group mode only (ignored for slug links)."
    },
    "agent_id": {
      "type": "integer",
      "description": "ID of an active agent in this workspace. Get it from agents.list. Any active agent can be dispatched — a voice trigger is NOT required (the runner attaches the agent you name directly)."
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Workspace Telegram channel account ID that joins as the bot. Optional — when the workspace has exactly one Telegram account, it's used by default. Required when multiple Telegram accounts exist."
    },
    "vision_mode": {
      "type": "string",
      "description": "Screen-share capture mode. 'off' = no vision (default), 'on_demand' = the agent can call vision_query for fine-detail reads, 'continuous_0_3fps' = the bot captures the screen at 1 fps with phash dedupe and splices the latest scene-change into each agent turn. OMIT to use 'off' (the default).",
      "enum": [
        "off",
        "on_demand",
        "continuous_0_3fps"
      ]
    },
    "instructions": {
      "type": "string",
      "description": "What the agent should do once it joins — its task brief, woven into the voice system prompt. e.g. 'present the overview deck' or 'greet everyone and summarize the discussion'. Optional.",
      "maximum": 2000
    },
    "start_if_none": {
      "type": "boolean",
      "description": "When joining a group voice chat (not a slug-based encrypted call), spawn a new voice chat if none is active. Default false. Ignored when target is a call slug (a slug IS the call)."
    }
  },
  "required": [
    "agent_id"
  ]
}

calls_list_active

List active voice calls in this workspace. Use before calls.make on a Telegram account (only one MTProto call per account at a time) to check whether the line is free.

Parameters2

channel	string	optional	Filter by voice channel. OMIT to include all channels.
channel_account_id	integer	optional	Filter by channel_account.id (the calling Telegram account or Twilio number). Combine with channel for a per-line busy check.

Raw schema

{
  "type": "object",
  "properties": {
    "channel": {
      "type": "string",
      "description": "Filter by voice channel. OMIT to include all channels.",
      "enum": [
        "telegram",
        "twilio",
        "android"
      ]
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Filter by channel_account.id (the calling Telegram account or Twilio number). Combine with channel for a per-line busy check."
    }
  },
  "required": []
}

calls_get_transcript

Get the structured transcript and final state of a voice call by call_id. Returns per-turn rows in chronological order, call status (active/completed/failed/abandoned), duration, and an `outcome` field telling whether the recipient picked up (answered/no_answer/busy/declined/failed/unknown). `answered_at` is non-null once the recipient picked up. Returns active turns if the call is still in progress.

Parameters1

call_id

string

required

Call ID returned by calls.make in _meta.call_id.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "Call ID returned by calls.make in _meta.call_id.",
      "maximum": 64
    }
  },
  "required": [
    "call_id"
  ]
}

calls_list_history

Search historical voice calls in this workspace by participant name, contact_id, thread, channel, source, and/or date range. Returns one row per call (NOT per turn) with call_id, duration_seconds, outcome, direction, started_at, source, channel_label, and parent_thread_id (the originating chat thread for Telegram-group / Twilio-outbound / Meet calls). Pair with calls.get_transcript(call_id) for the full per-turn transcript. Use this instead of messages.read_history for cross-thread call queries — group calls and Meet sessions live on per-call sub-threads, not on the parent chat thread.

Parameters8

participant_name	string	optional	Filter to calls whose parent thread has a participant matching this name (substring match against entity.title). Resolves group calls via the parent group's roster, not the per-call thread's speaker list.
contact_id	string	optional	Filter by exact entity_id (from contacts.find). Mutually exclusive with participant_name when both target the same person.
thread_id	integer	optional	Restrict to calls on this thread OR with this thread as their originating parent (Telegram group → call sub-thread back-link, Twilio outbound source_thread_id back-link).
channel	string	optional	Filter by message-level channel of the call thread: 'telegram' (1:1 voice or group call sub-thread), 'twilio_voice', 'meet_voice', 'livechat_voice'. OMIT to include all voice channels.
source	string	optional	Filter by voice_sessions.source: 'telegram' (1:1 + group), 'twilio' (PSTN), 'meet' (Google Meet bot), 'livechat' (in-app voice), 'android' (Android device). OMIT to include all sources.
since	string	optional	ISO date or datetime lower bound (inclusive). Default: 90 days ago. Naive timestamps are interpreted as UTC.
until	string	optional	ISO date or datetime upper bound (inclusive). Default: now.
limit	integer	optional	Maximum calls to return (default 20, max 100).

Raw schema

{
  "type": "object",
  "properties": {
    "participant_name": {
      "type": "string",
      "description": "Filter to calls whose parent thread has a participant matching this name (substring match against entity.title). Resolves group calls via the parent group's roster, not the per-call thread's speaker list."
    },
    "contact_id": {
      "type": "string",
      "description": "Filter by exact entity_id (from contacts.find). Mutually exclusive with participant_name when both target the same person."
    },
    "thread_id": {
      "type": "integer",
      "description": "Restrict to calls on this thread OR with this thread as their originating parent (Telegram group → call sub-thread back-link, Twilio outbound source_thread_id back-link)."
    },
    "channel": {
      "type": "string",
      "description": "Filter by message-level channel of the call thread: 'telegram' (1:1 voice or group call sub-thread), 'twilio_voice', 'meet_voice', 'livechat_voice'. OMIT to include all voice channels.",
      "enum": [
        "telegram",
        "twilio_voice",
        "meet_voice",
        "livechat_voice"
      ]
    },
    "source": {
      "type": "string",
      "description": "Filter by voice_sessions.source: 'telegram' (1:1 + group), 'twilio' (PSTN), 'meet' (Google Meet bot), 'livechat' (in-app voice), 'android' (Android device). OMIT to include all sources.",
      "enum": [
        "telegram",
        "twilio",
        "meet",
        "livechat",
        "android"
      ]
    },
    "since": {
      "type": "string",
      "description": "ISO date or datetime lower bound (inclusive). Default: 90 days ago. Naive timestamps are interpreted as UTC."
    },
    "until": {
      "type": "string",
      "description": "ISO date or datetime upper bound (inclusive). Default: now."
    },
    "limit": {
      "type": "integer",
      "description": "Maximum calls to return (default 20, max 100)."
    }
  },
  "required": []
}

calls_wait

Block until a voice call ends (status changes from 'active') or timeout elapses. Returns ended=true with final state when the call has ended; ended=false on timeout (re-issue to keep waiting). The returned state includes `outcome` so callers can branch on pickup vs. no-answer (answered/no_answer/busy/declined/failed/unknown). Default timeout 90s; cap 110s — bounded by nginx proxy_read_timeout 120s on /mcp.

Parameters2

call_id	string	required	Call ID returned by calls.make in _meta.call_id.
timeout_seconds	integer	optional	Max seconds to wait. Default 90, cap 110 (bounded below nginx 120s proxy_read_timeout). On expiry returns ended=False with status='active' so the caller can re-issue to keep waiting.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "Call ID returned by calls.make in _meta.call_id.",
      "maximum": 64
    },
    "timeout_seconds": {
      "type": "integer",
      "description": "Max seconds to wait. Default 90, cap 110 (bounded below nginx 120s proxy_read_timeout). On expiry returns ended=False with status='active' so the caller can re-issue to keep waiting.",
      "minimum": 5,
      "maximum": 110
    }
  },
  "required": [
    "call_id"
  ]
}

calls_hangup

Hang up an active voice call by call_id. Use after calls.make when the agent decides to terminate before the callee does, or to abort a stuck call. Idempotent: returns success if the call is already terminal.

Parameters2

call_id	string	required	Call ID returned by calls.make in _meta.call_id.
reason	string	optional	Short internal reason for ending the call (e.g. 'campaign timeout'). Stored on voice_sessions.metadata.

Raw schema

{
  "type": "object",
  "properties": {
    "call_id": {
      "type": "string",
      "description": "Call ID returned by calls.make in _meta.call_id.",
      "maximum": 64
    },
    "reason": {
      "type": "string",
      "description": "Short internal reason for ending the call (e.g. 'campaign timeout'). Stored on voice_sessions.metadata.",
      "maximum": 200
    }
  },
  "required": [
    "call_id"
  ]
}

android_screenshot

Capture a screenshot from the Android device. Returns JPEG image data encoded as base64.

Parameters1

channel_account_id

integer

optional

Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": []
}

android_tap

Tap on the Android device screen at specified coordinates. Coordinates are in device pixels.

Parameters3

x	integer	required	X coordinate in device pixels
y	integer	required	Y coordinate in device pixels
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "x": {
      "type": "integer",
      "description": "X coordinate in device pixels"
    },
    "y": {
      "type": "integer",
      "description": "Y coordinate in device pixels"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "x",
    "y"
  ]
}

android_swipe

Swipe/drag on the Android device screen from one coordinate to another. Use for scrolling, opening app drawer, etc.

Parameters6

x1	integer	required	Starting X coordinate in device pixels
y1	integer	required	Starting Y coordinate in device pixels
x2	integer	required	Ending X coordinate in device pixels
y2	integer	required	Ending Y coordinate in device pixels
duration_ms	integer	optional	Duration of swipe in milliseconds (default: 300)
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "x1": {
      "type": "integer",
      "description": "Starting X coordinate in device pixels"
    },
    "y1": {
      "type": "integer",
      "description": "Starting Y coordinate in device pixels"
    },
    "x2": {
      "type": "integer",
      "description": "Ending X coordinate in device pixels"
    },
    "y2": {
      "type": "integer",
      "description": "Ending Y coordinate in device pixels"
    },
    "duration_ms": {
      "type": "integer",
      "description": "Duration of swipe in milliseconds (default: 300)"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "x1",
    "y1",
    "x2",
    "y2"
  ]
}

android_key

Send a key event to the Android device. Use keycode (e.g., '3' for HOME, '4' for BACK) or common name (e.g., 'HOME').

Parameters2

code	string	required	Key code: numeric (e.g., '3', '4') or common name (HOME, BACK, POWER, VOLUME_UP, VOLUME_DOWN, MENU, SEARCH, ENTER, DEL)
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "Key code: numeric (e.g., '3', '4') or common name (HOME, BACK, POWER, VOLUME_UP, VOLUME_DOWN, MENU, SEARCH, ENTER, DEL)"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "code"
  ]
}

android_type

Type text on the Android device keyboard.

Parameters2

text	string	required	Text to type
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "text": {
      "type": "string",
      "description": "Text to type",
      "maximum": 500
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "text"
  ]
}

android_launch_app

Launch an app on the Android device by package name. Example: 'com.whatsapp'. Returns success status and process ID if launched.

Parameters2

package	string	required	Android package name to launch (e.g., 'com.whatsapp')
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "description": "Android package name to launch (e.g., 'com.whatsapp')"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "package"
  ]
}

android_close_app

Close an app on the Android device (safe method: HOME key + am kill). Never uses am force-stop (corrupts PackageManager). Example: 'com.whatsapp'.

Parameters2

package	string	required	Android package name to close (e.g., 'com.whatsapp')
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "package": {
      "type": "string",
      "description": "Android package name to close (e.g., 'com.whatsapp')"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "package"
  ]
}

android_install_apk

Install an app on the Android device from an APK or split bundle (XAPK/APKS — how most large modern apps ship). Provide apk_url (an https link the device downloads itself — preferred, and the only workable option for real apps) or, for tiny payloads, as apk_base64. Max 300MB. Large apps can take several minutes; if this call times out the install keeps running on the device — verify with the app-list tool instead of re-installing. Use reinstall=true to uninstall then install (for signature changes).

Parameters5

apk_url	string	optional	https URL of the APK — the server downloads it (preferred; the only practical option for real-sized apps).
apk_base64	string	optional	APK as base64-encoded bytes. Only usable for tiny payloads (the whole blob is an LLM tool argument); prefer apk_url.
package	string	optional	Expected package name (for verification)
reinstall	boolean	optional	Uninstall first if package exists (for different signature). OMIT for a normal install (default false).
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "apk_url": {
      "type": "string",
      "description": "https URL of the APK — the server downloads it (preferred; the only practical option for real-sized apps)."
    },
    "apk_base64": {
      "type": "string",
      "description": "APK as base64-encoded bytes. Only usable for tiny payloads (the whole blob is an LLM tool argument); prefer apk_url."
    },
    "package": {
      "type": "string",
      "description": "Expected package name (for verification)"
    },
    "reinstall": {
      "type": "boolean",
      "description": "Uninstall first if package exists (for different signature). OMIT for a normal install (default false)."
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": []
}

android_list_apps

List installed apps on the Android device. By default returns third-party apps; use all=true for all apps.

Parameters2

all	boolean	optional	Include system apps. OMIT for third-party only (default false).
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "all": {
      "type": "boolean",
      "description": "Include system apps. OMIT for third-party only (default false)."
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": []
}

android_current_app

Get the currently focused app and activity on the Android device.

Parameters1

channel_account_id

integer

optional

Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": []
}

android_ui_dump

Get UI structure dump from the Android device. Uses dumpsys (uiautomator OOM-kills on this build). Returns window list and focused activity for frame-based clicking.

Parameters1

channel_account_id

integer

optional

Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": []
}

android_shell

Run an allowlisted shell command on the Android device. First element of cmd array must be allowlisted: input, pm, dumpsys, am, getprop, screencap, monkey, uiautomator, settings, wm, cmd, content, ls, cat, pidof, ps, echo, service.

Parameters2

cmd	string	required	Shell command to run (array form preferred, space-separated accepted). Example: 'getprop ro.build.version.release' or ['getprop', 'ro.build.version.release']
channel_account_id	integer	optional	Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous.

Raw schema

{
  "type": "object",
  "properties": {
    "cmd": {
      "type": "string",
      "description": "Shell command to run (array form preferred, space-separated accepted). Example: 'getprop ro.build.version.release' or ['getprop', 'ro.build.version.release']"
    },
    "channel_account_id": {
      "type": "integer",
      "description": "Android device channel_account ID. Omit when the workspace has a single Android device; REQUIRED when it has more than one (e.g. WhatsApp + LINE), else the call is rejected as ambiguous."
    }
  },
  "required": [
    "cmd"
  ]
}

browser_open

Open a URL in a remote browser. Saved login cookies are auto-attached when the URL domain matches a claimed browser identity. Pass identity_name to override auto-matching or force a specific identity.

Parameters2

url	string	required
identity_name	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "url": {
      "title": "Url",
      "type": "string"
    },
    "identity_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Identity Name"
    }
  },
  "required": [
    "url"
  ],
  "title": "tool_openArguments"
}

browser_snapshot

Return a YAML aria_snapshot of the page DOM. Each interactive node is tagged with `[ref=eN]` (e.g. `[ref=e7]`). Pass that exact token as the `ref` arg to browser.click / browser.fill / browser.type / browser.press_key. Do NOT pass the role name ('combobox', 'button') as ref — only the eN token. Truncated at 32KB.

Parameters1

page_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_snapshotArguments"
}

browser_click

Click an element. `ref` is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('button.submit'). Prefer the aria-ref token.

Parameters2

page_id	string	required
ref	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "ref"
  ],
  "title": "tool_clickArguments"
}

browser_fill

Fill an input or textarea with the given value. `ref` is either an aria-ref token from browser.snapshot ('e7') OR a CSS selector ('input[name=email]'). Prefer the aria-ref token — it's stable and matches exactly what snapshot returned.

Parameters3

page_id	string	required
ref	string	required
value	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    },
    "value": {
      "title": "Value",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "ref",
    "value"
  ],
  "title": "tool_fillArguments"
}

browser_wait_for

Wait for a selector to appear OR a navigation URL to match a glob pattern. Provide `ref` (selector) OR `url_pattern` (glob).

Parameters4

page_id	string	required
ref	any	optional
url_pattern	any	optional
timeout_ms	integer	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ref"
    },
    "url_pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url Pattern"
    },
    "timeout_ms": {
      "default": 10000,
      "title": "Timeout Ms",
      "type": "integer"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_wait_forArguments"
}

browser_attach_identity

Switch the page's identity by loading saved cookies + storage. Use only when switching identity mid-page; for first navigation, pass `identity_name` to browser.open instead.

Parameters2

page_id	string	required
identity_name	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "identity_name": {
      "title": "Identity Name",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "identity_name"
  ],
  "title": "tool_attach_identityArguments"
}

browser_close

Close a page opened by browser.open.

Parameters1

page_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_closeArguments"
}

browser_hover

Hover the mouse over an element (reveals tooltips + hover menus). `ref` is a CSS selector.

Parameters2

page_id	string	required
ref	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "ref"
  ],
  "title": "tool_hoverArguments"
}

browser_select_option

Pick option(s) in a native <select> dropdown. Pass `value` (matches the option's value attr) OR `label` (matches its visible text). Lists allowed for multi-select.

Parameters4

page_id	string	required
ref	string	required
value	any	optional
label	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    },
    "value": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Value"
    },
    "label": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "items": {},
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Label"
    }
  },
  "required": [
    "page_id",
    "ref"
  ],
  "title": "tool_select_optionArguments"
}

browser_press_key

Press a keyboard key (e.g., 'Enter', 'Tab', 'Escape', 'ArrowDown') or a single character. Optional `ref` focuses an element first — aria-ref token from browser.snapshot ('e7') or a CSS selector.

Parameters3

page_id	string	required
key	string	required
ref	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "key": {
      "title": "Key",
      "type": "string"
    },
    "ref": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ref"
    }
  },
  "required": [
    "page_id",
    "key"
  ],
  "title": "tool_press_keyArguments"
}

browser_navigate_back

Navigate back in the page's history (browser back button). Returns the new URL + title.

Parameters1

page_id

string

required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_navigate_backArguments"
}

browser_take_screenshot

Capture a PNG screenshot of the page or a specific element. Returns base64-encoded image bytes AND a file_id (persisted in DialogBrain files storage). Pass file_id straight to messages.send(attachment_file_ids=[file_id]) — do NOT call files.upload again. Use sparingly — favor browser.snapshot for structured DOM understanding.

Parameters4

page_id	string	required
ref	any	optional
full_page	boolean	optional
inline_bytes	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Ref"
    },
    "full_page": {
      "default": false,
      "title": "Full Page",
      "type": "boolean"
    },
    "inline_bytes": {
      "default": false,
      "title": "Inline Bytes",
      "type": "boolean"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_take_screenshotArguments"
}

browser_tabs

Manage tabs within the same BrowserContext as `page_id`. `action` ∈ {list, switch, close, new}. For list, returns all open tab metadata; for new, returns the new tab's page_id.

Parameters4

page_id	string	required
action	string	required
tab_id	any	optional
url	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "action": {
      "title": "Action",
      "type": "string"
    },
    "tab_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Tab Id"
    },
    "url": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url"
    }
  },
  "required": [
    "page_id",
    "action"
  ],
  "title": "tool_tabsArguments"
}

browser_evaluate

Run JavaScript in the page context and return the result. Use for state not in the a11y tree, captcha iframe inspection, DOM events. Expression is either a plain JS value ('document.title') or a zero-arg IIFE ('(() => { … })()'). Inline any runtime values into the expression itself. Result is JSON-serialized; non-serializable values become strings. 256KB cap on output.

Parameters2

page_id	string	required
expression	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "expression": {
      "title": "Expression",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "expression"
  ],
  "title": "tool_evaluateArguments"
}

browser_drag

Drag one element onto another. `source_ref` is the element to grab; `target_ref` is where to drop. Both are CSS selectors. Used for slider captchas, kanban, drag-and-drop uploads.

Parameters3

page_id	string	required
source_ref	string	required
target_ref	string	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "source_ref": {
      "title": "Source Ref",
      "type": "string"
    },
    "target_ref": {
      "title": "Target Ref",
      "type": "string"
    }
  },
  "required": [
    "page_id",
    "source_ref",
    "target_ref"
  ],
  "title": "tool_dragArguments"
}

browser_type

Type text into an element with per-keystroke delay (organic). Each character dispatches keydown/keypress/keyup, unlike browser.fill which replaces .value instantly. Use when the page listens to keystroke events or for typing-speed fingerprint checks. `ref` is an aria-ref token from browser.snapshot ('e7') or a CSS selector. `delay_ms` defaults to 50.

Parameters4

page_id	string	required
ref	string	required
text	string	required
delay_ms	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    },
    "text": {
      "title": "Text",
      "type": "string"
    },
    "delay_ms": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": 50,
      "title": "Delay Ms"
    }
  },
  "required": [
    "page_id",
    "ref",
    "text"
  ],
  "title": "tool_typeArguments"
}

browser_fill_form

Fill multiple form fields in one call. `fields` is a list of {ref, value} dicts. ref is a CSS selector; value is a string (text) or boolean (checkbox). Saves N round-trips vs calling browser.fill repeatedly.

Parameters2

page_id	string	required
fields	array	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "fields": {
      "items": {
        "additionalProperties": true,
        "type": "object"
      },
      "title": "Fields",
      "type": "array"
    }
  },
  "required": [
    "page_id",
    "fields"
  ],
  "title": "tool_fill_formArguments"
}

browser_resize

Resize the page viewport. Useful when a site serves different HTML based on viewport width (mobile vs desktop) or when an anti-bot scores risk by viewport dimensions.

Parameters3

page_id	string	required
width	integer	required
height	integer	required

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "width": {
      "title": "Width",
      "type": "integer"
    },
    "height": {
      "title": "Height",
      "type": "integer"
    }
  },
  "required": [
    "page_id",
    "width",
    "height"
  ],
  "title": "tool_resizeArguments"
}

browser_file_upload

Attach files to an <input type=file>. Pass either `local_paths` (absolute host paths) or `data` (list of {name, mime, base64} blobs written to /tmp). 25MB cap per file.

Parameters4

page_id	string	required
ref	string	required
local_paths	any	optional
data	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "ref": {
      "title": "Ref",
      "type": "string"
    },
    "local_paths": {
      "anyOf": [
        {
          "items": {
            "type": "string"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Local Paths"
    },
    "data": {
      "anyOf": [
        {
          "items": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": "array"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Data"
    }
  },
  "required": [
    "page_id",
    "ref"
  ],
  "title": "tool_file_uploadArguments"
}

browser_handle_dialog

Respond to a pending JS dialog (alert/confirm/prompt). Pass accept=true for OK or false for Cancel. For prompt() dialogs also pass prompt_text. Dialogs are queued at page-open time; returns {pending: false} if none is waiting.

Parameters3

page_id	string	required
accept	boolean	required
prompt_text	any	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "accept": {
      "title": "Accept",
      "type": "boolean"
    },
    "prompt_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Prompt Text"
    }
  },
  "required": [
    "page_id",
    "accept"
  ],
  "title": "tool_handle_dialogArguments"
}

browser_console_messages

Return console.log/warn/error events captured since the last drain. Filter by level ('log'|'info'|'warning'|'error'|'debug') and/or pattern (regex). Buffer caps at 500 entries; oldest are dropped first. Set clear=false to peek without draining.

Parameters4

page_id	string	required
level	any	optional
pattern	any	optional
clear	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "level": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Level"
    },
    "pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Pattern"
    },
    "clear": {
      "default": true,
      "title": "Clear",
      "type": "boolean"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_console_messagesArguments"
}

browser_network_requests

List HTTP requests the page made since open or last drain. Optional filters: method (GET/POST/...), url_pattern (regex), status_min (e.g. 400 for errors). Captures up to 200 most recent requests per page.

Parameters5

page_id	string	required
method	any	optional
url_pattern	any	optional
status_min	any	optional
clear	boolean	optional

Raw schema

{
  "type": "object",
  "properties": {
    "page_id": {
      "title": "Page Id",
      "type": "string"
    },
    "method": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Method"
    },
    "url_pattern": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Url Pattern"
    },
    "status_min": {
      "anyOf": [
        {
          "type": "integer"
        },
        {
          "type": "null"
        }
      ],
      "default": null,
      "title": "Status Min"
    },
    "clear": {
      "default": false,
      "title": "Clear",
      "type": "boolean"
    }
  },
  "required": [
    "page_id"
  ],
  "title": "tool_network_requestsArguments"
}

browser_attach_meet

Attach to THIS meet's bot browser and return a page_id for its live Google Meet tab. Then use the normal browser.* tools (browser.snapshot to see the page, browser.click to press a control, browser.take_screenshot, browser.evaluate, browser.console_messages, browser.network_requests) with that page_id to inspect why the bot isn't visibly joining (lobby/blocked/admitted) and to recover a stalled join. Call with no arguments from inside a meet.

Parameters

No parameters.

Raw schema

{
  "type": "object",
  "properties": {},
  "required": [],
  "title": "tool_attach_meetArguments"
}

README.md3 KBView on GitHub

DialogBrain MCP

Remote MCP server that connects your AI agent to a unified inbox spanning WhatsApp, Telegram, Instagram, Email, Livechat, and Voice calls — plus a workspace knowledge graph and AI agent orchestration.

MCP URL: https://api.dialogbrain.com/mcp
Transport: Streamable HTTP
Auth: OAuth 2.0 (Dynamic Client Registration)
Tools: 156 (read/write across all channels)
Product: https://dialogbrain.com
Developer docs: https://docs.dialogbrain.com

What you can do

Read messages across channels: messages.read_history, threads.list, threads.search
Send messages: messages.send, messages.forward, messages.delete
Manage contacts: contacts.find, contacts.discover, contacts.sync, contacts.profile
Query workspace knowledge: workspace.search, kg.find_entity, kg.get_relationships
Trigger AI agents: agents.ask, agents.simulate_inbound, agents.approve_draft
Files, calendar, calls, voice, browser automation, YouTube — see full tool list in Developer Docs.

Quick start

Claude Desktop / Claude.ai (web)

Add as a Custom Connector with URL https://api.dialogbrain.com/mcp. Sign in via OAuth when prompted.

ChatGPT (Apps)

In the ChatGPT Apps directory, search for "DialogBrain" (pending review). Or add as a Custom MCP Server with the same URL.

Cursor / generic MCP clients

json

{
  "mcpServers": {
    "dialogbrain": {
      "url": "https://api.dialogbrain.com/mcp",
      "transport": "streamable-http",
      "auth": "oauth2"
    }
  }
}

Authentication

OAuth 2.0 with Dynamic Client Registration (RFC 7591). Your MCP client registers automatically and is granted an access token scoped to one DialogBrain workspace. Revoke at any time from Settings → Developer in app.dialogbrain.com.

Tool annotations

Every tool exposes accurate MCP hint annotations:

readOnlyHint — true for read tools (threads.list, messages.read_history, kg.find_entity, …)
destructiveHint — true for delete tools (messages.delete, widgets.delete, …)
openWorldHint — true for tools that touch third-party APIs (messages.send, web.search, contacts.sync, …)
idempotentHint — derived from read-only/delete-by-id semantics

See server.json for the registry manifest and gemini-extension.json for Gemini CLI integration.

Privacy & support

Privacy policy: https://dialogbrain.com/privacy
Terms: https://dialogbrain.com/terms
Support: support@dialogbrain.com

License

MIT — see LICENSE.

Install

Tools (225)

contacts_findcontacts_discovercontacts_researchcontacts_synccontacts_profilecontacts_updatecontacts_add_channelcontacts_capture_lead

Remote endpoint

Streamable HTTP

Hosted server - connect over the network, no local install.

url

https://api.dialogbrain.com/mcp

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "dialogbrain": {
      "command": "npx",
      "args": [
        "-y",
        "mcp-remote",
        "https://api.dialogbrain.com/mcp"
      ]
    }
  }
}

Desktop config is stdio-only; this bridges via mcp-remote. Native remote: Settings > Connectors.