Pagalbos centras
Chat API

Bot Talk API

Paskutinį kartą atnaujinta:

Bot Talk API

Bot Talk API yra REST API, skirtas bendrauti su konkrečiu pokalbių robotu tiesiai iš Jūsų programos - individualių sistemų, vidinių įrankių ar Jūsų sukurtų automatizacijų. Sukuriate API raktą roboto skirtuke API, tada iškviečiate pokalbio galinį tašką (angl. endpoint) naudodami raktą kaip Bearer prieigos raktą, kad gautumėte roboto atsakymus kaip vieną atsaką arba srautu per SSE.

Darbo pradžia

  1. Pasirinkite savo pokalbių robotą ir eikite į skirtuką API roboto puslapio viršuje (Select Bot > API (Pasirinkti robotą > API)).

Bot Talk API skirtukas

  1. Spustelėkite Create API Key (Sukurti API raktą).

API skirtukas su paryškintu mygtuku Create API Key

Šalia mygtuko esantis skaitiklis rodo, kiek raktų yra aktyvūs („1 of 5 API keys active“). Nuoroda View API Documentation (Peržiūrėti API dokumentaciją) atidaro šį žinyną, o Quick Start (Greita pradžia) curl fragmentas pateikia paruoštą paleisti pavyzdį.

  1. Lange Create API Key suteikite raktui pavadinimą, pasirinktinai nustatykite leidžiamų IP adresų sąrašą (angl. IP whitelist) ir užklausų limitą (angl. rate limit), pasirinkite jam suteikiamas teises ir spustelėkite Create (Sukurti).

Langelis Create API Key

  1. Nukopijuokite visą raktą iš sėkmės lango. Paprastu tekstu raktas rodomas tik vieną kartą.

Raktas atrodo taip: ck_abcdefghijklmnopqrstuvwxyz012345. Kiekvienas raktas priklauso konkrečiam robotui, todėl kiekviena užklausa, atlikta su šiuo raktu, komunikuoja su tuo robotu - robotas identifikuojamas pagal raktą ir URL adrese niekada nepateikiamas.

Bazinis URL

https://api.chatlab.com/aichat

Visi šiame straipsnyje nurodyti galiniai taškai yra santykiniai šio bazinio URL atžvilgiu.

Rakto teisės

Kiekvienas raktas turi vieną arba abi šias teises, kurios nustatomos perjungikliais langelyje Create API Key:

  • Chat (send messages and receive responses) (Pokalbiai (siųsti žinutes ir gauti atsakymus)) - suteikia prieigą prie /v1/chat ir /v1/chat/stream galinių taškų.
  • Conversation history (list and read past conversations) (Pokalbių istorija (peržiūrėti sąrašą ir skaityti buvusius pokalbius)) - suteikia prieigą prie /v1/conversations galinių taškų.

Skirtuke API kiekvienam raktui suteiktos teisės rodomos kaip ženkliukai Chat ir Conversations.

Autentifikavimas

Kiekvienoje užklausoje pateikite raktą Authorization antraštėje:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Užklausos be Authorization: Bearer ... antraštės grąžina 401 missing_api_key. Nežinomi raktai grąžina 401 invalid_api_key; anuliuoti raktai grąžina 401 revoked_api_key. Penki neteisingi bandymai per minutę iš to paties IP adreso sukelia 60 minučių blokavimą.

Limitai

  • Ne daugiau kaip 5 aktyvūs Bot Talk raktai vienam robotui
  • Ne daugiau kaip 60 užklausų per minutę vienam raktui (angl. token bucket algoritmas, talpa 60, tolygus papildymas po 1 žetoną per sekundę). Kurdami galite nustatyti mažesnę reikšmę - nustačius mažesnį rateLimitPerMinute, viršutinė riba sumažėja, o papildymo greitis proporcingai perskaičiuojamas.
  • Maksimalus žinutės ilgis - 4000 simbolių
  • Lygiagrečių SSE srautų skaičius vienam raktui priklauso nuo Jūsų paskyros limitų

Galiniai taškai

POST /v1/chat

Išsiunčia žinutę robotui ir gauna pilną atsakymą viename JSON atsake.

