Palīdzības centrs
Chat API

Bot Talk API

Pēdējo reizi atjaunināts:

Bot Talk API

Bot Talk API ir REST API, kas paredzēts saziņai ar konkrētu tērzēšanas robotu no jūsu pašu lietojumprogrammas - pielāgotām lietotnēm, iekšējiem rīkiem vai jūsu veidotām automatizācijām. Jūs izveidojat API atslēgu robota cilnē API, pēc tam izsaucat tērzēšanas galapunktu, izmantojot šo atslēgu kā Bearer marķieri, lai saņemtu robota atbildes - vienas atbildes veidā vai straumētas, izmantojot SSE.

Darba sākšana

  1. Izvēlieties savu tērzēšanas robotu un dodieties uz cilni API robota lapas augšdaļā (Select Bot > API (Izvēlēties robotu > API)).

Bot Talk API cilne

  1. Noklikšķiniet uz Create API Key (Izveidot API atslēgu).

Izcelta cilne API; poga Create API Key atrodas lapas saturā

Skaitītājs blakus pogai rāda, cik atslēgu ir aktīvas ("1 no 5 API atslēgām aktīva"). Saite View API Documentation (Skatīt API dokumentāciju) atver šo rokasgrāmatu, un Quick Start (Ātrais starts) curl fragments sniedz tūlītējai palaišanai gatavu piemēru.

  1. Dialoglodziņā Create API Key piešķiriet atslēgai nosaukumu, pēc izvēles iestatiet atļauto IP adrešu sarakstu (IP whitelist) un ātruma ierobežojumu (rate limit), izvēlieties tās atļaujas un pēc tam noklikšķiniet uz Create (Izveidot).

Dialoglodziņš Create API Key

  1. Nokopējiet pilno atslēgu no apstiprinājuma loga. Vienkārša teksta formātā tā tiek parādīta tikai vienu reizi.

Atslēga izskatās šādi: ck_abcdefghijklmnopqrstuvwxyz012345. Katra atslēga pieder konkrētajam robotam, tāpēc katrs ar šo atslēgu veiktais pieprasījums sazinās tieši ar to - robots tiek identificēts pēc atslēgas un nekad neparādās vietrādī URL.

  1. Savā serverī palaidiet tālāk norādīto curl piemēru ar savu atslēgu un īsu testa ziņojumu. Saglabājiet atgriezto conversationId, pēc tam izmantojiet to atkārtoti turpmākai saziņai. Pārbaudiet atbildi un sarunu robota cilnē Chatlogs (Sarunu žurnāli).

Glabājiet ck_ atslēgas savā serverī, nevis vietnes JavaScript kodā vai mobilo lietotņu pakotnēs. Atļauja Conversations nodrošina piekļuvi šī robota saglabātajām sarunām ar visiem apmeklētājiem, tāpēc jūsu lietojumprogrammai ir jāautorizē katrs gala lietotājs pirms šo datu atgriešanas. Izmantojiet Revoke (Atsaukt) vai Delete (Dzēst) cilnē API, lai pārtrauktu atslēgas darbību; neviena no šīm darbībām vairs neparādīs atslēgas vienkāršo tekstu.

Pirms sākat, izveidojiet un apmāciet savu tērzēšanas robotu un pārliecinieties, ka jūsu kontā ir iekļauta piekļuve API un ir pieejami ziņojumu kredīti.

Bāzes URL

https://api.chatlab.com/aichat

Visi šajā rakstā minētie galapunkti ir relatīvi pret šo bāzes URL.

Atslēgu atļaujas

Katrai atslēgai ir viena vai abas no šīm atļaujām, kas tiek iestatītas ar slēdžiem dialoglodziņā Create API Key:

  • Chat (send messages and receive responses) - atļauj galapunktus /v1/chat un /v1/chat/stream.
  • Conversation history (list and read past conversations) - atļauj galapunktus /v1/conversations.

Cilnē API katrai atslēgai piešķirtās atļaujas tiek rādītas kā nozīmītes Chat un Conversations.

Autentifikācija

