Центр допомоги
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-адрес і ліміт запитів (rate limit), виберіть дозволи для нього, а потім натисніть Create (Створити).

Діалогове вікно Create API Key

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

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

Базовий 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 також використовується для формування внутрішнього ідентифікатора клієнта.

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

{
  "message": {"role": "assistant", "content": "Sure, what's your order number?"},
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "model": "gpt-4o-mini",
  "usage": {"creditsUsed": 2},
  "actions": []
}
  • message.role завжди має значення "assistant"; message.content містить повний текст відповіді.
  • model - ідентифікатор моделі, на якій працював бот для цього виклику.
  • usage.creditsUsed враховує повідомлення користувача + відповідь бота (зазвичай 2), плюс один додатковий кредит за кожен виконаний виклик інструменту.
  • 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.delta - фрагмент вмісту { "content": "..." }. Передається послідовно в міру надходження токенів.
  • action - виклик інструменту { "type", "name", "status": "executing" }. Створюється, коли бот запускає виклик функції.
  • message.done - завершальна подія з полями conversationId, model, usage та (за наявності) списком завершених дій actions.
  • error - надсилається в разі помилки генерації; після цього потік завершується.

Коментарі keep-alive для SSE (:keepalive) надсилаються кожні 15 секунд під час тривалих генерацій. Таймаути на стороні сервера: 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 - непрозоре значення (opaque value), повернуте в полі 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.

Заголовки обмеження запитів (rate limit)

Відповіді, які дійшли до етапу перевірки лімітів (тобто автентифікація та перевірка 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, 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.

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