Base de connaissances GetMyBot

MCP: Programmatic Interface

Connect an AI assistant to GetMyBot to read settings and carry out tasks with your permission. MCP access, tools, and reference.

Sur cette page

MCP (Model Context Protocol) lets you connect an AI assistant to GetMyBot, for example to ask it to list your bots and find the reaction for /start. The assistant receives tools to read settings, create reactions, and inspect statistics. It performs operations through the API with your token's permissions.

To connect, supply the /mcp address and a personal token. If your client already uses the REST API, the same token works. In MCP, an operation is a tool, a document the assistant can read is a resource, and a prepared task for the assistant is a prompt. The sections below cover setup, permissions, and the available operations.

Address and authorization

MCP is available at the /mcp endpoint (Streamable HTTP transport, POST method). Authorization uses the same personal token as REST: the Authorization: Bearer <PERSONAL_TOKEN> header, where <PERSONAL_TOKEN> is the whole personal token (mbp_…). No separate tokens are needed: a single PAT works for both REST and MCP. A token belongs to one account: list_bots and the other tools see that account's bots only, and get_balance, get_transactions and connect_bot apply to it as well (see The token's account). Each tool requires the same scope as the corresponding REST endpoint; a token with scope * has full access. If a scope is missing, the call is rejected (fail-closed), just as with REST.

When the token is minted for somebody else's account, account-level tools also check the token holder's account rights: connect_bot needs bots.create, billing tools need billing.read or billing.write. The * scope does not grant account rights. Without them the tool returns the error permission denied: missing cabinet right (you are not a member of the account and reach it only through a shared bot) or permission denied: missing cabinet right: <right> (the membership lacks that specific right). Rights are granted by the account owner in the "Cabinet access" card; access management itself is not available via MCP.

Connecting to Claude Code / Cursor

The shortest path: open Account → Personal tokens and create a token. Right after creation the page shows a ready config and a claude mcp add command with the token already filled in; copy them as they are. The config is shown once, together with the token.

MCP needs a personal token (mbp_…). Project API tokens (mb_live_…) from the project settings only work with that project's REST API: with one of them /mcp answers 401 and tells you which token to use.

If you build the config by hand, use your cabinet's address (for example, https://getmybot.dev/mcp) and replace <PERSONAL_TOKEN> with the whole token, including its mbp_ prefix:

{
  "mcpServers": {
    "mybot": {
      "url": "https://getmybot.dev/mcp",
      "headers": {
        "Authorization": "Bearer <PERSONAL_TOKEN>"
      }
    }
  }
}

Claude Code: place this block in your project's .mcp.json or add the server with:

claude mcp add --transport http mybot https://getmybot.dev/mcp --header "Authorization: Bearer <PERSONAL_TOKEN>"

Cursor: add the same block to MCP settings (Settings → MCP → Add server). After connecting, the client will automatically receive the list of tools, resources, and prompts. If you get 401, check that the whole personal token follows Bearer , not a project API token.

Tools by domain

The tools below show their required scopes. Availability depends on the server version; use tools/list for the current list.

Bots (bots)

  • list_bots: bots:read
  • get_bot: bots:read
  • validate_bot_token: bots:write
  • connect_bot: bots:write
  • update_bot: bots:write
  • delete_bot: bots:write
  • sync_bot: bots:write
  • change_bot_token: bots:write
  • transfer_bot: bots:write
  • get_bot_settings: settings:read
  • update_bot_settings: settings:write (including test_user_ids, test users whose requests are not charged)
  • get_widget_email_readiness: settings:read. Pass bot_id to check the widget email reply configuration. senderConfigured indicates whether a sender address was found; transportStatus is configured, not_configured, or unknown. This reports configuration, not confirmed delivery.
  • get_widget_settings: settings:read
  • update_widget_settings: settings:write

In server versions that list them in tools/list, the project owner can call reveal_widget_identity_secret or rotate_widget_identity_secret with bots:write, bot_id and channel_id. Rotation additionally requires confirm_breaking_rotation: true; it invalidates the old key immediately, so update your backend. The secret is returned in plaintext to the MCP client and may be stored in its history; treat it like a password.

get_widget_settings returns the web widget's brand/launcher/panel/welcome/prechat/availability/ behavior settings, its origins, widgetKey and revision. update_widget_settings requires the expected_revision from that snapshot and refuses the save if the revision has moved since. update_bot_settings can also overwrite widget_experience wholesale, but it skips that validation, the avatar-ownership check, and the revision lock — for the widget, that is not the path to use.

Channels & WhatsApp templates (bots)

Multichannel support (Telegram + WhatsApp + VK + web widget) is available over MCP too. Channels and templates are gated by the shared scopes bots:read / bots:write: there is no separate channel scope.

  • list_channels: bots:read: list a bot's channels (platform tg/wa/vk/web, external_id, name, enabled, callback_url).
  • connect_channel: bots:write: connect a WhatsApp channel, a VK channel, or a web widget (platform + creds; for platform: "web" no creds are needed, only a required non-empty origins).
  • delete_channel: bots:write: disconnect a channel.
  • list_wa_templates: bots:read: the channel's WhatsApp template catalog (name, language, status, category, body).
  • sync_wa_templates: bots:write: re-sync the template catalog from Meta.
  • create_wa_template: bots:write: create a WhatsApp template and submit it to Meta for review.
  • update_wa_template: bots:write: edit a template (in APPROVED/REJECTED/PAUSED status).
  • delete_wa_template: bots:write: delete a template.

Telegram channels are connected via connect_bot, not connect_channel: the latter handles wa, vk, and web. Template categories: MARKETING / UTILITY / AUTHENTICATION. create_wa_template immediately submits the draft to Meta for review; the status changes asynchronously: read it back via list_wa_templates (refreshing the catalog with sync_wa_templates if needed).

connect_channel's response for platform: "web" differs from the other platforms: {"widget_key": "…"}, not {"id": …}. The call is idempotent: connecting the same bot again returns the same key rather than creating a second widget. Configuring the widget's look and behavior is the separate get_widget_settings/update_widget_settings pair above, not connect_channel.

Uploading a template's media header (image/video/document) over MCP is not supported yet: use the web UI or REST POST /api/bots/{botID}/channels/{channelID}/templates/media.

Reactions (reactions)

  • list_reactions: reactions:read
  • get_reaction: reactions:read
  • create_reaction: reactions:write
  • update_reaction: reactions:write
  • delete_reaction: reactions:write
  • import_reactions: reactions:write
  • test_formula: reactions:write: test an advanced formula against sample text. Fields: bot_id, formula, sample (in REST the same field is called sample_text). The context is empty: ctx and parameters are not substituted, the sample text is available as {text} / {answer}.
  • reorder_reaction: reactions:write
  • get_reaction_links: reactions:read
  • list_reaction_folders: reactions:read
  • create_reaction_folder: reactions:write
  • update_reaction_folder: reactions:write
  • delete_reaction_folder: reactions:write
  • add_reaction_to_folder: reactions:write
  • remove_reaction_from_folder: reactions:write
  • add_reactions_to_folder: reactions:write

Import via import_reactions creates reactions but skips media: there is no premium check or Telegram file receiver in the MCP context. If the SamBot bundle contains images, videos, or documents, use the full-featured REST import (POST /api/bots/{botID}/reactions/import): it transfers media as well.

Broadcasts (broadcasts)

  • start_broadcast: broadcasts:write (optional paid, optional segment by labels)
  • get_broadcast: broadcasts:write: for broadcasts started from a reaction via start_broadcast, the report includes blocked – block events attributed within 24 hours after delivery.
  • pause_broadcast: broadcasts:write
  • resume_broadcast: broadcasts:write
  • cancel_broadcast: broadcasts:write

Email sending settings

Sending availability. Campaigns and automated emails require configured delivery workers in your region. Connecting custom SMTP alone does not guarantee sending availability. Custom SMTP can also be used for unread widget reply copies when the other requirements are met. Contact support to check availability.

