Abikeskus
Chat API

Bot Talk API

Viimati uuendatud:

Bot Talk API

Bot Talk API on REST API suhtlemiseks ühe konkreetse chatbotiga teie enda rakendusest - kohandatud rakendustest, sisekasutuse tööriistadest või teie enda loodud automatiseerimistest. Te loote API-võtme roboti vahekaardil API, seejärel kutsute välja vestluse lõpp-punkti, kasutades võtit Bearer-tokenina, et saada roboti vastused kas üksiku vastusena või SSE kaudu voogedastusena.

Alustamine

  1. Valige oma chatbot ja liikuge roboti lehe ülaosas olevale vahekaardile API (Select Bot > API (Vali robot > API)).

Bot Talk API vahekaart

  1. Klõpsake nupul Create API Key (Loo API-võti).

Esile tõstetud API vahekaart; Create API Key asub lehe sisus

Nupu kõrval olev loendur näitab, mitu võtit on aktiivsed ("1 of 5 API keys active"). Link View API Documentation (Vaata API dokumentatsiooni) avab käesoleva juhendi ja Quick Start (Kiirjuhend) curl-koodilõik annab teile kohe käivitatava näite.

  1. Dialoogiaknas Create API Key (Loo API-võti) sisestage võtmele nimi, soovi korral määrake lubatud IP-aadresside loend (IP whitelist) ja päringute piirmäär (rate limit), valige selle õigused ning klõpsake seejärel nupul Create (Loo).

Create API Key dialoogiaken

  1. Kopeerige täielik võti õnnestumise dialoogiaknast. Lihttekstina kuvatakse seda ainult üks kord.

Võti näeb välja selline: ck_abcdefghijklmnopqrstuvwxyz012345. Iga võti kuulub sellele ühele robotile, seega suhtleb iga selle võtmega tehtud päring just selle robotiga - robot tuvastatakse võtme järgi ja see ei ilmu kunagi URL-is.

  1. Käivitage oma serverist allpool olev curl-näide koos oma võtme ja lühikese testsõnumiga. Salvestage tagastatud conversationId, seejärel taaskasutage seda jätkusõnumi jaoks. Kinnitage vastus ja vestlus roboti vahekaardil Chatlogs (Vestluslogid).

Hoidke ck_-võtmeid oma serveris, mitte veebisaidi JavaScriptis ega mobiilirakenduste pakettides. Õigus Conversations annab juurdepääsu selle roboti säilitatud vestlustele kõigi külastajate lõikes, seega peab teie rakendus enne nende andmete tagastamist iga lõppkasutaja autoriseerima. Kasutage võtme kasutuselt kõrvaldamiseks vahekaardil API nuppu Revoke (Tühista) või Delete (Kustuta); kumbki toiming ei kuva selle lihtteksti enam uuesti.

Enne alustamist looge ja treenige oma chatbot ning veenduge, et teie kontol on API-juurdepääs ja sõnumikrediidid.

Baas-URL

https://api.chatlab.com/aichat

Kõik käesolevas artiklis olevad lõpp-punktid on selle baas-URL-i suhtes relatiivsed.

Võtme õigused

Igal võtmel on üks või mõlemad neist õigustest, mis määratakse lülititega dialoogiaknas Create API Key:

  • Chat (send messages and receive responses) - lubab lõpp-punktid /v1/chat ja /v1/chat/stream.
  • Conversation history (list and read past conversations) - lubab lõpp-punktid /v1/conversations.

Vahekaardil API kuvatakse iga võtme antud õigusi märgistena Chat ja Conversations.

Autentimine

Saatke võti igal päringul päises Authorization:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Päringud ilma päiseta Authorization: Bearer ... tagastavad vastuse 401 missing_api_key. Tundmatud võtmed tagastavad 401 invalid_api_key; tühistatud võtmed tagastavad 401 revoked_api_key. Viis kehtetut katset ühe minuti jooksul samalt IP-aadressilt käivitavad 60-minutilise blokeeringu.

Piirangud

  • Kuni 5 aktiivset Bot Talk võtit roboti kohta
  • Kuni 60 päringut minutis võtme kohta (token bucket, maht 60, sujuv täitmine kiirusega 1 token sekundis). Loomisel madalamaks konfigureeritav - määrake madalam rateLimitPerMinute ja ülemmäär langeb ning täitmiskiirus kohandub proportsionaalselt.
  • Sõnumi maksimaalne pikkus 4000 tähemärki
  • Samaaegsete SSE-voogude arv võtme kohta sõltub teie konto piirangutest

Lõpp-punktid

POST /v1/chat

Saatke robotile sõnum ja saage täielik vastus ühes JSON-vastuses.

Päringu keha

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - kohustuslik string, maksimaalselt 4000 tähemärki.
  • conversationId - valikuline UUID. Uue vestluse puhul jätke vahele; olemasolevale lisamiseks taaskasutage väärtust, mille server varem tagastas.
  • metadata - valikuline objekt, mis aktsepteerib väärtusi {source, userName, userEmail, userPhone}. Praegu kasutatakse siin ainult välja userEmail kliendi identifikaatori tuletamiseks; kanalina salvestatakse API. Ärge lootke teiste metaandmete väljade salvestamisele lead-kirjesse.

