API & AI integration

Full workspace access via an API key: create and configure bots, manage channels, broadcasts and the inbox programmatically — or connect an AI (Claude and others) over MCP so it does the work for you.

1. Authentication & conventions

Every request carries the header Authorization: Bearer bs_live_…. Create a key in the app: Settings → API → Create key (shown once). A key has a scope (whole workspace / organization / project) and a role (admin / editor / operator) — default is whole-workspace + admin; for integrations grant the narrowest scope and role (least privilege). Billing is available only to a whole-workspace admin key.

API base URL: https://ultrabot.work/api

curl https://ultrabot.work/api/bots \
  -H "Authorization: Bearer bs_live_YOUR_KEY"

Keys via API

Keys can be managed programmatically too: GET /api/keys — list {id, name, prefix, created_at, revoked}; POST /api/keys {name} → {key, prefix, name} (the full bs_live_… key is returned once — store it immediately); POST /api/keys/revoke {id} — revoke. One key = one workspace.

Formats & errors

Request and response bodies are JSON (content-type: application/json). Success — a 2xx code and JSON. Errors return an HTTP code and a plain-text message body (not JSON): branch on the status code, show the text as-is.

Code	Meaning
`400`	Bad request (body/params)
`401`	Missing or expired authorization
`402`	Plan limit reached — upgrade required
`403`	Insufficient permissions (role)
`404`	Not found
`429`	Rate limit exceeded
`5xx`	Server error

Rate limits

Per IP+path, 60-second window: register/forgot — 5; login/reset-confirm — 20; billing/subscribe — 10; bots/import — 10; templates/clone — 20; widget messages — 60. Other endpoints have no hard limit. On excess — 429.

IDs & idempotency

Bot id looks like bot_…; a dialog id (sid) is the chat id as a string. PUT /api/bots/{id}/graph is a full replace of the draft (not a patch). POST /api/bots/{id}/publish creates a new snapshot version (publishing again = a new version; roll back via POST /api/bots/{id}/rollback/{version}).

2. Quick start: create and publish a bot

# 1) create a bot (returns id)
curl -X POST https://ultrabot.work/api/bots \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"name":"My bot"}'

# 2) set the flow (graph)
curl -X PUT https://ultrabot.work/api/bots/BOT_ID/graph \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"states":[...],"transitions":[...]}'

# 3) connect Telegram and publish
curl -X PUT https://ultrabot.work/api/bots/BOT_ID/telegram \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" -d '{"token":"123:ABC"}'
curl -X POST https://ultrabot.work/api/bots/BOT_ID/publish -H "Authorization: Bearer $KEY"

3. Full endpoint reference

Base URL: https://ultrabot.work/api. Every request carries Authorization: Bearer bs_live_…. A key works within its scope and role (default — whole workspace, admin; then all endpoints below are available except the platform super-admin panel). {id} — bot ID, {sid} — dialog ID (chat id).

Bots & graph

Method and path	Description
GET /api/bots	List active bots
POST /api/bots	Create a bot (draft) `{name}` → `{id}`
GET /api/bots/{id}	Bot + graph (states, transitions)
PUT /api/bots/{id}/graph	Replace the graph `{states, transitions}`
POST /api/bots/{id}/publish	Publish (graph snapshot → live)
GET /api/bots/{id}/validate	Validate the graph: errors/warnings
POST /api/bots/{id}/simulate	Test run `{text}` \| `{button}` \| `{reset:true}`
GET /api/bots/{id}/versions	Publish history
POST /api/bots/{id}/rollback/{version}	Roll the publication back to a version
GET /api/bots/{id}/export	Export the bot to JSON
POST /api/bots/import	Import a bot from JSON
GET /api/templates · POST /api/templates/{tid}/clone	Template gallery and cloning
DELETE /api/bots/{id}	Move to trash (soft: the bot stops replying, frees a slot)
GET /api/bots/archived	Trash: deleted bots
POST /api/bots/{id}/restore	Restore from trash (as a draft)
DELETE /api/bots/{id}/purge	Delete permanently (trash only) — irreversible

Website widget

A floating chat button on any site — one line (async, no page slowdown; full-screen on mobile):

<script src="https://ultrabot.work/widget.js" data-bot="BOT_ID" async></script>

Appearance (color, position, round button / side tab, theme, greeting bubble, avatar, branding) is configured in the app: bot → Website chat. Public config — GET /api/widget/{id}/config; save — PUT /api/bots/{id}/widget (editor+). Alternative — embed via <iframe src="https://ultrabot.work/widget/BOT_ID">.

Channels

Method and path	Description
GET/PUT /api/bots/{id}/telegram	Connect Telegram `{token}`
GET/PUT /api/bots/{id}/viber	Connect Viber `{token}`
GET/PUT /api/bots/{id}/channel/{name}	External channel: vk, ok, max, whatsapp, instagram, messenger, avito
GET/PUT /api/bots/{id}/commands	Telegram command menu `{list}`
GET/PUT /api/bots/{id}/comments-reply	Auto-reply to comments → DM
GET/PUT /api/bots/{id}/webhook-out	Outbound webhooks on bot events