A project can select GetMyBot or its own SMTP server; campaign and automated email availability depends on the respective delivery workers. Support mailboxes and inbound email are configured separately. See Email from your own domain.

  • get_email_smtp (settings:read): pass bot_id. The response gives mode and, for custom SMTP, settings and version; it never returns the password.

  • put_email_smtp (settings:write): pass bot_id, host, port, security (starttls or tls), username, envelope_from and password. Omit expected_version on creation; for updates, supply the version from get_email_smtp. You may omit the password only if host, port, security and username are unchanged. The server checks the connection and authentication without sending mail.

  • delete_email_smtp (settings:write): pass bot_id and the current expected_version to select GetMyBot mode. Sending in this mode requires a platform sender configured in the region. Switching modes resets domain verification.

get_email_smtp also returns delivery_workers with journey and newsletter statuses: configured, not_configured or unknown. These describe the responding server configuration, not queue health or email delivery. The separate delivery_workers.newsletter_gate field reports the shared gate for bulk email campaigns: open, paused, or unknown when its status cannot be checked. While paused, new jobs and recipients are not claimed, but sends already started may finish. This pause does not stop other email sending.

SMTP changes require the project owner or both reactions and support administration rights, the email feature and applicable project security checks. If the version is stale, read the latest settings before retrying.

Where available in tools/list, delete_email_domain takes bot_id, domain_id, confirm: true; delete_email_inbound_route takes bot_id, route_id, confirm: true; and delete_email_mailbox takes bot_id, expected_version, confirm: true. They require settings:write; mailbox deletion also requires support administration. Get its version from get_email_mailbox. A domain in use by campaigns may not be deleted.

Content validation

validate_content_for_channel (content:read) checks a saved content version for a selected channel without sending it. Pass bot_id, document_id, version, the current expected_revision, and platform. To validate for a recipient, pass both recipient_id and channel_id; add identity_id if needed. Use list_content_test_recipients to find available verified recipients.

The result contains snapshot, errors, and warnings. If the revision no longer matches, retrieve the current content and retry. Project and builder permissions and applicable security checks are required. Check tools/list for tool availability.

Pop-ups

list_popups and get_popup require popups:read; create_popup_draft, update_popup_draft, set_popup_enabled and delete_popup require popups:write. Availability of these operations and A/B variants depends on the deployed server version; check tools/list after upgrading.

To create a new disabled A/B draft, pass ab_test: true and two to five variants to create_popup_draft. Before first activation, use update_popup_draft to change variants; when passing variants, supply the complete desired list and retain existing variant IDs. Enable the pop-up with set_popup_enabled and enabled: true: its variants are fixed after the activation checks succeed. Previously fixed variants remain immutable even when the pop-up is disabled. To delete a pop-up, first read updated_at with get_popup, then pass it as expected_updated_at with confirm: true to delete_popup. An enabled pop-up stops showing immediately; historical events and the experiment record are retained.

Automated journeys

archive_campaign archives a journey that is not running, while delete_campaign permanently removes it and its history. clone_campaign_version copies a selected version into a new draft of the same journey, replacing the current draft. All three require confirm: true; save any edits you need before cloning.

Manage saved audiences with list_broadcast_audiences, create_broadcast_audience and delete_broadcast_audience (deletion requires confirm: true). list_reaction_broadcast_recipients pages through recipients, and list_reaction_broadcasts lists the reaction’s broadcast history. Viewing recipients requires subscribers:read and dialog access.

Audience preparation tools require the segments:read scope:

  • list_audience_segments: bot_id, optional limit (1–100, default 50) and cursor. Returns segments and next_cursor for the next page.
  • get_audience_segment: bot_id and segment_id. Returns the definition, status and computed member count.
  • preview_audience_segment: bot_id, definition with version and a root tree, and limit from 1 to 20. Returns estimated_count, an exact flag and a sample of visitor IDs and names with redacted match reasons. The count can be inexact.

Segment changes require the segments:write scope:

  • create_segment: bot_id, name and definition_json, a string containing the complete version 2 JSON definition. Every call creates a segment; check the existing list before retrying.
  • update_segment: bot_id, segment_id, expected_revision and at least one of name or definition_json. A new definition replaces the entire previous definition. If the revision is stale, read the segment again and agree on the change before retrying.
  • recompute_segment: bot_id and segment_id. A pending status means recalculation is queued, not complete.

These calls change data and do not accept a confirm field: use them only at the user's explicit request. Changing the definition or recomputing can cause people to enter the segment and trigger an active automated campaign configured for that event, including sending emails. Check associated campaigns before calling.

The token owner needs the bot analytics right, segment availability on the plan and any required 2FA. A returned segment_id can be used when configuring an email campaign audience: set audience_definition to kind: "segment" with that segment_id. These calls only read or estimate the audience; they do not save a segment, start a broadcast or confirm delivery.

For content-based broadcasts, MCP provides create_content_broadcast, update_content_broadcast_draft, preflight_content_broadcast, list_content_broadcast_recipients and archive_content_broadcast. Updates and archiving use expected_revision; listing recipients also requires subscribers:read and access to dialogs. Use schedule_content_broadcast to schedule and test_send_content_broadcast for a test send; both require expected_revision and confirm: true. Queueing does not confirm delivery.

list_campaign_templates lists available templates. instantiate_campaign_template accepts bot_id, template_id and an optional name, creating a new draft without starting or sending. Content tools include create_content_template, delete_content_template, clone_content and archive_content; deletion and archiving require confirm: true.

Tool availability depends on the server version. Check tools/list before use. Reading requires campaigns:read; creation, editing and status changes require campaigns:write; publishing and retrying require campaigns:publish. Project rights, plan and security requirements also apply.

  1. create_campaign creates a draft from bot_id and name. Read the current revision with get_campaign; use list_campaign_versions and get_campaign_version for versions and their contents.
  2. update_campaign_draft takes bot_id, campaign_id, expected_revision and draft_json. The latter is a string containing the complete draft JSON object: trigger, audience, settings, experiment_id, primary_goal, graph. Saving replaces the whole draft and clears omitted fields. On a revision conflict, reload the draft and reapply your edits.
  3. Use get_campaign_preflight to validate without publishing. publish_campaign_draft requires the current expected_revision and confirm: true. Later draft edits do not change the published version.
  4. set_campaign_status accepts running, paused or stopped. Starting with running requires confirm: true; the first start of an unpublished journey publishes its draft. For an email journey, this also requires the campaigns:publish scope and publication right. Pausing stops new entrants while existing journeys continue; stopped freezes journeys.
  5. retry_campaign_journey retries a failed step for subscriber_id and run_no. Pass bot_id, campaign_id and confirm: true; only failed journeys can be retried.

list_campaign_failures (campaigns:read) returns recent failed journeys. Pass bot_id, campaign_id, and optional limit from 1 to 500 (default 100). There is no cursor; results may be incomplete at the limit. Raw error text is omitted: use error_code and get_campaign_journey_trace.

Labels (labels)

  • list_labels: labels:read
  • create_label: labels:write
  • delete_label: labels:write
  • set_label_favorite: labels:write
  • assign_user_label: labels:write: assign a label to a subscriber (tg_user_id) using its canonical UUID label_id, optionally for ttl_days from 0 to 106751 days. 0 makes it permanent; when a temporary label expires, it is removed and triggers the "Label expired" event.
  • remove_user_label: labels:write: remove a subscriber label by its canonical UUID label_id

Collections and records (collections)

  • list_collections: collections:read
  • create_collection: collections:write
  • update_collection: collections:write
  • delete_collection: collections:write
  • list_records: collections:read
  • search_records, related_records: collections:read: search and related rows with result-completeness metadata
  • create_record: collections:write
  • update_record: collections:write
  • delete_record: collections:write
  • update_record_if: collections:write: atomically update one record when a nonempty set of expected fields matches; returns updated, conflict, or not_found

Data processing and branches

  • get_workflow_guide: reactions:read: current schemas for new actions, limits, results, and composition examples.
  • transform_list: reactions:read: filtering, stable sorting, deduplication, a row window, and field projection.
  • aggregate_list: reactions:read: grouping and named aggregates over supplied rows.
  • evaluate_conditions: reactions:read: evaluate ordered conditions and identify the selected branch without running it.

