Центр помощи
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-адресов и ограничение частоты запросов, выберите разрешения для ключа и нажмите Create (Создать).

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

  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. Не рассчитывайте на то, что другие поля метаданных сохранятся в записи лида.

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

Комментарии 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 - непрозрачное значение, возвращенное в поле 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.

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