Помощен център
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 адреси (IP whitelist) и лимит на заявките (rate limit), изберете какви разрешения да има той и след това кликнете върху Create (Създаване).

Диалогов прозорец Create API Key

  1. Копирайте пълния ключ от диалоговия прозорец за успех. Неговият чист текст се показва само веднъж.

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

Базов URL (Base 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.

Удостоверяване (Authentication)

Изпращайте ключа в заглавната част 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 потоци за един ключ зависят от лимитите на Вашия акаунт

Крайни точки (Endpoints)

POST /v1/chat

Изпращане на съобщение до бота и получаване на пълния отговор в един JSON отговор.

Тяло на заявката (Request body)

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

Тяло на отговора (Response body) (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), плюс един допълнителен кредит за всяко изпълнено извикване на инструмент (tool call).
  • actions изброява изпълнените инструменти по време на този ход. Към момента се генерират само записи от тип function_call (с type, name, status: "completed").

POST /v1/chat/stream

Вариант на /v1/chat с поточно предаване. Връща Content-Type: text/event-stream със Server-Sent Events.

Тяло на заявката (Request body)

Същата структура като при POST /v1/chat. Флагът stream в тялото не е задължителен - самото използване на този път задейства SSE.

Тяло на отговора (SSE събития)

  • message.delta - фрагмент от съдържанието { "content": "..." }. Няколко такива се изпращат поточно с пристигането на токените.
  • action - изпълнение на инструмент { "type", "name", "status": "executing" }. Изпраща се, когато ботът задейства извикване на функция.
  • message.done - финално събитие с conversationId, model, usage и (ако има такива) списъка с изпълнените actions.
  • error - изпраща се, ако генерирането е неуспешно; след това потокът се прекъсва.

При по-продължителни генерирания на всеки 15 секунди се изпращат SSE коментари за поддържане на връзката (:keepalive). Сървърни лимити за изчакване (timeouts): 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 на предишната страница. Пропуснете го за първата страница.

Тяло на отговора (Response body) (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}

Пълна история на разговора.

Тяло на отговора (Response body) (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 headers)

Отговорите, които достигнат етапа на проверка на лимита на заявките (т.е. успешно преминати удостоверяване и списък с разрешени 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.

Търсене във всички статииПопитайте асистента