These checks do not need a collection: pass ordinary JSON as data. They do not run reactions or change bot state. By contrast, update_record_if is a real write and appears in the change log. Specify bot_id and the required region; account rights are checked too.

Reaction actions use source as a context key, while the list-checking tools receive the data itself. Their aggregates describe loaded_rows, not an entire external database or collection. See parameters, results, and examples.

Scenarios (flows)

  • list_flows: flows:read
  • get_flow: flows:read
  • create_flow: flows:write
  • update_flow: flows:write
  • delete_flow: flows:write

Integrations, connections, credentials (integrations)

  • list_integrations: integrations:read
  • get_integration_sheets: integrations:read
  • get_integration_status: integrations:read
  • create_integration: integrations:write
  • update_integration: integrations:write
  • delete_integration: integrations:write
  • rotate_integration_token: integrations:write
  • list_connections: integrations:read
  • create_connection: integrations:write
  • test_connection: integrations:write
  • update_connection: integrations:write
  • delete_connection: integrations:write
  • list_credentials: integrations:read
  • create_credential: integrations:write
  • update_credential: integrations:write
  • delete_credential: integrations:write

CRM (crm)

CRM tools include reads and the separate Ozma chat binding operations below. Connecting, synchronization, ordinary job retries and general conflict resolution remain in REST. Credentials are not returned.

  • list_crm_connections: crm:read: a bot's connections with provider, status and capabilities.
  • get_crm_connection: crm:read: one connection's safe summary.
  • get_crm_mapping: crm:read: the connection's current mapping revision.
  • list_crm_operations: crm:read: recent sync operations, newest first, optionally scoped to one connection.
  • get_crm_operation: crm:read: one operation with its jobs; never a job's raw request payload.
  • list_crm_conflicts: crm:read: jobs waiting for manual conflict resolution.

See CRM integrations for what a connection, mapping and operation mean.

For the configured Gogol Ozma integration, the project owner can manage a chat contact binding. All calls require bot_id and subscriber_id and are owner-only:

  • get_ozma_chat_binding: crm:read and subscribers:read; returns the binding, revision, candidates, truncated and a short-lived evidence_token.
  • confirm_ozma_chat_binding: crm:write, crm:read, subscribers:read and subscribers:write; also pass the selected contact_id, expected_revision and unchanged evidence_token from the latest read. Call only after explicit owner confirmation and checking the contact. A truncated list cannot be confirmed; read again if the evidence is stale.
  • revoke_ozma_chat_binding: crm:write and subscribers:write; pass expected_revision from the latest read to revoke the binding.

Search uses the profile email, or its phone if email is absent and OZMA_CHAT_PHONE_BINDING_ENABLED is enabled on the server (off by default). A phone match does not prove identity or merge histories. Confirmation queues the transfer, not proof of delivery. Availability depends on the regional version and configuration.

For widget lead failures before CRM jobs are queued, use list_widget_crm_failures (crm:read, bot_id) to read up to 100 recent entries without contact values, and retry_widget_crm_failure (crm:write, bot_id, failure_id) after fixing the settings. Retry checks current consent and configuration; widget_crm_configuration_invalid and widget_consent_required indicate settings need correction or renewed consent. A status: "queued" response with operation means queued, not delivered to the CRM.

When a failed widget contact job finds a matching Bitrix24, amoCRM or RetailCRM contact, call get_widget_crm_contact_candidate with bot_id and job_id (crm:read and subscribers:read scopes, plus CRM and dialog rights). Compare the record with the visitor and obtain explicit owner confirmation. Then call confirm_widget_crm_contact_candidate with the same bot_id and job_id, the returned remote_id and confirm: true; this requires crm:write, crm:read, subscribers:read and subscribers:write, plus CRM and dialog rights. The contact and current consent are checked again. A successful status: "queued" means the operation is queued, not delivered to the CRM.

To configure widget leads, use an active Bitrix24, amoCRM or RetailCRM connection. list_widget_crm_pipelines (crm:read, bot_id, connection_id) returns pipelines with their statuses and current_revision. To enable or update sending, call set_widget_crm_trigger (crm:write) with the same IDs, expected_revision from a current read, enabled: true, and the selected pipeline_id and status_id. To disable it, send enabled: false and expected_revision; pipeline and stage are optional. The response contains revision and enabled. If the revision changed, read the settings again before retrying. For RetailCRM, pipeline_id is the site code and status_id is the order status. Phone search may be incomplete: review and confirm a match, or check the contact in CRM and search again if none is found. Complete duplicate prevention, including records created outside MyBot, is not guaranteed.

amoCRM phone search may be incomplete. If no contact is found, automatic creation stops: create or correct the contact in amoCRM, search again, and explicitly confirm the match. Matching reduces duplicates but cannot prevent them after external changes or indexing delays.

The lead pipeline must match the pipeline already selected in the CRM mapping: this call does not switch an existing mapping to a different pipeline. Other mappings are preserved. Enabling this workflow for other CRMs is not yet available.

Browser push and customer SDK (web_push, customer_sdk)

MCP can enable Web Push, update its configuration and send test notifications. Identity secret rotation and device revocation use REST. The tools never return a VAPID private key, push endpoint, identity secret or device push token.

  • enable_web_push: web_push:write. Pass bot_id, subject and navigation_origins, optionally quiet_hours. Initial enablement creates VAPID keys; subsequent calls preserve existing keys. Web Push management and integration secrets permissions and applicable 2FA checks are required; key creation is rate limited. The private key is not returned.
  • test_web_push: web_push:write. Pass bot_id, subscription_id, content_document_id, content_version, the notification payload and the required confirm: true. Web Push must be enabled, the subscriber must have consented, and the push document version must be published. The web_push.write permission and applicable 2FA checks are required. The response contains message_id and status: "queued"; queued does not confirm delivery. Each repeated call creates a new message.

To prepare a published push document, use create_push_content_draft (bot_id, name, optional blocks and settings), then update_push_content_draft (bot_id, document_id, version, expected_revision optional name and the complete blocks and settings) and publish_push_content (bot_id, document_id, version, expected_revision). Retrieve the current version and revision with get_content; use list_content with kind: "push" to list push documents. Changes require the content:write scope, the reactions permission for a member and applicable 2FA checks. Creating, editing and publishing do not send a notification. Updates replace blocks and settings in full.

  • update_web_push_config: web_push:write. Pass bot_id and the fields to change: subject, navigation_origins, quiet_hours and/or enabled. Only supplied fields change; VAPID keys are preserved. An existing configuration, Web Push management permission and applicable security checks are required.
  • get_web_push_config: web_push:read: the redacted Web Push configuration for a bot.
  • get_web_push_status: web_push:read: whether browser push is enabled.
  • get_web_push_report: web_push:read: subscription and receipt counters.
  • list_web_push_subscriptions: web_push:read: up to 100 recent bot subscriptions. Pass bot_id; the response can include a subscriber ID, browser details and consent status, but no push endpoint or keys.
  • get_customer_sdk_status: customer_sdk:read: whether the mobile SDK project is enabled.
  • get_customer_sdk_report: customer_sdk:read: installation and push-token counters.

Reading Web Push data requires the web_push.read bot permission. Reading customer SDK data requires customer_sdk.read.

See Browser push and Customer SDK for what these numbers mean.

Rotate VAPID keys

Both calls to rotate_web_push_keys require an existing Web Push configuration, the web_push:write scope and the web_push.write bot permission. If the project requires 2FA, the token holder must enable it.

  1. Pass bot_id and omit confirm or set confirm: false. The response contains the number of active subscriptions in active_subscriptions and confirmation_required: true. The preview leaves keys and subscriptions intact and does not use the rotation budget.
  2. Pass the same bot_id with confirm: true if you are ready for all active subscriptions to expire and for affected browsers to subscribe again. Confirmation also requires the integrations.secrets bot permission and a personal access token (PAT) issued in the project's region. It uses the existing per-bot key mutation rate limit shared with REST. The response contains config without the private key and the actual number of expired subscriptions in expired_subscriptions.

