Abikeskus
Chat API

Bot Talk API

Viimati uuendatud:

Bot Talk API

Bot Talk API on REST API suhtlemiseks ühe konkreetse chatbotiga teie enda rakendusest - olgu selleks kohandatud rakendused, sisekasutuse tööriistad või teie enda loodud automatiseerimised. 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 vastuseid kas üksiku vastusena või voogesitatuna üle SSE.

Alustamine

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

Bot Talk API vahekaart

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

API vahekaart esiletõstetud nupuga Create API Key

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 (Kiiralustus) curl-koodilõik annab teile kohe käivitamiseks valmis näite.

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

Create API Key dialoogiaken

  1. Kopeerige täielik võti õnnestumise dialoogiaknast. Lihtteksti kuvatakse 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-i.

Baas-URL

https://api.chatlab.com/aichat

Kõik selles artiklis toodud lõpp-punktid on suhtelised selle baas-URL-i suhtes.

Võtme õigused

Iga võti kannab ühte või mõlemat järgmistest õigustest, mis määratakse lülititega dialoogiaknas Create API Key:

  • Chat (send messages and receive responses) (Vestlus (sõnumite saatmine ja vastuste saamine)) - lubab lõpp-punktid /v1/chat ja /v1/chat/stream.
  • Conversation history (list and read past conversations) (Vestluste ajalugu (varasemate vestluste loetlemine ja lugemine)) - lubab /v1/conversations lõpp-punktid.

Vahekaart API kuvab 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 vastuse 401 invalid_api_key; tühistatud võtmed tagastavad vastuse 401 revoked_api_key. Viis vigast katset ühe minuti jooksul samalt IP-aadressilt toovad kaasa 60-minutilise blokeeringu.

Piirangud

  • Maksimaalselt 5 aktiivset Bot Talk võtit ühe roboti kohta
  • Maksimaalselt 60 päringut minutis ühe võtme kohta (token bucket, maht 60, sujuv täitmine kiirusega 1 token sekundis). Loomisel madalamaks konfigureeritav - määrake madalam rateLimitPerMinute ning ülempiir langeb ja täitmiskiirus kohandub vastavalt sellele.
  • 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 ühesainsas 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 kasutage uuesti väärtust, mille server varem tagastas.
  • metadata - valikuline objekt: {source, userName, userEmail, userPhone}. userEmail kasutatakse ka sisemise kliendi-ID tuletamiseks.

Vastuse keha (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 on alati "assistant"; message.content on täielik vastus.
  • model on mudeli ID, millel robot selle väljakutse ajal töötas.
  • usage.creditsUsed arvestab kasutaja sõnumit + roboti vastust (tavaliselt 2), millele lisandub üks lisakrediit iga käivitatud tööriistakutse kohta.
  • actions loetleb selle vestluskorra jooksul käivitatud tööriistad. Praegu väljastatakse ainult function_call kirjeid (väljadega type, name, status: "completed").

POST /v1/chat/stream

Lõpp-punkti /v1/chat voogesitusvariant. Tagastab päise Content-Type: text/event-stream koos Server-Sent Events sündmustega.

Päringu keha

Sama struktuur nagu päringul POST /v1/chat. Lippu stream päringu kehas ei nõuta - selle teekonna kasutamine käivitabki SSE.

Vastuse keha (SSE sündmused)

  • message.delta - sisufragment { "content": "..." }. Neid voogesitatakse mitu tükki vastavalt tokenite saabumisele.
  • action - tööriista käivitamine { "type", "name", "status": "executing" }. Väljastatakse siis, kui robot käivitab funktsioonikutse.
  • 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 ühendust elus hoidvaid SSE-kommentaare (:keepalive). Serveripoolsed ajalõpud: esimese tokeni puhul 30 sekundit, voo kohta kokku 120 sekundit.

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

Loetleb teie võtmega seotud roboti vestlused kõigist allikatest (vidin, WhatsApp, API jne).

Päringuparameetrid

  • limit - 1-100, vaikeväärtus 20. Väljaspool vahemikku olevad väärtused piiratakse vahemiku otstesse.
  • 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}

Täielik vestluse ajalugu.

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; sisemised system ja tööriistasõnumid filtreeritakse välja. Tagastab vastuse 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äringulimiidi päised

Päringulimiidi kontrolli faasini jõudnud vastused (st autentimine ja lubatud IP-de kontroll on edukalt läbitud) sisaldavad järgmisi päiseid:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - sellele väljakutsele tegelikult rakendatud võtmepõhine ülempiir (vaikimisi 60 või teie konfigureeritud rateLimitPerMinute, kui see on madalam).
  • X-RateLimit-Remaining - vahetult pärast seda väljakutset salves allesjäänud tokenid.
  • X-RateLimit-Reset - Unixi ajatempli sekundid, millal järgmine token kättesaadavaks muutub (mitte kogu salve täielik lähtestamine; salve täidetakse pidevalt). Kui salv on täis, on see praegune aeg.

Vastuste 429 rate_limit_exceeded puhul määratakse ka päis Retry-After, mis väljendab täissekundi täpsusega aega, kuni vabaneb vähemalt üks token.

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

Vigade vorming

Kõik vead kasutavad ühtset struktuuri:

{
  "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 (koodid: invalid_parameter, 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 voogusid (concurrent_streams_exceeded)
  • 500 api_error - sisemine viga

Seotud teemad

Konto tasemel toimingute (robotite loomine, robotite uuendamine, kasutusstatistika toomine) kohta vaadake teemat Management API.

Otsige kõigist artiklitestKüsige agendilt