Главная · Справка · API ЧБТ: диалоги, ответы и статус оператора

API ЧБТ: диалоги, ответы и статус оператора

У ЧБТ есть публичный REST API, и он нужен прежде всего helpdesk-системам: внешняя система читает диалоги и отвечает покупателю в тот же Telegram, MAX, ВКонтакте или виджет, откуда тот написал. В паре с ним работают вебхуки на события диалогов. API узкий: он про переписку, а не про сценарии, товары и заказы. Ниже — как получить токен, какие методы есть и чего пока нет.

Токен и лимиты

Токен выдаёт владелец или администратор бота в разделе «Интеграции и API» → «Токены API»: достаточно подписать, кому он выдан, например «Омнидеск». Токен показывается один раз — мы храним только его отпечаток, поэтому потерянный токен не восстановить, только выдать новый и отозвать старый. Токен даёт доступ к диалогам одного бота; чужой и несуществующий диалог отвечают одинаково — 404.

Токен передаётся только в заголовке Authorization: Bearer <токен>, в адресе запроса он не принимается. Лимит — 120 запросов в минуту на токен, при превышении — 429. Ответы — JSON, ошибки приходят как {"ok": false, "error": "код", "message": "текст"}: код читает программа, текст — ваша поддержка.

Методы

Все пути — от адреса https://app.chbt.io/api/v1.

GET /conversations — диалоги бота от свежих к старым, по 50 (до 200 через limit); фильтр status — bot, ai, inbox, closed; следующая страница — по nextCursor.
GET /conversations/:id/messages — история диалога по порядку, со статусом доставки ответов.
POST /conversations/:id/messages — ответ покупателю: {"text": "…"} до 4000 знаков. Уходит в канал покупателя как ответ оператора, диалог переходит из-под бота к человеку. В закрытый диалог не отправляется — сначала /handoff.
POST /conversations/:id/close — закрыть диалог.
POST /conversations/:id/handoff — передать диалог человеку: бот замолкает.
POST /presence — сообщить, что оператор на смене: {"online": true, "ttl": 120}. Отметка живёт от 30 секунд до 15 минут и гаснет сама, если её не продлить; пока она горит, виджет показывает покупателю «оператор онлайн».
GET /presence — текущий статус: внешний и по операторам в «Диалогах».

Ответ через API не порождает вебхук message.outbound: внешняя система и так знает о своём сообщении, а иначе оператор увидел бы собственный ответ как новый.

Связка с helpdesk: вебхуки + API

В разделе «Интеграции и API» подпишите адрес helpdesk на события message.inbound и conversation.handoff — он узнает о новых сообщениях покупателя.
Выдайте токен и передайте его helpdesk: по нему он читает историю и отвечает методом POST /conversations/:id/messages.
Если операторы работают не в «Диалогах» ЧБТ, а у себя, пусть helpdesk продлевает /presence каждые минуту-две — тогда виджет на сайте честно показывает, что на смене живой человек.

Для Омнидеска это уже собрано: готовое подключение создаёт обращение, дописывает в него сообщения и возвращает ответы сотрудников в канал покупателя. Формат событий и проверка подписи — в справке по webhook, обзор всех связок — на странице интеграций.

Чего в API нет

Создавать или менять сценарии, каналы и контакты — только через кабинет.
Товаров, каталога и заказов — ни чтения, ни записи.
Начать переписку первым: API отвечает только в существующий диалог, а мессенджеры не дают боту писать тому, кто ему не писал.
Статистики и выгрузки контактов: база с тегами выгружается в CSV из «Контактов».
SDK и библиотек — только HTTP и JSON.

Внутри сценария остаются свои инструменты: действие «HTTP-запрос» отправляет данные в вашу систему и может показать клиенту её ответ, триггер «Входящий webhook» запускает сценарий по внешнему событию. Если нужного метода нет, напишите нам о своей задаче — это влияет на то, что появится дальше.

Частые вопросы

Где взять ключ API?
В разделе «Интеграции и API» бота, блок «Токены API». Выдать токен могут владелец и администратор бота. Токен показывается один раз; потерянный не восстановить — выдайте новый и отзовите старый.

Может ли внешняя система написать покупателю?
Да, в уже открытый диалог: POST /api/v1/conversations/:id/messages отправит текст в тот канал, из которого покупатель написал, и переведёт диалог к человеку. Начать переписку первым API не может.

Можно ли через API получить товары или заказы?
Нет. Публичный API работает только с диалогами и статусом оператора. Товары загружаются в кабинете: фидом магазина, файлом или по API Wildberries.

Нужен ли платный тариф для API?
Нет, вебхуки и API на тариф не проверяются. Ограничение Бесплатного тарифа — 30 диалогов в месяц.

Создать бота бесплатно

Справка по webhook Интеграции