Центр допомоги
Chat API

Bot Talk API

Останнє оновлення:

Bot Talk API

Bot Talk API - це REST API для спілкування з конкретним чатботом із вашого власного застосунку: кастомних додатків, внутрішніх інструментів або створених вами автоматизацій. Ви створюєте ключ API на вкладці бота API, після чого викликаєте кінцеву точку чату, передаючи ключ як Bearer-токен, щоб отримувати відповіді бота у вигляді окремої відповіді або потоком через SSE.

Початок роботи

  1. Виберіть свого чатбота та перейдіть на вкладку API у верхній частині сторінки бота (Select Bot > API [Виберіть бота > API]).

Вкладка Bot Talk API

  1. Натисніть Create API Key (Створити ключ API).

Вкладка API виділена; кнопка Create API Key розміщена у вмісті сторінки

Лічильник поруч із кнопкою показує кількість активних ключів ("1 of 5 API keys active"). Посилання View API Documentation (Переглянути документацію API) відкриває цей довідник, а фрагмент curl у Quick Start (Швидкий старт) містить готовий до виконання приклад.

  1. У діалоговому вікні Create API Key (Створити ключ API) вкажіть назву ключа, за потреби задайте білий список IP-адрес і ліміт запитів, виберіть потрібні дозволи та натисніть Create (Створити).

Діалогове вікно створення ключа API

  1. Скопіюйте повний ключ із вікна успішного створення. Відкритий текст показується лише один раз.

Ключ виглядає як ck_abcdefghijklmnopqrstuvwxyz012345. Кожен ключ належить саме цьому боту, тому кожен запит із цим ключем звертається до цього бота - бот ідентифікується за ключем і ніколи не з'являється в URL.

  1. На своєму сервері виконайте наведений нижче приклад curl із вашим ключем і коротким тестовим повідомленням. Збережіть повернутий conversationId, а потім використайте його повторно для наступного повідомлення. Перевірте відповідь і розмову на вкладці бота Chatlogs (Історія чату).

Зберігайте ключі ck_ на своєму сервері, а не в JavaScript сайту чи збірках мобільних застосунків. Дозвіл Conversations надає доступ до збережених розмов цього бота з усіма відвідувачами, тому ваш застосунок повинен авторизувати кожного кінцевого користувача, перш ніж повертати ці дані. Щоб відкликати ключ, скористайтеся діями Revoke (Відкликати) або Delete (Видалити) на вкладці API; жодна з цих дій не покаже відкритий текст ключа знову.

Перш ніж почати, створіть і навчіть свого чатбота та переконайтеся, що ваш обліковий запис включає доступ до API й має кредити на повідомлення.

Базовий URL

https://api.chatlab.com/aichat

Усі кінцеві точки в цій статті наведені відносно цього базового URL.

Дозволи ключів

Кожен ключ має один або обидва зазначені дозволи, які налаштовуються перемикачами у діалоговому вікні Create API Key:

  • Chat (send messages and receive responses) - дозволяє використовувати кінцеві точки /v1/chat та /v1/chat/stream.
  • Conversation history (list and read past conversations) - дозволяє використовувати кінцеві точки /v1/conversations.

На вкладці API надані кожному ключу дозволи відображаються у вигляді бейджів Chat та Conversations.

Автентифікація

Передавайте ключ у заголовку Authorization у кожному запиті:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Запити без заголовка Authorization: Bearer ... повертають помилку 401 missing_api_key. Невідомі ключі повертають 401 invalid_api_key; відкликані ключі повертають 401 revoked_api_key. П'ять невдалих спроб за хвилину з однієї IP-адреси спричиняють блокування на 60 хвилин.

Ліміти

  • Не більше 5 активних ключів Bot Talk на одного бота
  • До 60 запитів на хвилину на один ключ (алгоритм token bucket, місткість 60, плавне поповнення зі швидкістю 1 токен на секунду). Значення можна зменшити під час створення - встановіть нижчий параметр rateLimitPerMinute, і ліміт знизиться, а швидкість поповнення пропорційно зміниться.
  • Максимальна довжина повідомлення - 4000 символів
  • Кількість одночасних потоків SSE на один ключ регулюється лімітами вашого облікового запису

Кінцеві точки

POST /v1/chat

Надіслати повідомлення боту й отримати повну відповідь у єдиному об'єкті JSON.

Тіло запиту

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - обов'язковий рядок, не більше 4000 символів.
  • conversationId - необов'язковий UUID. Пропустіть його для нової розмови або використайте значення, яке сервер повернув раніше, щоб продовжити наявну.
  • metadata - необов'язковий об'єкт, який приймає {source, userName, userEmail, userPhone}. Наразі тут використовується лише userEmail для визначення ідентифікатора клієнта; каналом фіксується API. Не розраховуйте на те, що інші поля metadata будуть збережені в записі ліда.

Тіло відповіді (200)

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "5.6-LUNA",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role завжди має значення "assistant"; message.content містить повну відповідь.
  • model - ідентифікатор моделі, на якій працював бот під час цього виклику.
  • usage.creditsUsed зараз фіксує 2 плюс одиницю за кожен зафіксований виклик інструмента за завершений цикл діалогу. Цей лічильник у відповіді не враховує множники кредитів для моделей/контексту і не повинен використовуватися як бухгалтерський реєстр білінгу. Для перевірки споживання облікового запису використовуйте статистику Management API та перегляньте кредити на повідомлення.
  • actions містить список викликів інструментів, виконаних під час цього циклу. Наразі повертаються лише записи function_call (із полями type, name, status: "completed").