The tool becomes available when the backend version that includes it is deployed in the project's region. Check tools/list for rotate_web_push_keys.

Media (media)

  • list_media_assets: media:write. Pass bot_id and optional limit (1–100, default 50) and cursor from the previous response. Returns library uploads, in_use, and next_cursor; chat and email attachments are excluded.
  • delete_media_asset (media:write). Pass bot_id, asset_id and confirm: true. Requires the Reactions permission (reactions) and the image_storage plan feature. Assets in use, including in the knowledge base, are rejected with media_in_use. On success the library entry is removed immediately (deleted: true). Background cleanup is queued (blob_cleanup_queued: true) and deletes the stored file only if no references remain.
  • upload_media: media:write
  • get_media: media:write
  • download_media: media:write: download a media asset's bytes as base64 ({mime, size_bytes, data_base64}), e.g. to re-upload it to another bot with upload_media. Refuses assets larger than 2 MB.

On server versions that support launcher_icon in the upload_media schema from tools/list, pass bot_id, kind: "launcher_icon", and the Base64-encoded image bytes in data_base64. The server identifies PNG, JPEG, and WebP by file contents. The file can be up to 64 KiB (65,536 bytes). Uploading requires media:write, the reactions bot right for project members, and image_storage on the bot owner’s plan.

To apply the icon, save the returned id in experience.launcher.customIconMediaId using update_widget_settings. Read the current experience and revision with get_widget_settings, keep the other experience settings, and pass the revision as expected_revision. See custom launcher icon settings.

Templates (templates)

  • list_templates: templates:read
  • delete_template: templates:write
  • create_template_from_bot: templates:write
  • apply_template: templates:write

Subscribers, chats, dialogs (subscribers)

  • list_subscribers: subscribers:read (offset/limit pagination, search, label and is_blocked=true|false filters; each item carries is_blocked and blocked_at when the subscriber blocked the bot)
  • list_chats: subscribers:read
  • list_dialogs: subscribers:read: operator-inbox threads: subscriber, platform, last-message preview, last_seen; keyset pagination via cursor/next_cursor.
  • read_dialog: subscribers:read: dialog messages, older pages via before_id; transcribed audio/video messages carry transcript_status/transcript/transcript_error in meta.
  • send_dialog_message: subscribers:write: operator text send to a subscriber: WhatsApp 24h window and channel routing enforced, delivery metered to the token owner.
  • send_dialog_attachment: subscribers:write: send a file to a Telegram, WhatsApp or VK dialog. Provide bot_id, numeric dialog user_id as a string, file_name, data_base64 and confirm: true. Optional fields are channel_id, content_type, caption and kind. Files are limited to 16 MiB. Sending is synchronous and has no idempotency key: after a timeout, check the dialog before retrying because the delivery outcome may be unknown. WhatsApp reply-window restrictions apply. The tool uses the channel saved for the dialog; historical conversations on another channel are not supported by this call.
  • edit_dialog_message: subscribers:write: Replaces the text or a supported media caption with a non-empty text value.
  • delete_dialog_message: subscribers:write: Deletes the message. Pass confirm=true to confirm deletion.
  • send_dialog_reaction: subscribers:write: send one of the bot's ready-made reactions to a subscriber (like the operator console's "send reaction" button). REST equivalents with the same scope: POST /api/bots/{botID}/users/{userID}/dialog/messages (Idempotency-Key required) and POST /api/bots/{botID}/users/{userID}/dialog/reactions with body {"reaction_id": "…"}.
  • transcribe_dialog_message: subscribers:write: start or fetch a speech-to-text transcription of an audio/video message. Idempotent: the first call enqueues a background job ({"status":"pending"}), poll by calling again until {"status":"done","text":…}; a failed transcription is restarted automatically. Requires the bot's "Speech recognition" integration.

For both calls, pass bot_id, tg_user_id, and the message's id from read_dialog as message_id. Pass channel_id and subscriber_id as needed to identify the dialog.

The token holder needs the bot’s dialog permission (dialogs) and must have 2FA enabled if the bot requires it. Only delivered outgoing messages in Telegram, VK, and the web widget are eligible. The available action depends on the channel, message type, and age.

These tools will appear in tools/list after the backend update is deployed.

Reply to a support dialog

send_support_message queues a text reply for the canonical subscriber's latest conversation. Pass bot_id, text, the canonical subscriber_id, and the current revision from list_support_inbox as expected_dialog_revision. Include confirm: true and an idempotency_key as a lowercase UUID. Reuse the key only for retries of the same send. It prevents duplicates while the outbox row is retained.

The tool requires the support:write scope, the Dialogs permission (dialogs), and 2FA if the project requires it. For email, the server verifies that the recipient and email thread belong to the dialog. For channels that support quotes, you can pass reply_to_message_id with the message ID to quote. The response returns status: "queued" and the new revision. Delivery is confirmed separately.

To return a handed-off conversation to its active AI agent, call resume_support_ai_conversation with bot_id, subscriber_id and explicit confirm: true; support:write and dialog access rights are required. The result contains conversation and resumed; resumed: false means repeating the call did not change an already resumed conversation. An incompatible state returns an error.

Support dialog attachments

To download a file sent by a website visitor through the widget, call download_support_widget_attachment with the same bot_id and subscriber_id you passed to read_support_dialog. Pass the numeric id of the message from the response as message_id.

The token needs the support:read scope and its holder needs the bot’s dialog permission (dialogs). The original file can be up to 20 MiB. The response includes file_name, mime_type, size_bytes, and the Base64-encoded file in data_base64.

For an email attachment, call download_support_email_attachment with bot_id, subscriber_id, message_id, and attachment_id. Use the id of the corresponding entry in the message’s attachments array as attachment_id.

Tool availability depends on the deployed server version. Check tools/list.

Support dialog status and assignment

The dialog status and private note tools are available only on server versions where they are deployed, and they may appear at different times. Check each one in tools/list.

  • get_support_dialog_meta · support:read · bot_id, subscriber_id. Returns the dialog state: bot_id, subscriber_id, status, revision, assignee_id, group_id, snoozed_until, last_activity_at, first_inbound_at, first_response_at, last_inbound_at, last_response_at, closed_at, reopened_at, reopen_count, and tags (tag IDs). Empty fields are omitted. A historical subscriber ID left by a merge resolves to the current subscriber, and the response returns the canonical subscriber_id.
  • update_support_dialog_meta · support:write · bot_id, subscriber_id, expected_revision, and at least one change: status, snoozed_until, assignee_id, group_id, or assign_to_self. Omitted fields stay unchanged. The response contains the updated state with the new revision.

Update rules:

  • status accepts open, pending, closed, or snoozed. open reopens a closed dialog. A closed dialog can move only to open or snoozed. You cannot pass the current status without any other change.
  • To enter snoozed, set snoozed_until to a future RFC 3339 timestamp. snoozed_until is accepted only if the dialog ends up in the snoozed status.
  • assignee_id takes the ID of a member of this bot. An empty string unassigns the dialog. assign_to_self: true assigns the dialog to the token holder and cannot be combined with assignee_id.
  • group_id takes the ID of an operator group on this bot. An empty string clears the group.

For writes, pass bot_id and subscriber_id as canonical UUIDs: lowercase with hyphens. Use the current subscriber_id from get_support_dialog_meta or list_support_inbox. If the subscriber has since been merged into another one, a revision read for its former ID is not valid, and the server returns a revision conflict. Set expected_revision to the current revision from get_support_dialog_meta or list_support_inbox. On a dialog revision conflict error, read the dialog again and decide whether the change is still needed before retrying it.

Reads require the support:read scope and writes require support:write. The token holder needs the bot’s Dialogs permission (dialogs), and 2FA must be enabled on their account if the project requires it.

Private notes in support dialogs

Private notes are internal operator comments on a dialog. They are never sent to the subscriber.

  • list_support_private_notes · support:read · bot_id, subscriber_id. Returns up to 100 active notes, newest first. The response has a notes array. Each note has id, bot_id, subscriber_id, author_id, body, created_at, and edited_at if it was edited.
  • create_support_private_note · support:write · bot_id, subscriber_id, body, expected_revision. Adds a note on behalf of the token holder and returns it.
  • update_support_private_note · support:write · bot_id, subscriber_id, note_id, body, expected_revision. Replaces the note text and sets edited_at.
  • delete_support_private_note · support:write · bot_id, subscriber_id, note_id, expected_revision. Soft-deletes the note: it is marked as deleted and no longer appears in the list. Response: {"status": "deleted"}.

