Як налаштувати публічний 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.