Užklausos turinys (angl. request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - privaloma eilutė, daugiausia 4000 simbolių.
  • conversationId - neprivalomas UUID. Praleiskite naujam pokalbiui; pakartotinai naudokite serverio anksčiau grąžintą reikšmę, jei norite tęsti esamą.
  • metadata - neprivalomas objektas: {source, userName, userEmail, userPhone}. userEmail taip pat naudojamas vidiniam kliento ID išvesti.

Atsako turinys (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 visada yra "assistant"; message.content yra pilnas atsakymas.
  • model yra modelio identifikatorius, su kuriuo robotas apdorojo šį iškvietimą.
  • usage.creditsUsed apima vartotojo žinutę + roboto atsakymą (paprastai 2), taip pat po vieną papildomą kreditą už kiekvieną įvykdytą įrankio iškvietimą.
  • actions pateikia įrankių vykdymus, atliktus šio kreipimosi metu. Šiuo metu grąžinami tik function_call įrašai (su type, name, status: "completed").

POST /v1/chat/stream

Srautinis /v1/chat variantas. Grąžina Content-Type: text/event-stream su Server-Sent Events (SSE).

Užklausos turinys

Tokia pati struktūra kaip ir POST /v1/chat. Parametras stream užklausos turinyje nėra būtinas - būtent šio kelio naudojimas suaktyvina SSE.

Atsako turinys (SSE įvykiai)

  • message.delta - turinio fragmentas { "content": "..." }. Gaunant žetonus, perduodami keli tokie fragmentai.
  • action - įrankio vykdymas { "type", "name", "status": "executing" }. Siunčiamas, kai robotas inicijuoja funkcijos iškvietimą.
  • message.done - galutinis įvykis su conversationId, model, usage ir (jei yra) įvykdytų actions sąrašu.
  • error - siunčiamas nepavykus generavimui; po to srautas nutraukiamas.

Ilgų generavimų metu kas 15 sekundžių siunčiami ryšio palaikymo SSE komentarai (:keepalive). Serverio skirtieji laikai (angl. timeouts): 30 sekundžių pirmajam žetonui, iš viso 120 sekundžių vienam srautui.

Curl pavyzdys

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

Pateikia su Jūsų raktu susieto roboto pokalbių sąrašą iš visų šaltinių (valdiklio, WhatsApp, API ir kt.).

Užklausos parametrai (angl. query parameters)

  • limit - 1-100, numatytoji reikšmė 20. Reikšmės už šio rėžio ribų yra automatiškai pakoreguojamos.
  • cursor - nepermatoma reikšmė, grąžinta nextCursor lauke ankstesniame puslapyje. Praleiskite pirmajam puslapiui.

Atsako turinys (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 sutrumpinama iki 100 simbolių su galūne ....
  • nextCursor paskutiniame puslapyje yra null; perduokite jį kaip cursor, kad gautumėte kitą puslapį.

GET /v1/conversations/{conversation_id}

Visa pokalbio istorija.

Atsako turinys (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"}
  ]
}

Grąžinami tik user ir assistant vaidmenys; vidinės system ir įrankių žinutės yra išfiltruojamos. Grąžina 404 not_found_error, jei pokalbis nepriklauso robotui, susietam su Jūsų raktu.

Norėdami peržiūrėti roboto konfigūraciją, naudokite Management API galinį tašką GET /v1/management/bots/{bot_id} su Management raktu.

Užklausų ribojimo antraštės

Atsakuose, kurie pasiekia užklausų ribojimo etapą (t. y. autentifikavimas ir IP leidžiamųjų sąrašas sėkmingai praeiti), pateikiama:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - šiam iškvietimui faktiškai pritaikyta rakto riba (numatytoji - 60 arba Jūsų sukonfigūruotas rateLimitPerMinute, jei jis mažesnis).
  • X-RateLimit-Remaining - žetonų likutis krepšelyje iškart po šio iškvietimo.
  • X-RateLimit-Reset - Unix epochos sekundės, kada bus pasiekiamas kitas žetonas (tai nėra pilnas krepšelio atstatymas; krepšelis pildomas nuolatos). Kai krepšelis pilnas, tai yra dabartinis laikas.

429 rate_limit_exceeded atsakuose taip pat nustatoma Retry-After antraštė, išreikšta sveikomis sekundėmis, kol atsilaisvins bent vienas žetonas.

Iki autentifikavimo įvykusios klaidos (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ir 403 ip_not_whitelisted neturi X-RateLimit-* antraščių - ribotuvas tikrinamas tik sėkmingai atlikus autentifikavimą ir IP patikras.

Klaidų formatas

Visos klaidos pateikiamos bendru formatu:

{
  "error": {
    "type": "rate_limit_error",
    "code": "rate_limit_exceeded",
    "message": "Rate limit exceeded. Try again in 12 seconds.",
    "param": null
  }
}

Dažni HTTP kodai:

  • 400 invalid_request_error - netinkamai suformuota įvestis (kodai: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - trūksta rakto (missing_api_key), nežinomas raktas (invalid_api_key) arba anuliuotas raktas (revoked_api_key)
  • 402 quota_exceeded_error - išnaudoti žinučių kreditai
  • 403 permission_error - IP užblokuotas (ip_blocked), IP nėra rakto leidžiamųjų sąraše (ip_not_whitelisted) arba rakto tipas neleidžia naudoti šio galinio taško (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - pokalbis nepriklauso šiam robotui
  • 405 invalid_request_error (method_not_allowed) - netinkamas HTTP veiksmas nurodytam URL
  • 429 rate_limit_error - per daug užklausų (rate_limit_exceeded) arba per daug lygiagrečių srautų (concurrent_streams_exceeded)
  • 500 api_error - vidinė klaida

Susiję

Norėdami atlikti paskyros lygio operacijas (kurti robotus, atnaujinti robotus, gauti naudojimo statistiką), žiūrėkite Management API.

Ieškoti visuose straipsniuoseKlauskite asistento