Palīdzības centrs
Chat API

Bot Talk API

Pēdējo reizi atjaunināts:

Bot Talk API

Bot Talk API ir REST API saziņai ar vienu konkrētu tērzēšanas robotu no Jūsu pašu lietotnes - pielāgotām lietotnēm, iekšējiem rīkiem vai Jūsu izveidotām automatizācijām. Jūs izveidojat API atslēgu robota cilnē API, pēc tam izsaucat tērzēšanas galapunktu, izmantojot 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 atveriet 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).

API cilne ar izceltu pogu Create API Key

Skaitītājs blakus pogai parāda, cik atslēgu ir aktīvas ("1 of 5 API keys active"). Saite View API Documentation (Skatīt API dokumentāciju) atver šo aprakstu, un Quick Start (Ātrais starts) curl koda fragments sniedz tūlītēji palaižamu piemēru.

  1. Dialoglodziņā Create API Key (Izveidot API atslēgu) piešķiriet atslēgai nosaukumu, pēc izvēles iestatiet atļauto IP adrešu sarakstu un ātruma ierobežojumu, 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 apstiprinājuma dialoglodziņā. Nešifrētais teksts tiek parādīts tikai vienu reizi.

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

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 šīs atļaujas, ko iestata 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 katras atslēgas piešķirtās atļaujas tiek rādītas kā nozīmītes Chat un Conversations.

Autentifikācija

Nosūtiet atslēgu galvenē Authorization 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

  • Ne vairāk kā 5 aktīvas Bot Talk atslēgas vienam robotam
  • Ne vairāk kā 60 pieprasījumi minūtē vienai atslēgai (žetonu spainis, ietilpība 60, vienmērīga papildināšana ar ātrumu 1 žetons sekundē). Var konfigurēt uz leju izveides brīdī - iestatiet zemāku rateLimitPerMinute, un limits samazināsies, bet papildināšanas ātrums pielāgosies atbilstoši.
  • Maksimālais ziņojuma garums ir 4000 rakstzīmju
  • Vienlaicīgu SSE straumju skaits vienai atslēgai ir pakļauts 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 to jaunai sarunai; izmantojiet atkārtoti vērtību, ko serveris atgrieza iepriekš, lai pievienotu ziņojumu esošai sarunai.
  • metadata - neobligāts objekts: {source, userName, userEmail, userPhone}. userEmail tiek izmantots arī iekšējā klienta ID atvasināšanai.

Atbildes pamatteksts (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 vienmēr ir "assistant"; message.content ir pilna atbilde.
  • model ir modeļa ID, ko robots izmantoja šim izsaukumam.
  • usage.creditsUsed ietver lietotāja ziņojumu + robota atbildi (parasti 2), kā arī vienu papildu kredītu par katru izpildīto rīka izsaukumu.
  • actions uzskaita rīku izpildi, kas notika šīs kārtas laikā. Pašlaik tiek ģenerēti tikai function_call ieraksti (ar type, name, status: "completed").

POST /v1/chat/stream

Galapunkta /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. Pamattekstā nav nepieciešams parametrs stream - SSE palaišanu nosaka šī ceļa izmantošana.

Atbildes pamatteksts (SSE notikumi)

  • message.delta - satura fragments { "content": "..." }. Vairāki šādi fragmenti tiek straumēti, tiklīdz ienā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ādi 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 noildzes: 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 Jūsu atslēgai piesaistītā robota sarunu sarakstu no visiem avotiem (logrīks, WhatsApp, API utt.).

Vaicājuma parametri

  • limit - 1-100, noklusējuma vērtība ir 20. Vērtības ārpus šī diapazona tiek pielāgotas robežām.
  • cursor - necaurspīdīga vērtība, kas atgriezta parametrā 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 galotni ....
  • Pēdējā lapā nextCursor ir null; norādiet to kā cursor, lai ielādētu nākamo lapu.

GET /v1/conversations/{conversation_id}

Pilna sarunas vēsture.

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 user un assistant lomas; iekšējie system un rīku ziņojumi tiek filtrēti. Atgriež 404 not_found_error, ja saruna nepieder robotam, kas ir 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 - atslēgas limits, kas faktiski piemērots šim izsaukumam (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 pilnīga 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 veselās sekundēs, līdz atbrīvojas vismaz viens žetons.

Pirmsautentifikācijas kļūdas (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) un 403 ip_not_whitelisted neietver X-RateLimit-* galvenes - 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 formatēta ievade (kodi: invalid_parameter, 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 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 metode šim 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 raksti

Informāciju par konta līmeņa darbībām (robotu izveidi, atjaunināšanu, lietojuma iegūšanu) skatiet sadaļā Management API.

Meklēt visus rakstusJautājiet aģentam