پایگاه دانش GetMyBot

REST API and Tokens

Programmatic access to your bot: API tokens, personal tokens, and mobile access.

در این صفحه

Beyond the visual builder, GetMyBot is open programmatically: bot data can be managed via the REST API. There are two kinds of tokens: per-bot access tokens and personal tokens (for account-level automation and integrations).

Bot API tokens

Created in Settings → API tokens. Each token is tied to a bot and grants access to its REST endpoints (reactions, users, collections, stats, etc.). The token is shown only once at creation: save it somewhere safe; the list shows the name, a masked value, and the creation date. Delete any tokens you no longer need.

Personal access tokens (PAT)

Personal access tokens (PAT, prefixed with mbp_) work at the account level and are used for automation and integrations. Created in the account dashboard; passed in the Authorization: Bearer mbp_… header. A token has scopes: a set of permissions in the form resource:action (for example, reactions:read, bots:write), and * means full access. Tokens have an expiry and are stored in hashed form. This is a convenient way to give a script limited access without sharing your password.

What is accessible via the API

The API exposes the same entities as the UI: bots and their settings, reactions (including import/export), subscribers and labels, collections and records, stats and request logs, and broadcasts. This lets you build custom dashboards, syncs, and automations on top of GetMyBot.

Channels & WhatsApp

GetMyBot is multichannel (Telegram + WhatsApp + VK), and a bot's channels are managed over REST as well. Channels and WhatsApp templates are gated by the shared scopes bots:read / bots:write: there is no separate channel scope.

  • GET /api/channels/capabilities (bots:read): the channel capability matrix (web sessions work without a scope).
  • GET /api/bots/{botID}/channels (bots:read): list a bot's channels.
  • POST /api/bots/{botID}/channels (bots:write): connect a WhatsApp or VK channel.
  • DELETE /api/bots/{botID}/channels/{channelID} (bots:write): disconnect a channel.
  • GET /api/bots/{botID}/channels/{channelID}/templates (bots:read): the channel's WhatsApp template catalog.
  • POST /api/bots/{botID}/channels/{channelID}/templates (bots:write): create a template and submit it to Meta for review.
  • POST /api/bots/{botID}/channels/{channelID}/templates/sync (bots:write): re-sync the catalog from Meta.
  • PUT /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): edit a template.
  • DELETE /api/bots/{botID}/channels/{channelID}/templates/{templateID} (bots:write): delete a template.
  • POST /api/bots/{botID}/channels/{channelID}/templates/media (bots:write): upload a header media example (image/video/document).

Request/response schemas, parameters, and examples are in the API Reference.

CRM connections

CRM has its own scope pair, crm:read / crm:write, separate from integrations:*: a tenant's CRM credentials and sync operations are far more sensitive than a Sheets connection. Every route also checks the bot's Reactions right.

Connecting depends on the provider:

  • POST /api/bots/{botID}/crm/connections/amocrm/start (crm:write): send {"account_key": "acme.amocrm.ru"} and receive a redirect_url to open in a browser. Starts are limited to three per minute per account, and the endpoint answers 503 while the platform has no amoCRM OAuth application configured. Bitrix24 answers 503 too, for the same reason.
  • GET /api/integrations/crm/{provider}/callback: the browser redirect target. It needs no token: the single-use, five-minute state issued by the start call is the authentication. It returns the connection's safe summary, never its credentials.
  • POST /api/bots/{botID}/crm/connections/retailcrm (crm:write): connect with an API key.
  • POST /api/bots/{botID}/crm/connections/ozmacrm (crm:write): connect with OIDC client credentials, a login, and the entity configuration.

Beyond connecting there are routes for field discovery, pipelines, mapping revisions, preview, initial sync, reconcile, operations and jobs, and conflict resolution, plus DELETE /api/bots/{botID}/crm/connections/{connectionID} to disconnect. Three more per-subscriber actions (CRM status, manual sync, conversation export) live under /api/bots/{botID}/subscribers/{subscriberID}/crm/… with the subscribers:* scopes and the Dialogs right.

Six read-only MCP tools mirror the CRM reads: see MCP. The full route table, scopes, and provider behaviour are on CRM integrations.

Content, email campaigns and popups

The content vertical has its own scopes. Content, campaign and popup endpoints also check the bot-level Reactions right, so a token cannot reach further than the account it belongs to.

  • content:read / content:write: content documents and templates: GET|POST /api/bots/{botID}/content, GET /api/bots/{botID}/content/{documentID}, PATCH /api/bots/{botID}/content/{documentID}/draft, POST /api/bots/{botID}/content/{documentID}/publish|clone|archive|test-send, POST /api/bots/{botID}/content/{documentID}/validate|preview, GET /api/bots/{botID}/content/test-recipients, GET|POST /api/bots/{botID}/content-templates, DELETE /api/bots/{botID}/content-templates/{templateID}.
  • email_campaigns:read / email_campaigns:write: campaigns and their reports: GET|POST /api/bots/{botID}/email-campaigns, GET|PATCH /api/bots/{botID}/email-campaigns/{campaignID}, GET /api/bots/{botID}/email-campaigns/{campaignID}/report|recipients|links, POST /api/bots/{botID}/email-campaigns/{campaignID}/consent-preview, POST /api/bots/{botID}/email-campaigns/{campaignID}/test-send|schedule|clone|pause|resume|cancel|archive.
  • popups:read / popups:write: GET|POST /api/bots/{botID}/popups, PATCH|DELETE /api/bots/{botID}/popups/{popupID}, GET /api/bots/{botID}/popups/{popupID}/stats|experiment, POST /api/bots/{botID}/popups/preflight.
  • settings:read / settings:write: sending domains and inbound email routes under /api/bots/{botID}/email/…. A sending domain is bot configuration, so it stays on the settings scope rather than a new one. Reading them needs only access to the bot; creating, verifying and deleting them needs the Reactions right as well.