body cannot be empty or whitespace-only and may be up to 10,000 bytes. Pass every ID as a canonical lowercase UUID. A historical subscriber_id left by a subscriber merge resolves to the current subscriber, so the response may contain a different subscriber_id. For an unknown dialog or note, the server returns a not-found error.

The token holder becomes the note’s author, and their ID is returned in author_id. The bot owner and its members can create notes. Only the author can edit or delete a note. Even the bot owner cannot change someone else’s note.

Each note creation, edit, or deletion increments the dialog revision. Set expected_revision to the current revision from get_support_dialog_meta or list_support_inbox. The note response does not include the new revision, so read the dialog again before the next write. On a dialog revision conflict error, reread the dialog and check whether the change still applies.

Permissions match the dialog status tools: support:read for reads, support:write for writes, the Dialogs permission (dialogs), and 2FA if the project requires it.

Support dialog tags

Tags are a bot-wide vocabulary of labels, such as “billing” or “refund”, that operators use to classify dialogs. These tools appear only after the matching backend version is deployed. Check for each of them in tools/list.

  • list_support_dialog_tags · support:read · bot_id. Returns a tags array: the bot’s tag vocabulary sorted by name. Each tag has id and name, plus color if a color is set.
  • create_support_dialog_tag · support:write · bot_id, name, and optional color. Leading and trailing spaces in name are trimmed; an empty name or one longer than 100 characters is rejected. color is a display string of up to 32 characters, such as #ff8800; the server does not check its format. Returns the tag with id, name, and color.
  • delete_support_dialog_tag · support:write · bot_id, tag_id. Deletes the tag from the vocabulary and removes it from every dialog. Response: {"status": "deleted"}.
  • add_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Adds a vocabulary tag to the dialog.
  • remove_support_dialog_tag · support:write · bot_id, subscriber_id, tag_id, expected_revision. Removes the tag from the dialog.

add_support_dialog_tag and remove_support_dialog_tag return the dialog state in the get_support_dialog_meta format with the current tags list. If the tag is already added or already removed, nothing changes and the current state is returned. If the subscriber has no stored dialog yet, add_support_dialog_tag creates an open dialog at revision 1. Operators see an actual tag change in the inbox right away.

Set expected_revision to the current revision from get_support_dialog_meta or list_support_inbox. The value must be at least 1; otherwise the server returns expected_revision is required. If the dialog revision has changed, the tag is left as it was and the server returns dialog revision conflict: read the dialog again with get_support_dialog_meta, take the canonical subscriber_id and revision it returns, and decide whether the change is still needed. Tags themselves do not change the revision: adding, removing, or deleting a tag does not increment revision, is not recorded in the dialog history, and does not move the last activity time. The response therefore carries the same revision, and you can pass it to the next call. The revision check protects against other dialog changes made after your read, such as status, assignment, or notes, but not against another operator editing tags at the same time.

Pass every ID as a canonical UUID: lowercase with hyphens. Otherwise the server returns an error such as tag_id must be a canonical UUID. Take tag_id from list_support_dialog_tags and the current subscriber_id from get_support_dialog_meta or list_support_inbox. Unlike the read tools, tag writes do not resolve a historical ID of a merged subscriber to the current one; they reject it with dialog revision conflict. When subscribers are merged, their tags move to the surviving dialog.

The tag and the subscriber must belong to the bot in bot_id. For a foreign or inaccessible bot the server returns bot not found, for another bot’s tag dialog tag not found, and for another bot’s subscriber subscriber not found; other bots’ data stays unchanged. The vocabulary and dialog tags can be changed only with a token issued for the bot owner’s cabinet. A token for another cabinet gets permission denied on writes.

list_support_dialog_tags requires the support:read scope; the other tools require support:write. With a read-only scope, writes return insufficient scope. The token holder needs the bot’s Dialogs permission (dialogs); without it the server returns missing bot right. If the project requires 2FA, it must be enabled on the token holder’s account; otherwise the server returns two_factor_enrollment_required. On writes, the token, scope, permission, and 2FA are checked again in the same transaction. If the token was revoked or permissions changed, nothing is written and the server returns permission denied or a not-found error. Every write is recorded in the action log and marked as MCP.

These tools have no idempotency key, so keep the retry behavior in mind:

  • You can repeat add_support_dialog_tag and remove_support_dialog_tag with the same expected_revision: tags do not change the revision, and a repeat creates no duplicate and returns the current state. If the revision changed for another reason between attempts, the repeat returns dialog revision conflict. Read the dialog again with get_support_dialog_meta, check tags, and use the canonical subscriber_id and revision it returns.
  • Repeating create_support_dialog_tag with the same name does not create a copy and returns the tag with its existing id. Without the color field, the existing color is kept, so a retry is safe. An explicit color replaces the color, and an empty string "" clears it.
  • Repeating delete_support_dialog_tag returns dialog tag not found. Deletion cannot be undone: a tag recreated with the same name gets a new id and has to be added to dialogs again.

Operator quick replies

Quick replies are templates an operator inserts into a reply by typing / followed by a shortcut. These tools are available only on server versions where they have been deployed. Check for them in tools/list.

  • list_quick_replies · support:read · bot_id. Returns an items array: the bot’s shared templates plus the token holder’s personal ones. The most used come first; ties are sorted by shortcut alphabetically. Each template has id, shortcut, title, blocks, and usage_count; a personal one also has owner_id.
  • create_quick_reply · support:write · bot_id, shortcut, and optional title, blocks, and personal. Pass the shortcut in shortcut without the /; an empty value is rejected. blocks are message blocks in the reaction builder format, with text, buttons, media, and the same substitutions. The default is an empty list. personal: true creates a personal template; without it, the template is shared with the team. Returns the saved template.
  • delete_quick_reply · support:write · bot_id, quick_reply_id. Deletes a shared template or one of the token holder’s personal templates. Response: {"status": "deleted"}.
  • use_quick_reply · support:write · bot_id, quick_reply_id. Records that an operator inserted the template: it increments usage_count by 1 and moves the template up the list. No message is sent to the subscriber. Response: {"status": "used"}.

Shared templates are visible to everyone with the bot’s Dialogs permission, and any of them can delete a shared template. A personal template belongs to the token holder who created it: you cannot create a personal template on behalf of another member. Other members’ personal templates never appear in the list, not even for the bot owner. For them, as for an unknown or malformed ID, delete_quick_reply and use_quick_reply return quick reply not found, and the counter does not change.

These tools have no idempotency key, so keep the retry behavior in mind:

  • Repeating create_quick_reply with personal: true and the same shortcut does not create a copy. It replaces the title and blocks of the existing personal template and keeps its id and usage_count.
  • Repeating create_quick_reply for a shared template creates another template with the same shortcut and a new id. If the create response was lost, check list_quick_replies first.
  • Every use_quick_reply call increments the counter by 1 again. Call it once per template insertion.
  • Repeating delete_quick_reply for a template that is already deleted returns quick reply not found.

list_quick_replies requires the support:read scope; the other tools require support:write. The token holder needs the bot’s Dialogs permission (dialogs), and 2FA must be enabled on their account if the project requires it. Without the permission the server returns missing bot right; without 2FA it returns two_factor_enrollment_required. On writes, the token, the support:write scope, the permission, and 2FA are checked again in the same transaction. If the token was revoked or permissions changed, nothing is written and the server returns permission denied or a not-found error. Templates of an archived bot cannot be changed.

Operator groups