Vastuse keha (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 on alati "assistant"; message.content on täielik vastus.
  • model on mudeli ID, millel robot selle väljakutse ajal töötas.
  • usage.creditsUsed teatab praegu lõpetatud dialoogietapi (turn) eest 2 pluss ühe iga teatatud tööriistaväljakutse (tool call) kohta. See vastuseloendur ei sisalda mudeli/konteksti krediidikordajaid ja seda ei tohi kasutada arvelduslogina. Konto tarbimise jälgimiseks kasutage Management API kasutust ja vaadake artiklit sõnumikrediidid.
  • actions loetleb tööriistade käivitamised, mis selle etapi jooksul toimusid. Praegu väljastatakse ainult kirjeid function_call (väljadega type, name, status: "completed").

POST /v1/chat/stream

Lõpp-punkti /v1/chat voogedastusvariant. Tagastab Content-Type: text/event-stream koos Server-Sent Events (SSE) sündmustega.

Päringu keha

Sama struktuur nagu POST /v1/chat. Päringu kehas olev lipp stream ei ole vajalik - selle teekonna kasutamine käivitabki SSE.

Vastuse keha (SSE sündmused)

  • message.reset - loobuge praeguse vastuse jaoks kogutud tekstist ja alustage uuesti osade (deltade) kogumist. See võib juhtuda, kui genereerimine taaskäivitub; mõlema versiooni lisamine kuvaks duplikaadi või asendatud vastuse.
  • message.delta - sisufragment { "content": "..." }. Neid edastatakse voona mitu tükki vastavalt tokenite saabumisele.
  • action - tööriista käivitamine { "type", "name", "status": "executing" }. Väljastatakse siis, kui robot käivitab funktsiooniväljakutse.
  • message.done - lõppsündmus koos väljadega conversationId, model, usage ja (kui neid on) lõpetatud nimekirjaga actions.
  • error - saadetakse genereerimise ebaõnnestumisel; voog katkeb pärast seda.

Pikkade genereerimiste ajal saadetakse iga 15 sekundi järel ühenduse elushoidmise SSE-kommentaare (:keepalive). Serveripoolsed ajalõpud: 30 sekundit esimese tokeni jaoks, 120 sekundit voo kohta kokku.

Curl-näide

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

Kuvab teie võtmega seotud roboti vestluste loendi kõigist allikatest (vidin, WhatsApp, API jne).

Päringu parameetrid (query parameters)

  • limit - 1-100, vaikimisi 20. Vahemikust väljapoole jäävad väärtused piiratakse vahemiku piiridega.
  • cursor - läbipaistmatu väärtus, mis tagastati eelmise lehe väljal nextCursor. Esimese lehe puhul jätke vahele.

Vastuse keha (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 kärbitakse 100 tähemärgini koos järelliitega ....
  • nextCursor on viimasel lehel null; järgmise lehe toomiseks edastage see parameetrina cursor.

GET /v1/conversations/{conversation_id}

Selle lõpp-punkti kaudu kättesaadavad säilitatud vestlussõnumid.

Vastuse keha (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"}
  ]
}

Tagastatakse ainult rollid user ja assistant; süsteemisisesed system- ja tööriistasõnumid filtreeritakse välja. Tagastab veakoodi 404 not_found_error, kui vestlus ei kuulu teie võtmega seotud robotile.

Roboti konfiguratsiooni vaatamiseks kasutage Management API lõpp-punkti GET /v1/management/bots/{bot_id} koos Management-võtmega.

Päringupiirangu päised (rate limit headers)

Vastused, mis jõuavad päringupiirangu etapini (st autentimine ja IP lubatud loend on edukalt läbitud), sisaldavad järgmist:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - võtmepõhine ülempiir, mida selle väljakutse puhul tegelikult rakendati (vaikimisi 60 või teie konfigureeritud rateLimitPerMinute, kui see on madalam).
  • X-RateLimit-Remaining - tokenite arv, mis on mahutisse jäänud vahetult pärast seda väljakutset.
  • X-RateLimit-Reset - Unixi ajatempli sekundid, millal järgmine token kättesaadavaks muutub (mitte kogu mahuti lähtestamine; mahuti täitub pidevalt). Kui mahuti on täis, on see praegune kellaaeg.

Vastuste 429 rate_limit_exceeded puhul määratakse ka päis Retry-After, mis on väljendatud täissekundites kuni vähemalt ühe tokeni vabanemiseni.

Autentimiseelsed vead (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) ja 403 ip_not_whitelisted ei sisalda päiseid X-RateLimit-* - piirajat kontrollitakse alles pärast autentimise ja IP-kontrollide õnnestumist.

Vigade vorming

Kõik vead kasutavad ühte ja sama ümbrist:

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

Levinumad HTTP-koodid:

  • 400 invalid_request_error - vigane sisend (invalid_parameter)
  • 415 invalid_request_error - toetamata sisutüüp (unsupported_media_type)
  • 401 authentication_error - puuduv võti (missing_api_key), tundmatu võti (invalid_api_key) või tühistatud võti (revoked_api_key)
  • 402 quota_exceeded_error - sõnumikrediidid on otsas
  • 403 permission_error - IP on blokeeritud (ip_blocked), IP ei ole võtme lubatud loendis (ip_not_whitelisted) või võtme tüüp ei luba seda lõpp-punkti (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - vestlus ei kuulu sellele robotile
  • 405 invalid_request_error (method_not_allowed) - vale HTTP-meetod URL-il
  • 429 rate_limit_error - liiga palju päringuid (rate_limit_exceeded) või liiga palju samaaegseid vooge (concurrent_streams_exceeded)
  • 500 api_error - süsteemisisene viga

Seotud teemad

Konto tasemel toimingute jaoks (robotite loomine, robotite uuendamine, kasutusandmete toomine) vaadake juhendit Management API.

Otsige kõigist artiklitestKüsige agendilt