POST /v1/chat/stream

Варіант /v1/chat у вигляді потоку. Повертає Content-Type: text/event-stream через Server-Sent Events.

Тіло запиту

Така сама структура, як і в POST /v1/chat. Прапорець stream у тілі запиту не потрібен - SSE активується використанням саме цього шляху.

Тіло відповіді (події SSE)

  • message.reset - скинути накопичений для поточної відповіді текст і почати збір фрагментів наново. Це може статися під час перезапуску генерації; об'єднання обох версій призвело б до показу продубльованої або застарілої відповіді.
  • message.delta - фрагмент вмісту { "content": "..." }. Кілька таких подій надходять у міру прибуття токенів.
  • action - виконання інструмента { "type", "name", "status": "executing" }. Відправляється, коли бот ініціює виклик функції.
  • message.done - фінальна подія з полями conversationId, model, usage та (за наявності) списком завершених дій actions.
  • error - надсилається в разі помилки генерації; після цього потік завершується.

Під час тривалої генерації кожні 15 секунд надсилаються коментарі SSE для підтримки з'єднання (:keepalive). Таймаути на стороні сервера: 30 секунд для першого токена, 120 секунд загалом на один потік.

Приклад curl

curl -N -X POST https://api.chatlab.com/aichat/v1/chat/stream \
  -H "Authorization: Bearer ck_..." \
  -H "Content-Type: application/json" \
  -d '{"message":"hello"}'

GET /v1/conversations

Список розмов бота, прив'язаного до вашого ключа, з усіх джерел (віджет, WhatsApp, API тощо).

Параметри запиту

  • limit - 1-100, за замовчуванням 20. Значення за межами цього діапазону обмежуються граничними.
  • cursor - непрозоре значення, повернене в nextCursor на попередній сторінці. Для першої сторінки залиште порожнім.

Тіло відповіді (200)

{
  "data": [
    {
      "conversationId": "550e8400-e29b-41d4-a716-446655440000",
      "createdAt": "2026-05-10T14:11:02Z",
      "lastMessageAt": "2026-05-10T14:12:34Z",
      "messageCount": 6,
      "lastMessagePreview": "Thanks for the help."
    }
  ],
  "hasMore": false,
  "nextCursor": null
}
  • lastMessagePreview обрізається до 100 символів із додаванням ... наприкінці.
  • nextCursor має значення null на останній сторінці; передайте його як cursor, щоб отримати наступну.

GET /v1/conversations/{conversation_id}

Збережені повідомлення розмови, які надає ця кінцева точка.

Тіло відповіді (200)

{
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "createdAt": "2026-05-10T14:11:02Z",
  "lastMessageAt": "2026-05-10T14:12:34Z",
  "messageCount": 6,
  "messages": [
    {"role": "user", "content": "Hi", "createdAt": "2026-05-10T14:11:02Z"},
    {"role": "assistant", "content": "Hello! How can I help?", "createdAt": "2026-05-10T14:11:03Z"}
  ]
}

Повертаються лише ролі user та assistant; службові повідомлення system та повідомлення інструментів відфільтровуються. Повертає 404 not_found_error, якщо розмова не належить боту, прив'язаному до вашого ключа.

Щоб переглянути конфігурацію бота, скористайтеся кінцевою точкою Management API GET /v1/management/bots/{bot_id} із ключем Management.

Заголовки лімітів запитів

Відповіді, які доходять до етапу перевірки лімітів (тобто після успішної автентифікації та проходження білого списку IP), містять:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - ліміт для ключа, фактично застосований до цього виклику (60 за замовчуванням або вказаний вами rateLimitPerMinute, якщо він нижчий).
  • X-RateLimit-Remaining - кількість токенів, що залишилися в кошику одразу після цього виклику.
  • X-RateLimit-Reset - час у секундах за стандартом Unix epoch, коли стане доступним наступний токен (це не повне скидання ліміту; кошик поповнюється безперервно). Якщо кошик заповнений, показується поточний час.

У відповідях 429 rate_limit_exceeded також встановлюється заголовок Retry-After, де вказується кількість цілих секунд до моменту, коли звільниться хоча б один токен.

Помилки до проходження автентифікації (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) та 403 ip_not_whitelisted не містять заголовків X-RateLimit-* - механізм обмеження перевіряється лише після успішної автентифікації та перевірки IP.

Формат помилок

Усі помилки мають єдиний формат обгортки:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Типові коди HTTP:

  • 400 invalid_request_error - неправильно сформовані вхідні дані (invalid_parameter)
  • 415 invalid_request_error - непідтримуваний тип вмісту (unsupported_media_type)
  • 401 authentication_error - відсутній ключ (missing_api_key), невідомий ключ (invalid_api_key) або відкликаний ключ (revoked_api_key)
  • 402 quota_exceeded_error - вичерпано кредити на повідомлення
  • 403 permission_error - IP заблоковано (ip_blocked), IP відсутня в білому списку ключа (ip_not_whitelisted) або тип ключа не дозволяє доступ до цієї кінцевої точки (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - розмова не належить цьому боту
  • 405 invalid_request_error (method_not_allowed) - неправильний HTTP-метод для цього URL
  • 429 rate_limit_error - забагато запитів (rate_limit_exceeded) або забагато одночасних потоків (concurrent_streams_exceeded)
  • 500 api_error - внутрішня помилка сервера

Пов'язані статті

Інформацію про операції на рівні облікового запису (створення ботів, оновлення ботів, перевірка використання) див. у статті Management API.

Шукати серед усіх статейЗапитати агента