Nosūtiet atslēgu Authorization galvenē katrā pieprasījumā:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Pieprasījumi bez galvenes Authorization: Bearer ... atgriež 401 missing_api_key. Nezināmas atslēgas atgriež 401 invalid_api_key; atsauktas atslēgas atgriež 401 revoked_api_key. Pieci nederīgi mēģinājumi vienas minūtes laikā no vienas un tās pašas IP adreses izraisa 60 minūšu bloķēšanu.

Ierobežojumi

  • Maksimums 5 aktīvas Bot Talk atslēgas vienam robotam
  • Maksimums 60 pieprasījumi minūtē vienai atslēgai (žetonu spainis (token bucket), ietilpība 60, vienmērīga papildināšana ar ātrumu 1 žetons sekundē). Var konfigurēt uz mazāku vērtību izveides laikā - iestatiet zemāku rateLimitPerMinute, un griesti samazināsies, papildināšanas ātrumam pielāgojoties proporcionāli.
  • Maksimālais ziņojuma garums ir 4000 rakstzīmju
  • Vienlaicīgu SSE straumju skaits vienai atslēgai ir atkarīgs no jūsu konta ierobežojumiem

Galapunkti

POST /v1/chat

Nosūtiet ziņojumu robotam un saņemiet pilnu atbildi vienā JSON atbildē.

Pieprasījuma pamatteksts

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - obligāta virkne, ne vairāk kā 4000 rakstzīmju.
  • conversationId - neobligāts UUID. Izlaidiet jaunas sarunas gadījumā; izmantojiet atkārtoti vērtību, ko serveris atgrieza iepriekš, lai pievienotu ziņojumu esošai sarunai.
  • metadata - neobligāts objekts, kas pieņem {source, userName, userEmail, userPhone}. Pašlaik šeit tiek izmantots tikai userEmail, lai iegūtu klienta identifikatoru; kanāls tiek reģistrēts kā API. Nepaļaujieties uz to, ka pārējie metadatu lauki tiks saglabāti potenciālā klienta (lead) ierakstā.