Operator groups are named sets of bot members that dialogs are routed to. Pass a group’s id as group_id to update_support_dialog_meta and as scope or overflow_group_id to the schedule and auto-reply tools. These tools appear only after the matching backend version is deployed. Check for each of them in tools/list.

  • list_operator_groups · support:read · bot_id. Returns a groups array sorted by name. Each group has id, name, strategy, and member_ids: the account IDs of its members, or an empty array. The order of member_ids in the list is not guaranteed.
  • create_operator_group · support:write · bot_id, name, and optional strategy. Leading and trailing spaces in name are trimmed. An empty name returns name is required, and a name longer than 200 characters returns name must be at most 200 characters. The name is unique within the bot. strategy takes least_busy (default), round_robin, or all; any other value returns strategy must be least_busy, round_robin or all. Returns group and created.
  • delete_operator_group · support:write · bot_id, group_id. Deletes the group. Response: {"status": "deleted", "group_id": "…"}.
  • add_operator_group_member · support:write · bot_id, group_id, owner_id. Adds a bot member to the group. Returns group and changed.
  • remove_operator_group_member · support:write · bot_id, group_id, owner_id. Removes the account from the group. Returns group and changed.

In write responses, group has the same fields as in the list, with member_ids sorted by ID. When a dialog is routed to a group, least_busy assigns it to the member with the fewest open dialogs assigned to them, and round_robin to the member who has gone longest without an assignment. With all, automatic assignment currently picks a member the same way as with least_busy. MCP cannot rename a group or change the strategy of an existing one.

Pass the account ID of the bot owner or a bot admin as owner_id. For any other account, including one whose data processing is suspended, add_operator_group_member returns owner_id is not a member of this bot. A member who loses access to the bot is removed from its groups automatically. MCP has no tool for listing bot members: account IDs appear in member_ids and in assignee_id from get_support_dialog_meta. remove_operator_group_member does not check bot membership.

Deleting a group also deletes its routing rules, its schedule with holidays, and its auto-reply policies. Dialogs lose the group in group_id but keep their assignee, and schedules that used the group as overflow_group_id lose that setting. While an active or paused AI agent hands dialogs off to the group, deletion is refused with operator group is the handoff target of an active or paused AI agent: change the agent’s handoff group first. Deletion cannot be undone: a group recreated with the same name gets a new id, and its members, rules, and schedule have to be set up again.

Pass every ID as a canonical UUID: lowercase with hyphens. Otherwise the server returns an error such as group_id must be a canonical UUID. For a foreign, archived, or inaccessible bot the server returns bot not found, and for an unknown group or another bot’s group operator group not found. Groups can be changed only with a token issued for the bot owner’s cabinet. With any other token, writes are rejected with bot not found or permission denied.

list_operator_groups requires the support:read scope; the other tools require support:write. With a read-only scope, writes return insufficient scope. The token holder needs the bot’s Dialogs permission (dialogs); without it the server returns missing bot right. If the project requires 2FA, it must be enabled on the token holder’s account; otherwise the server returns two_factor_enrollment_required. On writes, the token, scope, permission, and 2FA are checked again in the same transaction. If the token was revoked or permissions changed, nothing is written and the server returns permission denied or bot not found. Every write is recorded in the action log and marked as MCP.

These tools have no idempotency key, so keep the retry behavior in mind:

  • Repeating create_operator_group with the same name and strategy does not create a copy and returns the existing group with created: false. Without strategy, least_busy is used. The same name with a different strategy returns an operator group with this name already exists with a different strategy, and the group stays unchanged. The same error can occur if a group with this name is being deleted at that moment, so check list_operator_groups before retrying.
  • Repeating add_operator_group_member or remove_operator_group_member is safe: if the account is already in the group or already removed, nothing changes and the current group is returned with changed: false.
  • Repeating delete_operator_group returns operator group not found.
  • operator group change conflicted with a concurrent update; retry means nothing was written, and you can repeat the same call. After operator group could not be changed, check the state with list_operator_groups before retrying. account processing is suspended means that processing of the account’s data is suspended; retrying will not help.

Support routing rules

Routing rules automatically assign a new dialog to an operator group or to a specific bot member. These tools appear only after the matching backend version is deployed. Check for each of them in tools/list.

  • list_routing_rules · support:read · bot_id. Returns a rules array: all of the bot’s rules, enabled and disabled, in evaluation order. Rules are sorted by priority, and rules with equal priority by name.
  • create_routing_rule · support:write · bot_id, name, exactly one of group_id and assignee_id, and optional priority, enabled, and match. Each call creates a new rule. Returns rule.
  • update_routing_rule · support:write · bot_id, rule_id, and at least one of name, priority, enabled, match, group_id, or assignee_id. With no changes the server returns nothing to update. Returns the updated rule.
  • delete_routing_rule · support:write · bot_id, rule_id. Deletes the rule. Response: {"status": "deleted", "rule_id": "…"}.
  • reorder_routing_rules · support:write · bot_id, expected_rule_ids, rule_ids. Sets the order of all of the bot’s rules and returns a rules array in the new order.

A rule has id, bot_id, name, priority, enabled, match, and one of group_id or assignee_id. match contains only the conditions that are set; for a rule without conditions it is {}. Leading and trailing spaces in name are trimmed. An empty name returns name is required, and a name longer than 200 characters returns name must be at most 200 characters. Names are not required to be unique. priority is an integer in the 32-bit range, negative values included: the lower the value, the earlier the rule is evaluated. Without priority, a new rule gets 100; without enabled, it is created enabled. When create_routing_rule or update_routing_rule returns a rule with a non-empty match.tags, the response also contains a warnings array.

Conditions. Every list in match is optional, and a rule matches only when all of the conditions that are set hold. Without match, or with an empty match, the rule matches any new dialog.

  • platforms: the channels the message came from: tg, vk, wa, web, email, ig, or fb. One match is enough. Values are lowercased; any other value returns match.platforms must contain only tg, vk, wa, web, email, ig or fb.
  • keywords: case-insensitive substrings of the first inbound message. One match is enough.
  • labels: subscriber label names, case-sensitive. The subscriber must have all of the listed labels.
  • tags: IDs of this bot’s dialog tags from list_support_dialog_tags. This condition never holds: routing runs on the first inbound message, before any tag can be added. The rule is saved, and warnings carries a notice about this.

Each list can hold up to 50 values. Values in keywords and labels cannot be empty or consist only of spaces, and are limited to 200 characters. Otherwise the server returns a validation error such as match.keywords must have at most 50 entries. A tag of another bot or an unknown tag returns dialog tag not found in this bot.

Target. Pass the ID of a group from list_operator_groups as group_id, or the account ID of the bot owner or a bot admin as assignee_id. Set exactly one of these fields; otherwise the server returns specify exactly one of group_id or assignee_id. An unknown group or another bot’s group returns group does not belong to this bot, and an account that is not a member of the bot returns assignee is not a member of this bot. A group’s rules are deleted together with the group, and a member’s rules when the member loses access to the bot.

Partial updates. update_routing_rule changes only the fields you pass. match is replaced as a whole: to add a keyword, pass the entire new match, and {} removes all conditions. A group_id or assignee_id you pass replaces the target and clears the other field, so pass only one of them. If the change leaves no target or two targets, for example group_id: "" without assignee_id, the server returns specify exactly one of group_id or assignee_id. When the target changes or enabled: true is passed, the server checks again that the target belongs to the bot; tags are checked only when match is passed. Rules have no revision: an update is written over the current state even if someone else has just changed the rule.

Order. Pass the IDs of all of the bot’s rules, including disabled ones, in their current order from list_routing_rules as expected_rule_ids, and the same IDs in the desired order as rule_ids. Without these fields the server returns expected_rule_ids is required or rule_ids is required. If rule_ids contains a different set of IDs or duplicates, the server returns invalid routing rule order: rule_ids must be a permutation of expected_rule_ids. If a rule was added or deleted, or the order changed, after you read the list, the call changes nothing and returns routing rules changed; reload and retry. On success the rules get priorities 10, 20, 30, and so on. A new rule with the default priority 100 lands after rules with a lower priority, and among rules with equal priority its place is decided by name.