Note that consent-preview, validate and preview are POST requests even though they change nothing; they are audit events like any other authenticated POST.

Mutations use optimistic concurrency. Send the expected_revision you read, and treat 409 as "reload and retry", not as a transport error. POST /api/bots/{botID}/email-campaigns/{campaignID}/schedule also requires "confirm": true, and answers 422 with the full recipient check when the campaign is not ready.

The public tracking, unsubscribe and provider webhook endpoints (/e/t/…, /u/…, /esp/{provider}/webhook, /esp/{provider}/inbound) are not part of the token API. They are described in Email campaigns.

Browser push and the customer SDK

Both verticals have their own scope pair and, like the content routes, check a bot-level right: reads need the Analytics right, writes need the Reactions right. Every mutation is audited.

Browser push: web_push:read / web_push:write:

  • GET /api/bots/{botID}/web-push (web_push:read): the redacted configuration: the VAPID public key, subject, allowed navigation origins and quiet hours. The private key is never returned.
  • GET /api/bots/{botID}/web-push/subscriptions (web_push:read): recent subscriptions with consent status, browser family, locale and timezone. The push endpoint and its encryption keys are never serialized.
  • GET /api/bots/{botID}/web-push/report (web_push:read): subscription and receipt counters.
  • POST /api/bots/{botID}/web-push/enable (web_push:write): generates the VAPID key pair on first call, then behaves as an idempotent settings update.
  • PATCH /api/bots/{botID}/web-push (web_push:write): subject, navigation origins, quiet hours, enabled flag.
  • POST /api/bots/{botID}/web-push/rotate-keys (web_push:write): answers 409 with the active-subscription count until you send "confirm": true; confirming expires every existing subscription.
  • POST /api/bots/{botID}/web-push/test (web_push:write): the only send that exists: one message to one subscription, referencing a published Push content document.

Customer SDK: customer_sdk:read / customer_sdk:write:

  • GET /api/bots/{botID}/customer-sdk (customer_sdk:read): the redacted project: project key, region, app allowlists, identity-secret version and, during a rotation, when the previous secret lapses.
  • GET /api/bots/{botID}/customer-sdk/installations (customer_sdk:read) , up to 200 recent installations.
  • GET /api/bots/{botID}/customer-sdk/report (customer_sdk:read) , installation and push-token counters.
  • POST /api/bots/{botID}/customer-sdk/enable (customer_sdk:write): creates the project and returns the identity secret once; afterwards it is an idempotent settings update. It answers 503 on a deployment where the project-key signing secret is not configured.
  • PATCH /api/bots/{botID}/customer-sdk (customer_sdk:write): app allowlists and the enabled flag.
  • POST /api/bots/{botID}/customer-sdk/rotate-secret (customer_sdk:write) , returns a new identity secret and keeps the previous one valid for 24 hours.
  • DELETE /api/bots/{botID}/customer-sdk/installations/{installationID} (customer_sdk:write): revokes one device.

The SDK's own device-facing surface, /sdk/v1/*, is not part of this API. It authenticates with an installation token plus an identity epoch and rejects personal access tokens by design, exactly as /api/* rejects an installation token. It is documented in a separate OpenAPI document the server publishes unauthenticated at GET /sdk/openapi.yaml.

Broadcasts

Broadcasts have exactly one scope: broadcasts:write. There is no read/write pair here like content, email campaigns and popups have, so reading also requires broadcasts:write: the list, the report and the paged recipients alike. A read-only broadcast token cannot be issued. Every route also checks the bot-level Reactions right.

Second-generation broadcasts: content, audience and channels:

  • GET /api/bots/{botID}/broadcasts: list; ?archived=true includes archived ones.
  • POST /api/bots/{botID}/broadcasts: create a draft.
  • PATCH /api/bots/{botID}/broadcasts/{broadcastID}: edit a draft.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/preflight: check recipients; it sends nothing, but it is a POST and is audited as one.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/schedule: launch.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/test-send: test to one verified contact.
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/archive: archive.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/report: per-channel report.
  • GET /api/bots/{botID}/broadcasts/{broadcastID}/recipients: recipients, with limit and cursor.

