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 pačių sukurtų automatizacijų. Sukuriate API raktą roboto skirtuke API, o tada kviečiate pokalbio galinį tašką naudodami šį raktą kaip „Bearer“ prieigos raktą (angl. token), kad gautumėte roboto atsakymus kaip vieną pranešimą 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ą).

Paryškintas API skirtukas; mygtukas Create API Key yra puslapio turinyje

Šalia mygtuko esantis skaitiklis rodo, kiek raktų šiuo metu 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“ pavyzdys pateikia paruoštą paleisti užklausą.

  1. Lange Create API Key suteikite raktui pavadinimą, pasirinktinai nustatykite leistinų IP adresų sąrašą (angl. whitelist) bei 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ėkmingo sukūrimo lango. Švarus tekstas rodomas tik vieną kartą.

Raktas atrodo taip: ck_abcdefghijklmnopqrstuvwxyz012345. Kiekvienas raktas priklauso konkrečiam robotui, todėl kiekviena užklausa su šiuo raktu bendrauja būtent su juo - robotas identifikuojamas pagal raktą ir URL adrese niekada nenurodomas.

  1. Iš savo serverio paleiskite žemiau pateiktą „curl“ pavyzdį su savo raktu ir trumpa bandomąja žinute. Išsisaugokite gautą conversationId, kad galėtumėte jį naudoti tolesniam pokalbiui tęsti. Atsakymą ir pokalbį galite patikrinti roboto skirtuke Chatlogs (Pokalbių žurnalai).

Laikykite ck_ raktus savo serveryje, o ne svetainės „JavaScript“ kode ar mobiliųjų programėlių paketuose. Teisė „Conversations“ suteikia prieigą prie visų šio roboto išsaugotų lankytojų pokalbių, todėl Jūsų programa privalo autorizuoti kiekvieną galutinį naudotoją prieš pateikdama šiuos duomenis. Norėdami panaikinti rakto galiojimą, API skirtuke naudokite Revoke (Panaikinti galiojimą) arba Delete (Ištrinti); nė vienas iš šių veiksmų daugiau neparodys slapto rakto teksto.

Prieš pradėdami, sukurkite ir apmokykite savo pokalbių robotą bei patikrinkite, ar Jūsų planui suteikta API prieiga ir ar turite pakankamai žinučių kreditų.

Bazinis URL

https://api.chatlab.com/aichat

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

Rakto teisės

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

  • Chat (send messages and receive responses) - leidžia pasiekti /v1/chat ir /v1/chat/stream galinius taškus.
  • Conversation history (list and read past conversations) - leidžia pasiekti /v1/conversations galinius taškus.

Skirtuke API kiekvieno rakto suteiktos teisės rodomos kaip Chat ir Conversations ženkliukai.

Autentifikavimas

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

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

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

Apribojimai

  • Daugiausia 5 aktyvūs „Bot Talk“ raktai vienam robotui
  • Daugiausia 60 užklausų per minutę vienam raktui (žetonų kibirėlis, talpa 60, tolygus pildymas po 1 žetoną per sekundę). Galima sumažinti kuriant raktą - nustatykite mažesnę rateLimitPerMinute reikšmę ir viršutinė riba sumažės, o pildymo greitis atitinkamai prisitaikys.
  • Didžiausias žinutės ilgis - 4000 simbolių
  • Lygiagrečių SSE srautų skaičius vienam raktui priklauso nuo Jūsų paskyros plano apribojimų

Galiniai taškai

POST /v1/chat

Išsiųskite žinutę robotui ir gaukite visą atsakymą viename JSON objekte.