How rules apply. Routing runs once: on the first inbound message of a dialog that has neither an assignee nor a group. The server evaluates enabled rules in order and applies the first one that matches. For a group, the operator is picked by the group’s strategy, taking schedules and overflow_group_id into account. For a member, the bot schedule applies, and if the member is unavailable, another member of one of their groups may get the dialog. If no operator is available for the first matching rule, later rules are not evaluated and the dialog stays in the unassigned queue. The same happens when no rule matches. Creating, changing, deleting, or reordering rules does not affect dialogs that are already assigned: they keep their assignment.

Pass every ID as a canonical UUID: lowercase with hyphens. Otherwise the server returns an error such as rule_id must be a canonical UUID. For a foreign, archived, or inaccessible bot the server returns bot not found, and for an unknown rule or another bot’s rule routing rule not found. Rules can be changed only with a token issued for the bot owner’s cabinet. With any other token, writes are rejected with bot not found or permission denied.

list_routing_rules requires the support:read scope; the other tools require support:write. With a read-only scope, writes return insufficient scope. The token holder needs the bot’s Dialogs permission (dialogs); without it the server returns missing bot right. If the project requires 2FA, it must be enabled on the token holder’s account; otherwise the server returns two_factor_enrollment_required. On writes, the token, scope, permission, and 2FA are checked again in the same transaction. If the token was revoked or permissions changed, nothing is written and the server returns permission denied or bot not found. Every write is recorded in the action log and marked as MCP.

These tools have no idempotency key, so keep the retry behavior in mind:

  • Repeating create_routing_rule creates another rule with a new id, even when the fields are the same. If the response to a create was lost, check list_routing_rules first.
  • Repeating update_routing_rule writes the passed values again. If someone else changed the rule between attempts, the retry overwrites those fields. If the response was lost, check the rule in list_routing_rules first.
  • Repeating delete_routing_rule returns routing rule not found. Deletion cannot be undone: a rule created again gets a new id.
  • After a successful reorder_routing_rules, repeating it with the same expected_rule_ids usually returns routing rules changed; reload and retry, because the order is already different. The same error appears when someone else changed the rules. In both cases, read list_routing_rules again, check the order, and only then retry with new expected_rule_ids.
  • After routing rule could not be changed, check the state with list_routing_rules before retrying. account processing is suspended means that processing of the account’s data is suspended; retrying will not help.

Operator dialog read status

These tools use the same unread counters as the operator inbox: they show how many incoming messages the token holder has not read yet and mark a dialog as read, just like opening it in the console. These tools appear only after the matching backend version is deployed. Check for each of them in tools/list.

  • get_dialog_unread_summary · support:read · bot_id. Returns {"items": [...], "count": N}: the token holder’s unread messages across the bot’s dialogs, email included. Dialogs without unread incoming messages are omitted. Each row has user_id and unread, plus channel_id, scope_channel_id, and subscriber_id when they are not empty. One user can appear in several rows, one per channel. There is no pagination, and the row order is not guaranteed.
  • get_dialog_read_state · support:read · bot_id, user_id, optional channel_id and subscriber_id. Returns the read status of one dialog without changing anything.
  • mark_dialog_read · support:write · bot_id, user_id, optional channel_id, subscriber_id, and last_read_message_id. Marks the dialog as read for the token holder and returns the new status.

The get_dialog_read_state and mark_dialog_read responses contain unread (the number of unread incoming messages), first_unread_message_id (the ID of the earliest unread message in feed order, omitted when everything is read), last_read_message_id (the token holder’s own read mark, or 0 if they have not read the dialog), and shared (true when shared read status applies to the token holder).

Choosing the dialog. user_id is the dialog user’s ID as a decimal string. Take user_id from a summary row or tg_user_id_str from list_dialogs and pass it unchanged as a string: the numeric tg_user_id loses precision for large IDs. Leading zeros, a + sign, exponents, and 0 are rejected with user_id must be a non-zero decimal integer string.

To target a dialog from the summary, pass its scope_channel_id as channel_id, not the row’s channel_id field. In the summary, channel_id is empty for a legacy Telegram dialog that is not bound to a channel, while scope_channel_id names the channel the messages and the read mark belong to. For an exact match, add subscriber_id from the same row. It cannot be passed without channel_id: the server returns subscriber_id requires channel_id. If a row has no scope_channel_id, pass neither channel_id nor subscriber_id.

Without channel_id and subscriber_id, the tools work with the legacy dialog in the bot’s main Telegram channel, like the console route without a channel. This is the same read mark as with that Telegram channel’s channel_id. list_dialogs returns no channel ID, so tg_user_id_str alone reaches only this dialog. A user’s dialogs in different channels are read separately: a mark in one channel does not change the counter in another.

Pass UUIDs in canonical form: lowercase with hyphens. Otherwise the server returns an error such as channel_id must be a canonical UUID. If the channel belongs to another bot, the user has no dialog in that channel, subscriber_id belongs to another dialog, or the subscriber has been merged into another one, the server returns dialog scope not found. After a subscriber merge, get the row from the summary again. invalid dialog scope means an invalid combination of channel_id and subscriber_id.

Marking as read. Without last_read_message_id, or with 0, the whole dialog is marked as read as of the call. To mark it read up to a specific point, pass the id of a message in this dialog, for example from read_dialog: later messages in feed order stay unread. A message from another dialog or channel returns message not found in this dialog, and a negative value returns last_read_message_id must not be negative. The mark only moves forward: if the message is earlier than the current mark, the mark stays unchanged and the current status is returned.

The mark belongs to the token holder, not the bot owner, and changes only the token holder’s counters. Nothing is sent to the customer, no read receipt is delivered, and the messages and support dialog status do not change. When the mark moves, open operator consoles refresh their counters.

Shared read status. If shared read status is turned on for the whole bot or in the token holder’s personal settings (see Support), unread, first_unread_message_id, and the summary count from the latest mark of any operator, and shared is true. Even in this mode, last_read_message_id remains the token holder’s own mark. As a result, mark_dialog_read can also clear the counter for colleagues who have shared read status. Without it, a mark affects only the token holder.

Access and errors. get_dialog_unread_summary and get_dialog_read_state require the support:read scope, and mark_dialog_read requires support:write. With a read-only scope, marking returns insufficient scope. The token holder needs the bot’s Dialogs permission (dialogs); without it the server returns missing bot right. If the project requires 2FA, it must be enabled on the token holder’s account; otherwise the server returns two_factor_enrollment_required. For a foreign, archived, or inaccessible bot the server returns bot not found. Dialogs can be marked as read only with a token issued for the bot owner’s cabinet. With any other token, the write is rejected with bot not found or permission denied. When marking, the token, scope, permission, and 2FA are checked again in the same transaction. If the token was revoked or permissions changed, nothing is written and the server returns permission denied or bot not found. Every mark_dialog_read call, including a rejected one, is recorded in the action log and marked as MCP. Reads are not logged.

The errors unread summary is temporarily unavailable, dialog read state is temporarily unavailable, and dialog could not be marked read are temporary. mark_dialog_read has no idempotency key, but retrying is safe: the mark never moves backwards, and a retry with the same last_read_message_id changes nothing. A retry without last_read_message_id also marks messages that arrived between attempts.

Support schedules, holidays and auto-replies (support)

Check tools/list after the server update for availability. The personal token holder needs the bot’s Dialogs permission (dialogs). If the project requires 2FA, enable it on the token holder’s account.

Pass bot_id to every call. For scope, use bot or the UUID of an operator group on that bot.

  • list_support_schedules · support:read · bot_id. Lists schedules and revisions for the bot and its operator groups.
  • list_support_holidays · support:read · bot_id, scope. Lists the holidays for a schedule and returns its current revision.
  • list_support_auto_replies · support:read · bot_id. Lists auto-reply policies and revisions for the bot and its operator groups.
  • preview_support_availability · support:read · bot_id, scope, from, to. Shows the state at from and subsequent transitions through to using the saved schedule and holidays. Pass RFC 3339 timestamps. The interval must be positive and at most 31 days. The preview saves no changes and sends no messages. The response includes up to 512 transitions entries with at, state and reason.
  • upsert_support_schedule · support:write · bot_id, scope, timezone, weekly_intervals, enabled, expected_revision. Creates or replaces a schedule. Pass an IANA time zone such as Europe/Belgrade and the full set of weekly intervals. Each interval has weekday (0 for Sunday through 6 for Saturday), start_minute and end_minute as local minutes since midnight. The optional overflow_group_id refers to a group on the same bot.
  • replace_support_holidays · support:write · bot_id, scope, holidays, expected_revision. Replaces all holidays for an existing schedule. Each entry takes local_date (YYYY-MM-DD), kind (closed or custom), name and intervals. Use empty intervals for closed and provide intervals with start_minute and end_minute for custom. Pass holidays: [] to clear the list.
  • upsert_support_auto_reply · support:write · bot_id, scope, state, content_document_id, content_version, interval_seconds, enabled, expected_revision. Saves a policy for working or non_working hours. Use a published version of an unarchived content document on the same bot and set the interval between auto-replies in seconds (1–2,678,400).

