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

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

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

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

  1. Изпълнете curl примера по-долу от Вашия сървър, като използвате Вашия ключ и кратко тестово съобщение. Запазете върнатия conversationId, след което го използвайте отново за следващо съобщение. Проверете отговора и разговора в раздела Chatlogs (История на разговорите) на бота.

Съхранявайте ключовете ck_ на Вашия сървър, а не в JavaScript кода на уебсайта или в пакетите на мобилни приложения. Разрешението Conversations дава достъп до съхранените разговори на този бот от всички посетители, затова Вашето приложение трябва задължително да оторизира всеки краен потребител, преди да му върне тези данни. Използвайте Revoke (Анулиране) или Delete (Изтриване) в раздела API, за да деактивирате ключ; нито едно от двете действия няма да покаже отново ключа в явен вид.

Преди да започнете, създайте и обучете Вашия чатбот и се уверете, че Вашият план включва достъп до API и разполагате с кредити за съобщения.

Базов 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, за да се извлече идентификаторът на клиента; каналът се записва като API. Не разчитайте останалите метаданни да бъдат запазени в запис за lead.

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

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

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

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

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

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

Списък с разговори за бота, обвързан с Вашия ключ, от всички източници (widget, 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)
  • 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.

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