Как работает публичный API Binom Ai?
Публичный API Binom Ai – это способ подключить синтетического сотрудника от BINOMAI.com к своему сайту, приложению, CRM или другой системе: вы отправляете сообщение клиента через запрос к API и сразу получаете готовый ответ синтетического сотрудника. Подробнее для разработчика
Как создать чат?
Отправьте запрос:
POST https://prod-api.binomai.com/api/public/chats
В теле запроса передайте свой собственный ID чата (например, ID заказа или диалога в вашей системе) в поле chat_id:
curl https://prod-api.binomai.com/api/public/chats \
-u YOUR_API_KEY: \
-d chat_id="order_12345"
Это же значение, которое вы передали, вернётся в ответе как integration_chat_id – и именно его нужно использовать во всех дальнейших запросах.
Важный нюанс по ID: в ответе на создание чата вернутся три разных ID – не перепутайте их:
| Поле | Что это | Используется ли в дальнейших запросах |
|---|---|---|
chat_id – то, что вы передали в запросе | Ваш собственный ID | – |
integration_chat_id – в ответе | Ровно то же значение, что вы передали | Да, именно это значение подставляется как {chat_id} в путь всех следующих запросов |
id – в ответе | Внутренний UUID, который генерирует BINOMAI.com | Не используется в публичном API |
Каждый чат также приходит с двумя статусами:
state– статус рассмотрения диалога:unreviewed(не просмотрен),reviewed(просмотрен),awaiting_operator(ожидает оператора).ai_state– активен ли синтетический сотрудник в этом чате:ai_active(отвечает автоматически) илиai_blocked(диалог забрал живой оператор – через кабинет, виджет или подключённый helpdesk; в этом состоянии сообщения клиента по-прежнему сохраняются, но автоматического ответа не будет). Через публичный API переключить этот статус нельзя.
Чат может приходить из разных каналов – это отражено в поле form: сайт (public_chat, widget), Telegram, Instagram, звонки (call), интеграция через API (api) и ряд других отраслевых сценариев (lawyer, tutor, interview и т.д.).
Как отправить сообщение и получить ответ синтетического сотрудника?
POST https://prod-api.binomai.com/api/public/chats/{chat_id}/messages
где {chat_id} – тот же ID, что вы указали при создании чата.
curl https://prod-api.binomai.com/api/public/chats/order_12345/messages \
-u YOUR_API_KEY: \
-d content="Здравствуйте, подскажите цену на доставку"
Ответ синтетического сотрудника приходит сразу же, в теле этого же запроса – ждать или дополнительно опрашивать API не нужно.
В ответе, помимо текста ответа (content), приходят: role (кто автор – user, assistant, system или operator), chat_id, ваш integration_message_id (если передавали), а также message_feedback – если на сообщение уже оставлена оценка (см. раздел про фидбек ниже). Поле contacts (контакты собеседника) в ответе на сообщение не возвращается – оно есть только у самого чата.
Как получить всю историю переписки?
GET https://prod-api.binomai.com/api/public/chats/{chat_id}/messages
Этот запрос возвращает весь диалог целиком – постраничная навигация (page/per) на историю сообщений не действует, сколько бы сообщений ни было.
Авторизация
Как авторизоваться в API?
Через HTTP Basic Auth: ваш API-ключ передаётся как username, поле password остаётся пустым.
Где взять API-ключ?
В личном кабинете BINOMAI.com: раздел "Интеграции организации" → тип API.
- Чтобы отозвать ключ – удалите соответствующую интеграцию.
- Чтобы перевыпустить ключ – создайте новую интеграцию типа API; старый ключ перестанет работать после удаления старой интеграции.
Голосовые сообщения и файлы
Можно ли отправлять голосовые сообщения?
Да. Для этого в поле content передайте значение [AUDIO], а сам аудиофайл приложите как обычный файл.
Как прикрепить файл к сообщению?
Есть два способа:
- По ссылке (
file_urls) – вы указываете URL файла, сервер BINOMAI.com сам скачивает его. - По ID уже загруженного файла (
files) – если файл уже был загружен заранее.
Можно использовать любой из вариантов или оба сразу.
Оценка ответов (фидбек)
Как клиент может оценить ответ синтетического сотрудника?
POST /api/public/chats/{chat_id}/messages/{id}/feedback
С параметрами state (like, dislike или remove – чтобы снять оценку) и comment (комментарий).
Комментарий обязателен только для like и dislike. Чтобы снять ранее поставленную оценку, комментарий не нужен – достаточно state="remove".
Лимиты и ошибки
Сколько сообщений можно отправлять?
- Не больше 10 сообщений в один чат за минуту – после этого чат временно блокируется на 10 минут.
- Не больше 100 запросов в минуту ко всему публичному API в целом (по всем чатам суммарно).
Что означают коды ошибок?
| Код | Что произошло |
|---|---|
| 401 | Неверный или отсутствующий API-ключ |
| 402 | Закончились доступные запросы к синтетическому сотруднику по вашему тарифу |
| 403 | Подписка не активна |
| 404 | Чат или сообщение не найдены |
| 429 | Превышен лимит запросов (см. выше) |
Как понять, что означает пришедшая ошибка в ответе?
Ошибка авторизации (401 при неверном ключе) приходит в формате:
{ "status": "error", "message": "Authentication failed" }
Все остальные ошибки – в формате:
{ "error": "текст ошибки" }
Жизненный цикл чата
Что будет, если клиент не ответил на сообщение?
Если в чат так и не пришло ни одного сообщения от пользователя – он автоматически удаляется через 3 часа.
А если переписка уже началась, но клиент долго не отвечает?
Чат, где уже была хотя бы одна переписка, не удаляется автоматически – он хранится сколько угодно. Для очень старых диалогов рекомендуем создавать новый чат на своей стороне (например, если клиент вернулся спустя месяц) – это не обязательное требование, а рекомендация для более точных ответов синтетического сотрудника, чтобы старый контекст не мешал новому разговору.
Работа с базой знаний (карточки)
Что такое "карточка" в BINOMAI.com?
Карточка – это сохранённая пара "вопрос-ответ" в базе знаний, которая формируется на основе диалогов с клиентами.
GET /api/public/cards
Какие бывают статусы у карточки?
| Статус | Значение |
|---|---|
waiting | Создана, ответа ещё нет |
in_progress | Идёт обработка |
answered | Ответ задан |
submitted | Принята в обработку |
consumed | Готова к использованию в базе знаний |
failed | Обработка не удалась |
Работа с прайс-листами
Как получить прайс-лист и список товаров в нём?
GET /api/public/price_lists
GET /api/public/price_lists/{id}
Список товаров возвращается прямо внутри ответа, в поле price_items – отдельного запроса для получения товаров делать не нужно.
⚠️ Постраничная навигация (per/page) работает только для списка всех прайс-листов (GET /price_lists) – у запроса одного конкретного прайс-листа по {id} параметров навигации нет.
Как понять, идёт ли ещё обработка прайс-листов?
В ответе на список прайс-листов есть поле parse_in_progress – оно указывает, идёт ли сейчас разбор (парсинг) прайс-листов. ⚠️ Точная логика этого поля уточняется у разработчиков.
Откуда берутся прайс-листы?
Источником может быть загруженный CSV-файл, либо внешний фид (rss, horoshop и аналогичные) – тогда в ответе будет заполнено поле url с адресом фида.
Какие данные хранятся по каждому товару?
Каждый товар в price_items содержит: название (title), бренд, категорию, описание, цену, ссылку на товар и на изображение, QR-код (qr_code_url/qr_link), а также key_params – ключевые параметры/слова, которые синтетический сотрудник сам выделяет из описания товара при обработке, чтобы точнее отвечать на вопросы по этому товару.
Нужен ли webhook?
Нет. Для публичного API отдельная настройка webhook не требуется – ответ синтетического сотрудника приходит сразу же в момент отправки сообщения, без необходимости получать уведомления отдельным способом.
Интеграции с конкретными платформами
Отдельные гайды по подключению BINOMAI.com к популярным системам (Shopify, AmoCRM, Syrve и другим) описывают, как связать сущности этих платформ (заказы, сделки, диалоги) с чатами и сообщениями BINOMAI.com. (Ссылки на такие гайды добавляются по мере готовности.)
Пути запросов, названия полей, коды ошибок и лимиты приведены точно как в API - при переносе на сайт менять их нельзя. Формулировки самих ответов можно адаптировать под тон сайта.
Contact
If you have any questions, please contact our support team – support@binomai.com.
