Центр помощи
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 укажите имя ключа, при необходимости настройте белый список 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 - отправляется при сбое генерации; после этого поток закрывается.

Во время длительной генерации каждые 15 секунд отправляются keep-alive комментарии 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 и т. д.).

Параметры запроса (query parameters)

  • 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.

Заголовки ограничения частоты запросов (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 seconds, когда станет доступен следующий токен (это не время полного сброса корзины; корзина пополняется непрерывно). Когда корзина заполнена, значение равно текущему времени.

При получении ответа 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.

Поиск по всем статьямСпросить агента