Marketing

Method and path	Description
GET/POST /api/bots/{id}/broadcasts	Broadcasts (with segments/scheduling)
GET /api/bots/{id}/segment-count?tag=	Segment size by tag
GET/POST /api/bots/{id}/sequences	Drip sequences
DELETE /api/bots/{id}/sequences/{sid}	Delete a sequence
POST /api/bots/{id}/sequences/{sid}/enroll-all	Enroll all contacts into a sequence

Contacts & CRM

Method and path	Description
GET /api/bots/{id}/contacts?tag=&q=	Subscribers (filter by tag/search)
POST /api/bots/{id}/contacts/tag	Tag a subscriber `{cid, tag, action}`
POST /api/bots/{id}/contacts/bulk-tag	Bulk tag assignment
GET /api/bots/{id}/contacts/export	Export subscribers to CSV
GET/POST /api/bots/{id}/deals · DELETE …/deals/{did}	Mini-CRM: deals
GET/POST /api/bots/{id}/products · DELETE …/products/{pid}	Product catalog

AI & knowledge base

Method and path	Description
GET/PUT /api/bots/{id}/ai	Bot AI provider `{provider, api_key, model}`
GET/POST /api/bots/{id}/knowledge · DELETE …/knowledge/{doc_id}	Knowledge base (RAG) `{title, text}`
POST /api/bots/{id}/knowledge/reindex	Vector reindex of the knowledge base
GET/PUT /api/bots/{id}/provider/{name}	Integrations: bitrix, amocrm, sheets, yookassa, sms

Analytics

Method and path	Description
GET /api/bots/{id}/stats	Dialogs, messages, conversion
GET /api/bots/{id}/radar	Traffic sources (by `?start=`)

Inbox (dialogs & agent)

Method and path	Description
GET /api/inbox?filter=	Dialogs: waiting \| active \| mine \| closed
GET /api/inbox/counts	Tab counters
GET /api/inbox/{id}/{sid}/messages	Dialog messages
POST /api/inbox/{id}/{sid}/reply	Agent reply `{text}`
POST /api/inbox/{id}/{sid}/assign	Assign a dialog to yourself/an agent
POST /api/inbox/{id}/{sid}/status	Dialog status `{status}` (incl. closed)
POST /api/inbox/{id}/{sid}/note	Internal agent note

Organizations, projects & access

Hierarchy: workspace → organization → project → bot. Plan and limits are per workspace (shared pool). A workspace has a default organization and project, so a solo user never notices them. Roles (inherited top-down, apply at their level and below): admin — full access, editor — edits bots, operator — replies in dialogs only, billing — payments only (workspace level only). Access is granted at any level; external collaborators can be invited to a single project.

Method and path	Description
GET /api/orgs	Workspace organizations with their projects
POST /api/orgs	Create an organization `{name}`
PUT /api/orgs/{id} · DELETE /api/orgs/{id}	Rename / delete an organization (empty)
POST /api/projects	Create a project `{org_id, name}`
PUT /api/projects/{id} · DELETE /api/projects/{id}	Rename / delete a project (empty)
PUT /api/bots/{id}/move	Move a bot to a project `{project_id}`
GET /api/access?scope_type=tenant\|org\|project&scope_id=	Who has access at a level
POST /api/access	Grant access `{scope_type, scope_id, email, role}` (a new email gets an account + invite email)
DELETE /api/access	Revoke access `{scope_type, scope_id, email}`

Workspace: plan, payer, keys

Method and path	Description
GET /api/billing	Plan, limits, usage, payer (`payer_email`), payment methods (`psps`)
GET /api/billing/payments	Payment history
POST /api/billing/payer	Set the workspace payer `{email}`
GET /api/keys	Workspace API keys

Plan, limits and payments are per workspace (like the API key). The payer pays (the creator by default, reassignable by a tenant admin); prices are multi-currency (RUB/KZT/USD/EUR — the amount is taken by the chosen payment method). Team members are managed via /api/access (scope_type=tenant), roles admin/editor/operator/billing. One key = one workspace.

4. Bot graph schema

A flow is states (nodes) and transitions (edges). A minimal bot:

{
  "states": [
    {"id":"start","type":"start","label":"Start","config":{},"position":{"x":80,"y":80}},
    {"id":"hello","type":"message","label":"Hi","config":{"text":"Hello! How can I help?"},"position":{"x":80,"y":220}}
  ],
  "transitions": [
    {"id":"t1","from":"start","to":"hello","type":"goto","condition":null}
  ]
}

Main node types (type) and their config:

type	config	Purpose
`start`	—	Entry point
`trigger`	`{event, keywords, match}`	Start a branch by keyword or on a new subscriber (subscribe)
`message`	`{text, media_url?, buttons?}`	Send a message (buttons via `on_button` transitions)
`input`	`{var}`	Wait for a reply, save it to a variable
`condition`	`{var, op, value}`	Branching (`on_condition` transitions with `result:true/false`)
`set_var`	`{var, value}`	Set a variable
`api_call`	`{url, method, body, save_to}`	HTTP request to an external service
`ai`	`{prompt, use_kb, save_to, task}`	AI answer from the knowledge base
`tag`	`{action, tag}`	Add/remove a subscriber tag
`set_field`	`{field, value}`	Set a custom subscriber field
`payment`	`{provider, amount, ...}`	Payment: YooKassa (link) or Telegram Stars (in chat)
`bitrix` / `amocrm` / `sheets`	`{fields}` / `{columns}`	Send data to Bitrix24 / amoCRM / Google Sheets
`handoff`	—	Hand off to an agent (in the inbox)

Tip: fetch a ready bot's graph via GET /api/bots/{id} — it's the best example of the format to edit.

5. Outgoing webhooks (bot events)

The platform can notify your server about bot events. Setup:

curl -X PUT https://ultrabot.work/api/bots/BOT_ID/webhook-out \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"url":"https://your.app/hook","events":{"subscribe":true,"handoff":true,"deal":true,"payment":true}}'

Each event is toggled by a true/false flag. On an event the platform sends a POST to your url (10s timeout, redirects not followed, no retries — keep the handler fast and idempotent). The body always has the shape {event, bot_id, data}:

{"event":"subscribe","bot_id":"bot_ab12…","data":{"chat_id":123,"name":"John","channel":"telegram"}}

event	When	data
`subscribe`	New subscriber	`{"chat_id":123,"name":"John","channel":"telegram"}`
`handoff`	Dialog handed to an agent (handoff node)	chat_id as a number, e.g. `123`
`deal`	Deal created (deal node)	`{"title":"Order","amount":1990,"stage":"new"}`
`payment`	Successful in-bot payment (Telegram payment)	`{"chat_id":123,"payload":"invoice payload"}`

6. Integration examples

Create a broadcast (tag segment, push or email channel):

curl -X POST https://ultrabot.work/api/bots/BOT_ID/broadcasts \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"text":"Sale!","filter_tag":"vip","channel":"push"}'

Optional: buttons, subject (for email), scheduled_at (ISO time), repeat_days, filter_var/filter_value, delay_seconds.

Tag a contact (action: add | remove):

curl -X POST https://ultrabot.work/api/bots/BOT_ID/contacts/tag \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"cid":"CHAT_ID","tag":"vip","action":"add"}'

Inbox: list waiting dialogs and reply as an agent:

curl "https://ultrabot.work/api/inbox?filter=waiting" -H "Authorization: Bearer $KEY"
curl -X POST https://ultrabot.work/api/inbox/BOT_ID/SID/reply \
  -H "Authorization: Bearer $KEY" -H "content-type: application/json" \
  -d '{"text":"Hello!"}'

Workspace plan and limits:

curl https://ultrabot.work/api/billing -H "Authorization: Bearer $KEY"
# → {"plan":"pro","limits":{"max_bots":10,"max_broadcasts_month":100,"max_contacts":10000},
#     "usage":{...},"payer_email":"...","psps":["robokassa"]}

7. AI integration (MCP)

Through the Model Context Protocol an AI gets tools that call this API with your key — and can create/configure bots, run the inbox and more on its own. Two options:

Option A — remote MCP (no install)

Just add the server by URL. For Claude Desktop / clients with remote MCP:

{
  "mcpServers": {
    "ultrabot": {
      "url": "https://ultrabot.work/mcp",
      "headers": { "Authorization": "Bearer bs_live_YOUR_KEY" }
    }
  }
}

Option B — local server (stdio)

For Claude Desktop / Claude Code that need a local process:

{
  "mcpServers": {
    "ultrabot": {
      "command": "npx",
      "args": ["-y", "@ultrabot/mcp"],
      "env": {
        "ULTRABOT_API_KEY": "bs_live_YOUR_KEY",
        "ULTRABOT_BASE_URL": "https://ultrabot.work"
      }
    }
  }
}

Available tools: list_bots, create_bot, get_bot, rename_bot, delete_bot, list_archived_bots, restore_bot, purge_bot, update_graph, publish_bot, bot_overview, bot_stats, connect_telegram, set_channel, create_broadcast, list_dialogs, dialog_messages, reply_dialog, set_ai, add_knowledge, list_contacts, tag_contact, set_commands, billing_status.

Example user prompt: "Build an autoresponder bot for barbershop bookings, connect my Telegram and publish" — the AI will call create_bot → update_graph → connect_telegram → publish_bot.

Get a key and start

Keys live in the app under "Settings → API".

Open the app