Усі питання

Як налаштувати публічний API Binom Ai?

Оновлено 19 Жовтня, 2026 11 хвилин читання 27 / 69

Публічний 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.

Оновлено від 19.10.26

Публічний 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 перемкнути цей статус не можна.

Як надіслати повідомлення і отримати відповідь синтетичного співробітника?

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="Здравствуйте, подскажите цену на доставку"

У відповіді, окрім тексту відповіді (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.

Як підключити API в кабінеті

Відкрийте Інтеграції → вкладка API ("Інтеграція API").
Натисніть "Підключити" і підтвердьте.
З'явиться "API підключено!" і блок "Як користуватися API:" з ключем. "Доступ до API застосовується лише до цього Binom. Зберігайте ключ API в безпеці".
Щоб відключити, натисніть "Відключити інтеграцію по API".

Якщо вкладка показує "Обмеження тарифу" – "Інтеграція по API доступна на старших тарифах", склад тарифів – на сторінці тарифи та ціни.

Як ще запитують

Чи є в чат-бота API?

Так, публічний API підключається в Інтеграціях → API.

Як передавати замовлення та контакти в CRM?

Способи підключити CRM: через API, Horoshop або каталог "Більше інтеграцій".

Що далі

Стаття була корисною?

Оновлено 19 Жовтня, 2026