Every write requires expected_revision. Use 0 only to create a schedule or auto-reply policy. For an update, use the current revision from a read response. A schedule and its holidays share a revision, which changes when either is updated. An auto-reply policy has its own revision for each scope and state pair. If the revision is stale, read the latest data and reapply your changes.

These tools configure support operations. To read or update the web widget’s own availability settings, use get_widget_settings or update_widget_settings.

Stats and analytics (stats)

get_support_analytics returns the support report for a selected period; get_support_analytics_details returns paginated metric details using a signed cursor. Both require stats:read and the project analytics right; the period cannot exceed 366 days.

  • get_stats: stats:read
  • get_stats_summary: stats:read
  • get_stats_recent: stats:read
  • get_stats_log: stats:read
  • get_reaction_health: stats:read
  • get_analytics: stats:read
  • get_analytics_chats: stats:read
  • get_site_widget_analytics: stats:read
  • get_site_popup_analytics: stats:read
  • get_funnel: stats:read

Both tools require the project's Analytics right and the stats:read scope. Pass bot_id, from, and to; specify the period boundaries as RFC 3339 timestamps. The start is inclusive and the end exclusive: [from, to). The period must be positive and at most 366 days; result days are in UTC.

get_site_widget_analytics returns counts of received website pageviews, observed visitor identifiers over the whole period, active web dialogs, and inbound messages, plus daily data. Pageviews can include server-side events, and identifiers do not necessarily represent unique people. get_site_popup_analytics returns shown, viewed, interacted, and converted event counts by popup and UTC day. These are counts of events, not people. A viewed impression means at least half of the popup was on screen for two consecutive seconds in a visible tab; it does not prove the text was read. Neither tool returns financial data.

  • get_popup_report (popups:read + subscribers:read) – Daily metrics for one popup (days).

  • get_site_popup_analytics (stats:read) – Totals by popup for the period and daily totals across popups (popups, days).

  • measured_shown. Number of distinct impressions recorded with a valid impression_id and a contact ID (subscriber_id).

  • converted_impressions. Number of those impressions with a matching conversion. Each impression counts at most once.

  • impression_conversion_rate = converted_impressions / measured_shown

  • impression_coverage = measured_shown / shown

Both rates are fractions from 0 to 1. Each is null when its denominator is zero.

A conversion must match the impression ID, project, popup, variant, and contact. It can be recorded from 60 seconds before the impression up to, but excluding, 24 hours after it. It counts toward the UTC day of the impression.

Historical events without impression IDs still count in shown, viewed, interacted, and converted by event time. They cannot be linked to a measured impression. If a period has only unmeasured impressions, coverage is 0 and the impression conversion rate is null.

Shared experiments (experiments)

  • list_experiments: experiments:read
  • get_experiment: experiments:read
  • get_experiment_report: experiments:read

These tools are read-only. They return the immutable experiment definition or the report for one version. The report keeps currencies separate and carries the selected attribution model; it does not create assignments, record facts, change a lifecycle state, or select a winner.

{
  "name": "get_experiment_report",
  "arguments": { "bot_id": "<bot-id>", "experiment_id": "<experiment-id>", "version": 2 }
}

Saved event funnels currently use REST only. Do not confuse the legacy get_funnel tool above, which returns the auto-derived stats funnel, with a saved event funnel definition or its cohort. Use the bounded REST endpoints in Saved event funnels for those workflows.

Billing: read (billing)

  • get_balance: billing:read
  • list_tariffs: billing:read
  • get_transactions: billing:read

In somebody else's account all three require the account right billing.read, otherwise: permission denied: missing cabinet right.

Sending messages

  • send_message: broadcasts:write: send a message on behalf of the bot; balance charges are tracked automatically by the token owner.

Resources

In addition to tools, the server exposes resources you can read to avoid guessing structure:

  • mybot://openapi.yaml: the full OpenAPI spec (same as served at /openapi.yaml).
  • mybot://reference: a compact reference: tool list with scopes and conventions (base URL, pagination, error format, limits).
  • mybot://schemas/reaction, mybot://schemas/trigger, mybot://schemas/action, mybot://schemas/flow, mybot://schemas/collection: JSON schemas for configs. Most useful for correctly generating reactions (trigger, conditions, chats, actions), scenarios, and collections.
  • mybot://bots: a dynamic list of your bots (quick context without calling a tool).

Prompts

Ready-made scenarios (slash commands in MCP clients):

  • setup_autoresponder: build an autoresponder bot (arguments: bot, topic/question set).
  • segment_broadcast: broadcast to a label segment (arguments: bot, labels, reaction/text).
  • diagnose_reaction: figure out why a reaction is not triggering (reads the reaction, reaction health, and order).
  • import_from_sambot: run a SamBot bundle import and verify the result.
  • weekly_report: summary of bot stats/analytics for a period.

When to use MCP vs. REST

  • Building an integration, sync job, script, or custom dashboard: use REST.
  • Connecting GetMyBot to an AI assistant or agent that supports MCP: use /mcp.

Both interfaces work under the same token and are subject to the same owner permissions. If no tool covers your use case, the corresponding REST endpoint is always available in the interactive reference.

Feature rollout gates are identical on both surfaces. Copilot, Flow Intelligence, Explainable Replay, and Vertical Playbooks fail closed when the account is not included in the rollout.

Customer AI and workflow tools

FamilyToolsRequired scopes
Managed AIinvoke_managed_ai, get_managed_ai_usagemanaged_ai:invoke, managed_ai:usage:read
Copilotcreate_copilot_proposal, get_copilot_proposal, validate_copilot_proposal, simulate_copilot_proposal, apply_copilot_proposal, reject_copilot_proposalcopilot:use + journey read/edit
Flow Intelligenceget_flow_intelligence_policy, preview_flow_intelligence_policy, update_flow_intelligence_policy, reaggregation toolsanalytics:read, journey:edit
Replaylist_execution_traces, get_execution_trace, simulate_execution_trace, capture_regression_fixture, list_regression_fixtures, get_regression_fixture, run_regression_fixture, list_replay_runsjourney:read/edit
Playbookslist_vertical_playbooks, setup/preflight/install/upgrade tools; KPI remains REST-onlytemplate, bot, reaction read/write
Onboardingstart_outcome_onboarding, update_outcome_onboarding, complete_outcome_onboardingbot/template/reaction scopes
Metalist_meta_connections, start_meta_authorization, refresh_meta_assets, asset check/select/attach and disconnect toolsintegration/bot scopes

Mutations are audited with the MCP surface and PAT token id. OAuth returns a browser handoff URL; the callback and webhooks are never tools. Provider keyring, routing, and reconciliation are not published to customer agents.

What's next

Visual tracking rules

list_tracking_rules requires tracking:read; creation, updates and deletion require tracking:write, permission to manage reactions, and applicable 2FA. Enabled rules collect events and specified values on matching pages: review settings before enabling. For updates and deletion pass the current revision from the list as expected_revision; on conflict, read the rule again. Omitted update fields stay unchanged.

  • list_tracking_rules: bot_id
  • create_tracking_rule: bot_id, name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • update_tracking_rule: bot_id, rule_id, expected_revision; name, event_name, trigger_kind, selector, page_patterns, extractions, enabled
  • delete_tracking_rule: bot_id, rule_id, expected_revision