Atbildes pamatteksts (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 vienmēr ir "assistant"; message.content ir pilna atbilde.
  • model ir modeļa ID, ko robots izmantoja šim izsaukumam.
  • usage.creditsUsed pašlaik parāda 2 plus vienu par katru reģistrēto rīka izsaukumu pabeigtā dialoga solī. Šis atbildes skaitītājs neietver modeļa/konteksta kredītu reizinātājus, un to nedrīkst izmantot kā norēķinu uzskaites žurnālu. Konta patēriņa uzskaitei izmantojiet Management API usage un skatiet sadaļu ziņojumu kredīti.
  • actions uzskaita rīku izpildes, kas darbojās šī soļa laikā. Šobrīd tiek izvadīti tikai function_call ieraksti (ar type, name, status: "completed").

POST /v1/chat/stream

/v1/chat straumēšanas variants. Atgriež Content-Type: text/event-stream ar Server-Sent Events.

Pieprasījuma pamatteksts

Tāda pati struktūra kā POST /v1/chat. Karodziņš stream pamattekstā nav nepieciešams - tieši šī ceļa izmantošana aktivizē SSE.

Atbildes pamatteksts (SSE notikumi)

  • message.reset - atmest tekstus, kas uzkrāti pašreizējai atbildei, un sākt vākt deltas no jauna. Tas var notikt, ja ģenerēšana sākas no jauna; abu versiju pievienošana parādītu dublētu vai aizstātu atbildi.
  • message.delta - satura fragments { "content": "..." }. Tiek straumēti vairāki šādi fragmenti, tiklīdz pienāk žetoni.
  • action - rīka izpilde { "type", "name", "status": "executing" }. Tiek nosūtīts, kad robots ierosina funkcijas izsaukumu.
  • message.done - beigu notikums ar conversationId, model, usage un (ja tādas ir) pabeigto actions sarakstu.
  • error - tiek nosūtīts, ja ģenerēšana neizdodas; pēc tam straume tiek pārtraukta.

Ilgstošas ģenerēšanas laikā ik pēc 15 sekundēm tiek nosūtīti darbības uzturēšanas SSE komentāri (:keepalive). Servera puses noildze: 30 sekundes pirmajam žetonam, 120 sekundes kopā vienai straumei.

Curl piemērs

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

Iegūstiet sarakstu ar sarunām tam robotam, kas piesaistīts jūsu atslēgai, no visiem avotiem (logrīks, WhatsApp, API utt.).

Vaicājuma parametri

  • limit - 1-100, noklusējuma vērtība 20. Vērtības ārpus šī diapazona tiek pielāgotas robežām.
  • cursor - necaurspīdīga vērtība, kas atgriezta nextCursor iepriekšējā lapā. Izlaidiet to pirmajai lapai.

Atbildes pamatteksts (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 tiek saīsināts līdz 100 rakstzīmēm ar piedēkli ....
  • nextCursor pēdējā lapā ir null; nododiet to kā cursor, lai iegūtu nākamo lapu.

GET /v1/conversations/{conversation_id}

Šī galapunkta rādītie saglabātie sarunas ziņojumi.

Atbildes pamatteksts (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"}
  ]
}

Tiek atgrieztas tikai lomas user un assistant; iekšējie system un rīku ziņojumi tiek izfiltrēti. Atgriež 404 not_found_error, ja saruna nepieder robotam, kas piesaistīts jūsu atslēgai.

Lai pārbaudītu robota konfigurāciju, izmantojiet Management API galapunktu GET /v1/management/bots/{bot_id} ar Management atslēgu.

Ātruma ierobežojuma galvenes

Atbildes, kas sasniedz ātruma ierobežošanas posmu (t.i., autentifikācija un atļauto IP adrešu pārbaude ir veiksmīga), ietver:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - vienai atslēgai piemērotie griesti, kas faktiski attiecas uz šo izsaukumu (pēc noklusējuma 60, vai jūsu konfigurētais rateLimitPerMinute, ja tas ir mazāks).
  • X-RateLimit-Remaining - spainī atlikušie žetoni uzreiz pēc šī izsaukuma.
  • X-RateLimit-Reset - Unix laikspiedols sekundēs, kurā kļūst pieejams nākamais žetons (tā nav pilna spaiņa atiestatīšana; spainis tiek papildināts nepārtraukti). Kad spainis ir pilns, šis ir pašreizējais laiks.

Atbildēs 429 rate_limit_exceeded tiek iestatīta arī galvene Retry-After, kas izteikta pilnās sekundēs, līdz atbrīvojas vismaz viens žetons.

Kļūdas pirms autentifikācijas (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) un 403 ip_not_whitelisted nesatur galvenes X-RateLimit-* - ierobežotājs tiek pārbaudīts tikai pēc veiksmīgas autentifikācijas un IP pārbaužu veikšanas.

Kļūdu formāts

Visām kļūdām ir vienots ietvars:

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

Biežākie HTTP kodi:

  • 400 invalid_request_error - nepareizi veidota ievade (invalid_parameter)
  • 415 invalid_request_error - neatbalstīts satura tips (unsupported_media_type)
  • 401 authentication_error - trūkst atslēgas (missing_api_key), nezināma atslēga (invalid_api_key) vai atsaukta atslēga (revoked_api_key)
  • 402 quota_exceeded_error - iztērēti ziņojumu kredīti
  • 403 permission_error - bloķēta IP adrese (ip_blocked), IP adrese nav atslēgas atļauto adrešu sarakstā (ip_not_whitelisted), vai arī atslēgas veids neatļauj šo galapunktu (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - saruna nepieder šim robotam
  • 405 invalid_request_error (method_not_allowed) - nepareiza HTTP darbība (verbs) vietrādim URL
  • 429 rate_limit_error - pārāk daudz pieprasījumu (rate_limit_exceeded) vai pārāk daudz vienlaicīgu straumju (concurrent_streams_exceeded)
  • 500 api_error - iekšēja kļūda

Saistītie resursi

Darbībām konta līmenī (robotu izveide, robotu atjaunināšana, patēriņa iegūšana) skatiet sadaļu Management API.

Meklēt visus rakstusJautājiet aģentam