--- id: "faq-10076" type: "faq" lang: "ru" title: "Как работает публичный API Binom Ai?" url: "https://binomai.com/ru/faq/kak-rabotaet-binom-ai-public-api/" translation_group: "faq-10071" translations: en: url: "https://binomai.com/faq/how-does-the-binom-ai-public-api-work/" markdown: "https://binomai.com/ai/en/faq/how-does-the-binom-ai-public-api-work.md" uk: url: "https://binomai.com/ua/faq/yak-pratsiuie-binom-ai-public-api/" markdown: "https://binomai.com/ai/ua/faq/yak-pratsiuie-binom-ai-public-api.md" published: "2026-08-15T23:17:18Z" updated: "2026-10-19T11:58:27Z" --- # Как работает публичный API Binom Ai? *Обновлено: 19.10.2026, 11:58 UTC* --- Публичный API Binom Ai - это способ подключить синтетического сотрудника от BINOMAI.com к своему сайту, приложению, CRM или другой системе: вы отправляете сообщение клиента через запрос к API и сразу получаете готовый ответ синтетического сотрудника. [Подробнее для разработчика](https://binomai.com/faq/binom-ai-public-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](mailto:support@binomai.com). --- ## Обновлено от 19.10.26 Публичный API Binom Ai - это способ подключить синтетического сотрудника от BINOMAI.com к своему сайту, приложению, CRM или другой системе: вы отправляете сообщение клиента через запрос к API и сразу получаете готовый ответ синтетического сотрудника. [Подробнее для разработчика](https://binomai.com/faq/binom-ai-public-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`) и ряд других отраслевых сценариев (`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](mailto:support@binomai.com). ## Как подключить API в кабинете 1. Откройте [Интеграции](https://app.binomai.com/cabinet/binom/integrations) → вкладка API ("Интеграция API"). 2. Нажмите "Подключить" и подтвердите. 3. Появится "API подключён!" и блок "Как пользоваться API:" с ключом. "Доступ к API применяется только к этому Binom. Храните ключ API в безопасности". 4. Чтобы отключить, нажмите "Отключить интеграцию по API". Если вкладка показывает "Ограничения тарифа" - "Интеграция по API доступна на старших тарифах", состав тарифов - на странице [тарифы и цены](https://binomai.com/ru/pricing/). ## Как ещё спрашивают ### Есть ли у чат-бота API? Да, публичный API подключается в [Интеграциях](https://app.binomai.com/cabinet/binom/integrations) → API. ### Как передавать заказы и контакты в CRM? [Способы подключить CRM](https://binomai.com/ru/faq/kak-podklyuchit-crm/) - через API, Horoshop или каталог "Больше интеграций". ## Что дальше - [Как подключить CRM](https://binomai.com/ru/faq/kak-podklyuchit-crm/) - [Интеграция с CRM через API](https://binomai.com/ru/faq/kak-integrirovat-binom-ai-s-crm-sistemoj-cherez-api-dlya-avtomaticheskoj-peredachi-zakazov-i-kontaktnyh-dannyh/)