The older reaction broadcasts are still here, on the same base path. They are started by their own route, POST /api/bots/{botID}/reactions/{reactionID}/broadcast, with a body of {"paid": false, "labels": ["vip"]}: the only place where a broadcast can be narrowed by labels. Four routes are shared by both systems:

  • GET /api/bots/{botID}/broadcasts/{broadcastID},
  • POST /api/bots/{botID}/broadcasts/{broadcastID}/pause|resume|cancel.

The handler tries the second-generation broadcast first and only then falls back to the legacy row, so both the body and the response depend on which system owns the id. A second-generation broadcast needs {"expected_revision": N} and returns the whole broadcast; the legacy one ignores the body and answers {"status": "pausing"}, {"status": "resuming"} or {"status": "canceled"}.

Request bodies are strict: an unknown field is a 400, not a silently ignored key. Mutations use optimistic concurrency: send the expected_revision you read and treat 409 as "reload and retry". schedule also requires "confirm": true; without it the answer is 400.

What the broadcast status codes mean:

  • 402: the bot owner's plan does not include the broadcasts feature;
  • 403: paid broadcasts are not enabled for this bot;
  • 409: a stale revision, or the broadcast is not ready to launch (unpublished content, a stale segment, a non-running experiment, an empty audience);
  • 422: the content is missing or fails validation for one of the channels;
  • 429: too many test sends.

Over MCP the same scope covers start_broadcast, get_broadcast, pause_broadcast, resume_broadcast, cancel_broadcast, list_content_broadcasts and get_content_broadcast_report. The last two and get_broadcast only read, yet they still require broadcasts:write , there simply is no read scope. Creating a draft, editing it, checking recipients, launching, test-sending and archiving a second-generation broadcast are not exposed over MCP, only over REST; pause_broadcast, resume_broadcast and cancel_broadcast act on legacy reaction broadcasts only. For the product-level description of both flows see Broadcasts.

Mobile access

The platform has a mobile app with its own authorization (access and refresh tokens) and a unified bot dashboard: it uses the same backend.

API reference

The full interactive reference for the public API is available on the API Reference page: it lists all PAT-accessible endpoints, parameters, request and response schemas, required scopes, and ready-to-use examples (curl, JavaScript, Python). You can execute a test request with your own token directly from the page.

Funnels and experiments

Saved funnel definitions and reports use analytics:read and analytics:write; saving a cohort as a segment also requires segments:write. Experiment definitions, lifecycle operations, reports, and cohorts use experiments:read and experiments:write. All of these endpoints also check the bot-level Analytics right. Audit logging follows the HTTP method: an authenticated owner's POST, PUT, PATCH, and DELETE request is recorded, including semantically read-only report, query, and cohort requests sent with POST. GET read and list requests are not audit events.

Always send bounded RFC3339 UTC ranges for reports. Funnel and experiment reports are limited to 366 days. Experiment revenue uses an integer minor field and an ISO 4217 currency; do not calculate a mixed-currency total on the client.

curl "$BASE_URL/api/bots/$BOT_ID/funnels?limit=50&cursor=$CURSOR" \
  -H "Authorization: Bearer $PAT"

Use the next cursor returned by the server unchanged. A bad cursor or body returns 400, and a resource or explicitly requested experiment version that is unavailable in the bot returns 404. A stale mutation revision or winner selection conflict returns 409. Full request bodies and response schemas are in the API Reference and the funnels and experiments guides.

Security

  • Tokens are shown once; treat them as secrets.
  • Bot and credential secrets are stored encrypted.
  • Audit logging is method-based: authenticated POST, PUT, PATCH, and DELETE requests are recorded; GET reads are not.

Customer AI, intelligence, playbooks, and Meta

The customer API now includes the complete agent workflow:

  • Managed AI: POST /api/v1/ai/responses (managed_ai:invoke) and GET /api/v1/ai/usage (managed_ai:usage:read). Profiles are fast, balanced, and quality; provider is auto, openai, anthropic, or deepseek. Invocation requires an Idempotency-Key and never falls back from a tenant key to paid Managed AI silently.
  • Copilot: create under /api/reactions/{rootID}/copilot/proposals, then get, validate, simulate, apply, or reject under /api/copilot/proposals/{proposalID}. Applying creates a new draft version, not a publication.
  • Flow Intelligence: overlay and samples under a reaction plus account policy and bounded reaggregation under /api/bots/{botID}/flow-intelligence/*.
  • Explainable Replay: execution traces, deterministic simulation, redacted regression fixtures, and runs under /api/bots/{botID}. Protected artifact reveal is not an agent operation.
  • Vertical Playbooks: /api/playbooks/catalog, resumable setup/preflight/install/upgrade under /api/playbook-installs/{installID}, and KPI reads.
  • Outcome onboarding: POST|PATCH /api/onboarding/session and POST /api/onboarding/session/complete.
  • Messenger and Instagram: /api/meta/connections returns an OAuth browser handoff, then exposes customer-owned assets for check, selection, and attachment. Tokens never appear in responses.

Provider keyring, routing, prices, and reconciliation are superadmin-only and intentionally absent from the customer API and MCP surface.

Copilot, Flow Intelligence, Explainable Replay, and Vertical Playbooks also enforce the account rollout. A disabled or unassigned feature fails closed and cannot be bypassed through MCP.

What's next