Užklausos turinys (body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - privaloma eilutė, ne daugiau kaip 4000 simbolių.
  • conversationId - neprivalomas UUID. Praleiskite, jei pradedate naują pokalbį; pakartotinai naudokite anksčiau serverio grąžintą reikšmę, jei norite tęsti esamą pokalbį.
  • metadata - neprivalomas objektas, priimantis {source, userName, userEmail, userPhone}. Šiuo metu čia naudojamas tik userEmail, kad būtų nustatytas kliento identifikatorius; kanalas užregistruojamas kaip API. Nepasikliaukite tuo, kad kiti metaduomenų laukai bus išsaugoti potencialaus kliento (lead) įraše.

Atsakymo turinys (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 visada yra "assistant"; message.content yra pilnas atsakymo tekstas.
  • model yra modelio ID, kurį robotas naudojo šiam atsakymui generuoti.
  • usage.creditsUsed šiuo metu nurodo 2 kreditus ir po vieną papildomą už kiekvieną įvykdytą įrankio iškvietimą per šį žingsnį. Šis atsakymo skaitiklis neapima modelio / konteksto kreditų daugiklių ir negali būti naudojamas sąskaitų apskaitai. Paskyros suvartojimui tikrinti naudokite Management API sunaudojimą ir peržiūrėkite žinučių kreditus.
  • actions pateikia šiame žingsnyje atliktus įrankių veiksmus. Šiuo metu pateikiami 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 (body)

Tokia pati struktūra kaip ir POST /v1/chat. Lauko stream užklausos turinyje nurodyti nereikia - SSE inicijuoja pats šio kelio iškvietimas.

Atsakymo turinys (SSE įvykiai)

  • message.reset - anuliuoti esamam atsakymui surinktą tekstą ir pradėti kaupti fragmentus iš naujo. Tai gali nutikti, jei generavimas prasideda iš naujo; sujungus abi versijas, atsakymas dubliuotųsi arba liktų neaktualus tekstas.
  • message.delta - turinio fragmentas { "content": "..." }. Generuojant atsakymą, transliuojami keli tokie įvykiai, atitinkantys gaunamus žetonus.
  • action - įrankio vykdymas { "type", "name", "status": "executing" }. Išsiunčiamas, kai robotas aktyvuoja funkcijos iškvietimą.
  • message.done - galutinis įvykis, kuriame pateikiami conversationId, model, usage ir (jei buvo) įvykdytų actions sąrašas.
  • error - išsiunčiama, jei generavimas nepavyksta; po to srautas nutraukiamas.

Ilgo generavimo metu kas 15 sekundžių siunčiami ryšio palaikymo SSE komentarai (:keepalive). Serverio laukimo limitai (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 visus roboto, susieto su Jūsų raktu, pokalbius iš visų šaltinių (valdiklio, „WhatsApp“, API ir kt.).

Užklausos parametrai

  • limit - 1-100, numatytoji reikšmė 20. Reikšmės už šio rėžio ribų automatiškai priderinamos.
  • cursor - identifikatorius, grąžintas ankstesnio puslapio lauke nextCursor. Pirmam puslapiui praleiskite.

Atsakymo 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 yra sutrumpintas iki 100 simbolių su galūne ....
  • Paskutiniame puslapyje nextCursor reikšmė yra null; perduokite ją kaip cursor, kad gautumėte kitą puslapį.

GET /v1/conversations/{conversation_id}

Šis galinis taškas pateikia išsaugotas pokalbio žinutes.

Atsakymo 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ąžinamos tik user ir assistant rolių žinutės; vidiniai system pranešimai ir įrankių iškvietimai yra išfiltruojami. Jei pokalbis nepriklauso robotui, susietam su Jūsų raktu, grąžinama klaida 404 not_found_error.

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

Užklausų ribojimo antraštės

Atsakymuose, kurie pasiekia užklausų ribojimo etapą (t. y. sėkmingai praeina autentifikavimą ir IP sąrašo patikrą), pateikiamos šios antraštės:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - šiam iškvietimui faktiškai pritaikyta riba vienam raktui (pagal numatytuosius nustatymus 60, arba mažesnė, jei sukonfigūravote rateLimitPerMinute).
  • X-RateLimit-Remaining - likęs žetonų skaičius iškart po šio iškvietimo.
  • X-RateLimit-Reset - „Unix epoch“ laikas sekundėmis, kada taps prieinamas kitas žetonas (tai nėra pilnas limito atstatymas; rezervas pildomas nuolatos). Kai rezervas pilnas, čia rodomas dabartinis laikas.

Esant 429 rate_limit_exceeded atsakymams, taip pat nustatoma antraštė Retry-After, kurioje sveikomis sekundėmis nurodoma, kiek laiko liko palaukti, kol atsilaisvins bent vienas žetonas.

Klaidos prieš autentifikavimą (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ir 403 ip_not_whitelisted neturi X-RateLimit-* antraščių - limitų tikrinimas atliekamas tik po to, kai sėkmingai praeina autentifikavimas ir IP patikros.

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žniausi HTTP klaidų kodai:

  • 400 invalid_request_error - neteisingai suformuota užklausa (invalid_parameter)
  • 415 invalid_request_error - nepalaikomas turinio tipas (unsupported_media_type)
  • 401 authentication_error - trūksta rakto (missing_api_key), nežinomas raktas (invalid_api_key) arba panaikintas raktas (revoked_api_key)
  • 402 quota_exceeded_error - išnaudoti žinučių kreditai
  • 403 permission_error - IP užblokuotas (ip_blocked), IP nėra leistinų adresų 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 metodas nurodytam URL
  • 429 rate_limit_error - viršytas užklausų skaičius (rate_limit_exceeded) arba per daug lygiagrečių srautų (concurrent_streams_exceeded)
  • 500 api_error - vidinė serverio klaida

Susijęs turinys

Paskyros lygio operacijoms (robotų kūrimui, jų atnaujinimui, suvartojimo peržiūrai) skaitykite Management API.

Ieškoti visuose straipsniuoseKlauskite asistento