---
id: "faq-10074"
type: "faq"
lang: "uk"
title: "Як налаштувати публічний API Binom Ai?"
url: "https://binomai.com/ua/faq/yak-pratsiuie-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"
  ru:
    url: "https://binomai.com/ru/faq/kak-rabotaet-binom-ai-public-api/"
    markdown: "https://binomai.com/ai/ru/faq/kak-rabotaet-binom-ai-public-api.md"
published: "2026-08-15T23:16:28Z"
updated: "2026-10-19T21:50:56Z"
---

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

*Оновлено: 19.10.2026, 21:50 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/ua/faq/kak-podklyuchit-crm/): через API, Horoshop або каталог "Більше інтеграцій".

## Що далі

- [Як підключити CRM](https://binomai.com/ua/faq/kak-podklyuchit-crm/)
- [Інтеграція з CRM через API](https://binomai.com/ua/faq/kak-integrirovat-binom-ai-s-crm-sistemoj-cherez-api-dlya-avtomaticheskoj-peredachi-zakazov-i-kontaktnyh-dannyh/)