Centru de ajutor
Chat API

Bot Talk API

Ultima actualizare:

Bot Talk API

Bot Talk API este un API REST pentru comunicarea cu un anumit chatbot direct din propria aplicație - aplicații personalizate, instrumente interne sau fluxuri de automatizare create de dumneavoastră. Creați o cheie API în fila API a botului, apoi apelați endpointul de chat folosind cheia ca Bearer token pentru a primi răspunsurile botului, fie ca răspuns unic, fie transmise în flux (streaming) prin SSE.

Primii pași

  1. Selectați chatbotul dumneavoastră și navigați la fila API din partea de sus a paginii botului (Select Bot > API [Selectați botul > API]).

Fila Bot Talk API

  1. Faceți clic pe Create API Key (Creați o cheie API).

Fila API evidențiată; Create API Key se află în conținutul paginii

Contorul de lângă buton indică câte chei sunt active ("1 of 5 API keys active"). Linkul View API Documentation (Vizualizați documentația API) deschide acest ghid de referință, iar fragmentul curl Quick Start (Pornire rapidă) vă oferă un exemplu gata de rulat.

  1. În caseta de dialog Create API Key, dați un nume cheii, setați opțional o listă de adrese IP permise (whitelist) și o limită de frecvență a solicitărilor (rate limit), alegeți permisiunile asociate, apoi faceți clic pe Create (Creați).

Caseta de dialog Create API Key

  1. Copiați cheia completă din caseta de dialog afișată la finalizarea cu succes. Textul necriptat este afișat o singură dată.

O cheie are forma ck_abcdefghijklmnopqrstuvwxyz012345. Fiecare cheie este asociată respectivului bot, astfel încât fiecare solicitare trimisă cu acea cheie comunică exclusiv cu acesta - botul este identificat prin cheie și nu apare niciodată în URL.

  1. De pe serverul dumneavoastră, rulați exemplul curl de mai jos folosind cheia proprie și un mesaj scurt de test. Salvați valoarea conversationId primită în răspuns, apoi reutilizați-o pentru mesajele următoare. Confirmați răspunsul și conversația în fila Chatlogs (Istoric conversații) a botului.

Păstrați cheile ck_ pe serverul dumneavoastră, nu în codul JavaScript al site-ului web sau în pachetele aplicațiilor mobile. Permisiunea Conversations oferă acces la conversațiile salvate ale acestui bot de la toți vizitatorii; prin urmare, aplicația dumneavoastră trebuie să autorizeze fiecare utilizator final înainte de a-i returna aceste date. Utilizați opțiunile Revoke (Revocați) sau Delete (Ștergeți) din fila API pentru a dezactiva o cheie; niciuna dintre aceste acțiuni nu va afișa din nou cheia în clar.

Înainte de a începe, creați și antrenați chatbotul dumneavoastră și verificați dacă contul include acces la API și deține credite pentru mesaje.

URL de bază

https://api.chatlab.com/aichat

Toate endpointurile din acest articol sunt relative la acest URL de bază.

Permisiunile cheii

Fiecare cheie conține una sau ambele permisiuni de mai jos, configurate prin comutatoarele din caseta de dialog Create API Key:

  • Chat (send messages and receive responses) [Chat (trimiteți mesaje și primiți răspunsuri)] - permite accesul la endpointurile /v1/chat și /v1/chat/stream.
  • Conversation history (list and read past conversations) [Istoricul conversațiilor (listați și citiți conversațiile anterioare)] - permite accesul la endpointurile /v1/conversations.

Fila API afișează permisiunile acordate fiecărei chei sub formă de etichete Chat și Conversations.

Autentificare

Trimiteți cheia în antetul Authorization la fiecare solicitare:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Solicitările fără un antet Authorization: Bearer ... returnează eroarea 401 missing_api_key. Cheile necunoscute returnează 401 invalid_api_key; cheile revocate returnează 401 revoked_api_key. Cinci încercări nevalide într-un minut de la aceeași adresă IP declanșează o blocare de 60 de minute.

Limite

  • Maximum 5 chei Bot Talk active per bot
  • Maximum 60 de solicitări pe minut per cheie (algoritm token bucket, capacitate de 60, reumplere constantă cu 1 jeton pe secundă). Valoarea poate fi redusă la creare - setați un rateLimitPerMinute mai mic, iar limita maximă scade, rata de reumplere ajustându-se proporțional.
  • Lungimea maximă a mesajului este de 4000 de caractere
  • Fluxurile SSE simultane per cheie sunt supuse limitelor contului dumneavoastră

Endpointuri

POST /v1/chat

Trimite un mesaj către bot și primește răspunsul complet într-un singur răspuns JSON.

