Centru de ajutor
Chat API

Bot Talk API

Ultima actualizare:

Bot Talk API

Bot Talk API este un API REST pentru comunicarea cu un chatbot specific din propria dumneavoastră aplicație - aplicații personalizate, instrumente interne sau automatizări pe care le construiți dumneavoastră. Creați o cheie API în fila API a botului, apoi apelați endpoint-ul de chat folosind cheia ca Bearer token pentru a primi răspunsurile botului, fie ca răspuns unic, fie prin 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 (Selectare bot > API)).

Fila Bot Talk API

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

Fila API cu butonul Create API Key evidențiat

Contorul de lângă buton indică numărul de chei active („1 of 5 API keys active”). Linkul View API Documentation (Vizualizare documentație API) deschide acest ghid de referință, iar fragmentul curl din Quick Start (Pornire rapidă) vă oferă un exemplu gata de rulare.

  1. În fereastra modală Create API Key (Creare cheie API), introduceți un nume pentru cheie, setați opțional o listă de permisiuni IP (whitelist) și o limită de rată (rate limit), alegeți permisiunile atribuite, apoi faceți clic pe Create (Creare).

Fereastra modală Create API Key

  1. Copiați cheia completă din fereastra de confirmare. Cheia în text clar este afișată o singură dată.

O cheie are forma ck_abcdefghijklmnopqrstuvwxyz012345. Fiecare cheie aparține acelui bot individual, astfel încât fiecare solicitare trimisă cu respectiva cheie comunică exclusiv cu acel bot - botul este identificat prin cheie și nu apare niciodată în URL.

URL de bază

https://api.chatlab.com/aichat

Toate endpoint-urile din acest articol sunt relative la acest URL de bază.

Permisiunile cheii

Fiecare cheie conține una sau ambele permisiuni de mai jos, configurate cu ajutorul comutatoarelor din fereastra Create API Key:

  • Chat (send messages and receive responses) - permite accesul la endpoint-urile /v1/chat și /v1/chat/stream.
  • Conversation history (list and read past conversations) - permite accesul la endpoint-urile /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ă 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 60, reumplere constantă la 1 token pe secundă). Poate fi configurată la o valoare mai mică la creare - setați un rateLimitPerMinute mai redus și limita scade, iar rata de reumplere se scalează proporțional.
  • Lungimea maximă a mesajului este de 4000 de caractere
  • Fluxurile SSE concurente per cheie sunt supuse limitelor contului dumneavoastră

Endpoint-uri

POST /v1/chat

Trimiteți un mesaj către bot și primiți 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 adăuga mesaje la o conversație existentă.
  • metadata - obiect opțional: {source, userName, userEmail, userPhone}. userEmail este utilizat și pentru a deriva identificatorul intern al clientului.

Corpul răspunsului (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 este întotdeauna "assistant"; message.content este răspunsul complet.
  • model este identificatorul modelului pe care a rulat botul pentru acest apel.
  • usage.creditsUsed contorizează mesajul utilizatorului + răspunsul botului (de regulă 2), plus un credit suplimentar pentru fiecare apel de instrument (tool call) executat.
  • actions listează execuțiile de instrumente care au rulat în timpul acestei interacțiuni. În prezent, sunt emise doar intrări function_call (cu type, name, status: "completed").

POST /v1/chat/stream

Varianta de streaming a /v1/chat. Returnează Content-Type: text/event-stream cu Server-Sent Events.

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 declanșează automat SSE.

Corpul răspunsului (evenimente SSE)

  • message.delta - fragment de conținut { "content": "..." }. Se transmit mai multe astfel de fragmente pe măsură ce sosesc tokenurile.
  • action - execuție a unui instrument { "type", "name", "status": "executing" }. Este emisă atunci când botul declanșează un apel de funcție.
  • message.done - eveniment final cu conversationId, model, usage și (dacă există) lista de actions finalizate.
  • error - trimis dacă generarea eșuează; fluxul se încheie ulterior.

Comentariile SSE de tip keep-alive (:keepalive) sunt trimise la fiecare 15 secunde în timpul generărilor îndelungate. Intervalele de expirare (timeouts) 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 intervalului sunt ajustate automat la limite.
  • cursor - valoare opacă returnată în nextCursor la pagina anterioară. Omiteți-l 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 cursor pentru a prelua pagina următoare.

GET /v1/conversations/{conversation_id}

Istoricul complet al conversației.

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 sistem (system) și cele ale 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 endpoint-ul Management API GET /v1/management/bots/{bot_id} cu o cheie Management.

Antete pentru limitarea ratei (Rate limit headers)

Răspunsurile care ajung la etapa de verificare a limitei de rată (adică autentificarea și lista de permisiuni IP au fost validate) includ:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - limita per cheie aplicată efectiv acestui apel (implicit 60, sau valoarea dumneavoastră configurată în rateLimitPerMinute dacă este mai mică).
  • X-RateLimit-Remaining - tokenurile rămase în bucket imediat după acest apel.
  • X-RateLimit-Reset - secunde Unix epoch la care devine disponibil următorul token (nu o resetare completă a bucket-ului; bucket-ul se reumple continuu). Când bucket-ul este plin, aceasta reprezintă ora curentă.

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

Erorile din etapa de pre-autentificare (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) și 403 ip_not_whitelisted nu conțin antetele X-RateLimit-* - sistemul de limitare a ratei este consultat numai după ce autentificarea și verificările IP reușesc.

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 - date de intrare formatate incorect (coduri: invalid_parameter, 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 de mesaje epuizate
  • 403 permission_error - IP blocat (ip_blocked), IP-ul nu se află în lista de permisiuni a cheii (ip_not_whitelisted) sau tipul cheii 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 concurente (concurrent_streams_exceeded)
  • 500 api_error - eroare internă

Articole conexe

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

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