CHBT CHBT chatbot builder
Create a bot
Features
For sellers Shop in your bot AI sales assistant Wildberries Online store QR code for a package insert
Messengers Telegram MAX VK Chat on the site
Templates Plans Blog Help
Sign in Create a bot

Home · Help · CHBT API: conversations, replies and operator status

CHBT API: conversations, replies and operator status

CHBT has a public REST API, and it’s mainly for helpdesk systems: an external system reads conversations and replies to the customer in the same Telegram, MAX, VK, or widget chat they wrote from. Webhooks for conversation events work alongside it. The API is narrow: it covers messaging, not flows, products, or orders. Below: how to get a token, which methods are available, and what isn’t there yet.

Token and limits

Tokens are issued by the bot’s owner or administrator in “Integrations and APIs” → “API tokens”: just note who the token is for, for example “Omnidesk.” The token is shown only once — we store only its fingerprint, so a lost token can’t be recovered; you can only issue a new one and revoke the old one. A token gives access to the conversations of one bot; someone else’s conversation and a nonexistent one get the same response — 404.

The token is passed only in the Authorization: Bearer <token> header; it isn’t accepted in the request URL. The limit is 120 requests per minute per token; above that, you get 429. Responses are JSON, and errors come as {"ok": false, "error": "code", "message": "text"}: the code is for your software, the text is for your support team.

Methods

All paths are relative to https://app.chbt.io/api/v1.

  • GET /conversations — the bot’s conversations from newest to oldest, 50 per page (up to 200 with limit); the status filter takes bot, ai, inbox, closed; get the next page with nextCursor.
  • GET /conversations/:id/messages — the conversation history in order, with the delivery status of replies.
  • POST /conversations/:id/messages — reply to the customer: {"text": "…"}, up to 4,000 characters. The reply goes to the customer’s channel as an operator reply, and the conversation passes from the bot to a person. It can’t be sent to a closed conversation — call /handoff first.
  • POST /conversations/:id/close — close the conversation.
  • POST /conversations/:id/handoff — hand the conversation over to a person: the bot goes silent.
  • POST /presence — report that an operator is on shift: {"online": true, "ttl": 120}. The flag lasts from 30 seconds to 15 minutes and expires on its own unless renewed; while it’s active, the widget shows the customer “operator online”.
  • GET /presence — the current status: external and per operator in “Conversations”.

A reply sent through the API doesn’t trigger the message.outbound webhook: the external system already knows about its own message, and otherwise the operator would see their own reply as a new one.

Helpdesk integration: webhooks + API

  1. In the “Integrations and APIs” section, subscribe the helpdesk URL to the message.inbound and conversation.handoff events — that's how it learns about new customer messages.
  2. Issue a token and give it to the helpdesk: with it, the helpdesk reads the history and replies using POST /conversations/:id/messages.
  3. If your operators work in their own system rather than in CHBT's “Conversations”, have the helpdesk renew /presence every minute or two — then the website widget accurately shows that a live person is on shift.

For Omnidesk, this is already built: the ready-made integration creates a ticket, appends messages to it, and sends staff replies back to the customer's channel. The event format and signature verification are described in the webhook help; an overview of all integrations is on the integrations page.

What the API doesn’t have

  • Creating or changing flows, channels, and contacts — only through the dashboard.
  • Products, catalog, and orders — neither reading nor writing.
  • Starting a conversation first: the API replies only in an existing conversation, and messengers don't let a bot message someone who hasn't messaged it.
  • Statistics and contact export: the contact list with tags is exported to CSV from “Contacts”.
  • SDKs and libraries — only HTTP and JSON.

Inside a flow, you still have its own tools: the “HTTP request” action sends data to your system and can show the customer its response, and the “Incoming webhook” trigger starts a flow on an external event. If the method you need isn't there, tell us about your use case — it influences what we build next.

FAQ

Where do I get an API key?
In the bot's “Integrations and APIs” section, in the “API tokens” block. The bot's owner and admins can issue a token. The token is shown only once; a lost token can't be recovered — issue a new one and revoke the old one.

Can an external system message a customer?
Yes, in a conversation that is already open: POST /api/v1/conversations/:id/messages sends the text to the channel the customer wrote from and hands the conversation over to a human. The API can’t start a conversation first.

Can I get products or orders through the API?
No. The public API works only with conversations and operator status. Products are uploaded in the dashboard: via a store feed, a file, or the Wildberries API.

Do I need a paid plan for the API?
No, webhooks and the API aren't restricted by plan. The Free plan's limit is 30 conversations per month.

Create a bot for free

Webhook helpIntegrations