Corpul solicitării (Request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - șir de caractere obligatoriu, maximum 4000 de caractere.
  • conversationId - UUID opțional. Omiteți-l pentru o conversație nouă; reutilizați valoarea returnată anterior de server pentru a continua o conversație existentă.
  • metadata - obiect opțional care acceptă {source, userName, userEmail, userPhone}. În prezent, doar userEmail este utilizat aici, pentru a deduce identificatorul clientului; canalul este înregistrat ca API. Nu vă bazați pe salvarea celorlalte câmpuri de metadate într-o înregistrare de lead.

Corpul răspunsului (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 este întotdeauna "assistant"; message.content reprezintă răspunsul complet.
  • model este identificatorul modelului pe care a rulat botul pentru acest apel.
  • usage.creditsUsed raportează în prezent 2 credite plus un credit pentru fiecare apel de instrument raportat la un ciclu complet de conversație. Acest contor din răspuns nu include multiplicatorii de credite pentru model/context și nu trebuie utilizat ca registru de facturare. Consultați Management API usage pentru consumul la nivel de cont și secțiunea despre credite pentru mesaje.
  • actions listează execuțiile de instrumente care au rulat în timpul acestei interacțiuni. În prezent, sunt emise doar intrări de tip function_call (cu type, name, status: "completed").

POST /v1/chat/stream

Varianta de streaming pentru /v1/chat. Returnează Content-Type: text/event-stream cu evenimente Server-Sent Events (SSE).

Corpul solicitării (Request body)

Aceeași structură ca la POST /v1/chat. Indicatorul stream din corpul solicitării nu este obligatoriu - utilizarea acestei căi activează automat SSE.

Corpul răspunsului (evenimente SSE)

  • message.reset - anulează textul acumulat pentru răspunsul curent și începe din nou colectarea fragmentelor delta. Acest lucru poate apărea la reluarea generării; adăugarea ambelor versiuni ar produce un răspuns duplicat sau înlocuit.
  • message.delta - fragment de conținut { "content": "..." }. Se transmit mai multe astfel de fragmente pe măsură ce sosesc tokenurile.
  • action - execuție de instrument { "type", "name", "status": "executing" }. Este emis atunci când botul declanșează un apel de funcție.
  • message.done - eveniment final ce conține conversationId, model, usage și lista actions finalizată (dacă există).
  • error - trimis în cazul în care generarea eșuează; fluxul este întrerupt ulterior.

Comentarii SSE de tip keep-alive (:keepalive) sunt trimise la fiecare 15 secunde în timpul generărilor de lungă durată. Limite de timp (timeout) pe server: 30 de secunde pentru primul token, 120 de secunde în total per flux.

Exemplu Curl

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

Listează conversațiile pentru botul asociat cheii dumneavoastră, din toate sursele (widget, WhatsApp, API etc.).

Parametri de interogare (Query parameters)

  • limit - 1-100, valoare implicită 20. Valorile din afara acestui interval sunt ajustate automat la limite.
  • cursor - valoare opacă returnată în nextCursor la pagina anterioară. Omiteți parametrul pentru prima pagină.

Corpul răspunsului (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 este trunchiat la 100 de caractere, cu sufixul ....
  • nextCursor este null pe ultima pagină; transmiteți-l ca valoare pentru cursor pentru a prelua pagina următoare.

GET /v1/conversations/{conversation_id}

Mesajele conversației păstrate, expuse prin acest endpoint.

Corpul răspunsului (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"}
  ]
}

Sunt returnate doar rolurile user și assistant; mesajele interne de tip system și mesajele instrumentelor sunt filtrate. Returnează 404 not_found_error dacă conversația nu aparține botului asociat cheii dumneavoastră.

Pentru a inspecta configurația botului, utilizați endpointul Management API GET /v1/management/bots/{bot_id} cu o cheie Management.

Antete pentru limite de frecvență (Rate limit headers)

Răspunsurile care ajung la etapa de verificare a limitelor de frecvență (adică după ce au trecut etapele de autentificare și de verificare a listei IP) includ:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limita per cheie aplicată efectiv acestui apel (60 în mod implicit, sau valoarea configurată de dumneavoastră în rateLimitPerMinute, dacă este mai mică).
  • X-RateLimit-Remaining - numărul de jetoane rămase în recipient imediat după acest apel.
  • X-RateLimit-Reset - timestamp Unix epoch în secunde la care devine disponibil următorul jeton (nu o resetare completă a recipientului; acesta se reumple continuu). Când recipientul este plin, această valoare reprezintă ora curentă.

La răspunsurile 429 rate_limit_exceeded, este inclus și antetul Retry-After, exprimat în secunde întregi până la eliberarea a cel puțin unui jeton.

Erorile premergătoare autentificării (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) și 403 ip_not_whitelisted nu includ antetele X-RateLimit-* - sistemul de limitare a frecvenței este consultat doar după ce verificările de autentificare și IP au reușit.

Formatul erorilor

Toate erorile utilizează o structură comună:

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

Coduri HTTP frecvente:

  • 400 invalid_request_error - solicitare incorectă (invalid_parameter)
  • 415 invalid_request_error - tip de conținut neacceptat (unsupported_media_type)
  • 401 authentication_error - cheie lipsă (missing_api_key), cheie necunoscută (invalid_api_key) sau cheie revocată (revoked_api_key)
  • 402 quota_exceeded_error - credite pentru mesaje epuizate
  • 403 permission_error - adresă IP blocată (ip_blocked), adresă IP neautorizată în lista cheii (ip_not_whitelisted) sau tipul de cheie nu permite accesul la acest endpoint (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - conversația nu aparține acestui bot
  • 405 invalid_request_error (method_not_allowed) - metodă HTTP incorectă pentru acest URL
  • 429 rate_limit_error - prea multe solicitări (rate_limit_exceeded) sau prea multe fluxuri simultane (concurrent_streams_exceeded)
  • 500 api_error - eroare internă

Articole conexe

Pentru operațiuni la nivel de cont (crearea de boți, actualizarea boților, consultarea consumului), consultați Management API.

Căutați în toate articoleleÎntrebați agentul