Centar za pomoć
Chat API

Bot Talk API

Poslednje ažuriranje:

Bot Talk API

Bot Talk API je REST API za komunikaciju sa jednim konkretnim chatbotom iz Vaše sopstvene aplikacije - prilagođenih aplikacija, internih alata ili automatizacija koje sami napravite. Kreirate API ključ na kartici API bota, a zatim pozivate chat krajnju tačku sa ključem kao Bearer tokenom da biste dobili odgovore bota, bilo kao pojedinačni odgovor ili strimovano putem SSE-a.

Početak rada

  1. Izaberite svog bota i pređite na karticu API na vrhu stranice bota (Select Bot > API - Izaberite bota > API).

Kartica Bot Talk API

  1. Kliknite na Create API Key (Kreiraj API ključ).

Istaknuta kartica API; dugme Create API Key se nalazi u sadržaju stranice

Brojač pored dugmeta prikazuje koliko je ključeva aktivno ("1 of 5 API keys active"). Link View API Documentation (Pogledajte API dokumentaciju) otvara ovu dokumentaciju, a Quick Start curl primer Vam pruža gotov kod za pokretanje.

  1. U dijalogu Create API Key dodelite ključu naziv, opciono postavite listu dozvoljenih IP adresa i ograničenje brzine (rate limit), odaberite dozvole koje poseduje, a zatim kliknite na Create (Kreiraj).

Dijalog Create API Key

  1. Kopirajte ceo ključ iz dijaloga o uspešnom kreiranju. Tekst u čistom formatu prikazuje se samo jednom.

Ključ izgleda kao ck_abcdefghijklmnopqrstuvwxyz012345. Svaki ključ pripada samo tom jednom botu, tako da svaki zahtev upućen pomoću ključa komunicira sa tim botom - bot se identifikuje putem ključa i nikada se ne pojavljuje u URL adresi.

  1. Sa svog servera pokrenite curl primer u nastavku sa svojim ključem i kratkom test porukom. Sačuvajte vraćeni conversationId, a zatim ga ponovo iskoristite za sledeću poruku. Potvrdite odgovor i konverzaciju na kartici Chatlogs (Istorija ćaskanja) Vašeg bota.

Čuvajte ključeve ck_ na svom serveru, a ne u JavaScript kodu veb-sajta ili paketima mobilnih aplikacija. Dozvola Conversations pruža pristup sačuvanim konverzacijama ovog bota sa svim posetiocima, pa Vaša aplikacija mora da autorizuje svakog krajnjeg korisnika pre nego što vrati te podatke. Koristite opcije Revoke (Opozovi) ili Delete (Obriši) na kartici API da biste povukli ključ; nijedna radnja više neće prikazati njegov tekst u čistom formatu.

Pre nego što počnete, kreirajte i trenirajte svog bota i proverite da li Vaš nalog uključuje API pristup i poseduje kredite za poruke.

Osnovni URL

https://api.chatlab.com/aichat

Sve krajnje tačke u ovom članku su relativne u odnosu na ovaj osnovni URL.

Dozvole ključa

Svaki ključ nosi jednu ili obe ove dozvole, podešene pomoću prekidača u dijalogu Create API Key:

  • Chat (send messages and receive responses) (Ćaskanje: slanje poruka i primanje odgovora) - omogućava krajnje tačke /v1/chat i /v1/chat/stream.
  • Conversation history (list and read past conversations) (Istorija razgovora: lista i čitanje prethodnih razgovora) - omogućava krajnje tačke /v1/conversations.

Kartica API prikazuje dodeljene dozvole svakog ključa kao oznake Chat i Conversations.

Autentifikacija

Pošaljite ključ u zaglavlju Authorization pri svakom zahtevu:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Zahtevi bez zaglavlja Authorization: Bearer ... vraćaju 401 missing_api_key. Nepoznati ključevi vraćaju 401 invalid_api_key; opozvani ključevi vraćaju 401 revoked_api_key. Pet nevažećih pokušaja u jednom minutu sa iste IP adrese pokreću blokadu od 60 minuta.

Ograničenja

  • Maksimalno 5 aktivnih Bot Talk ključeva po botu
  • Maksimalno 60 zahteva u minutu po ključu (token bucket, kapacitet 60, ravnomerno dopunjavanje od 1 tokena u sekundi). Može se konfigurisati na manju vrednost prilikom kreiranja - podesite niži rateLimitPerMinute i gornja granica opada, a brzina dopunjavanja se usklađuje sa njom.
  • Maksimalna dužina poruke 4000 znakova
  • Istovremeni SSE strimovi po ključu podležu ograničenjima Vašeg naloga

Krajnje tačke (Endpoints)

POST /v1/chat

Pošaljite poruku botu i primite kompletan odgovor u jednom JSON odgovoru.

Telo zahteva (Request body)

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - obavezan string, maksimalno 4000 znakova.
  • conversationId - opcioni UUID. Izostavite za novu konverzaciju; ponovo iskoristite vrednost koju je server prethodno vratio da biste nastavili postojeću.
  • metadata - opcioni objekat koji prihvata {source, userName, userEmail, userPhone}. Trenutno se ovde koristi samo userEmail, kako bi se izveo identifikator klijenta; kanal se beleži kao API. Nemojte se oslanjati na to da će ostala polja metapodataka biti sačuvana u zapis o lead-u.

Telo odgovora (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 je uvek "assistant"; message.content predstavlja pun odgovor.
  • model je ID modela na kojem je bot radio tokom ovog poziva.
  • usage.creditsUsed trenutno prijavljuje 2 plus po jedan za svaki prijavljeni poziv alata za završeni krug. Ovaj brojač u API odgovoru ne uključuje množioce kredita za model/kontekst i ne sme se koristiti kao Vaša evidencija za naplatu. Koristite potrošnju u Management API-ju za uvid u potrošnju naloga i pogledajte kredite za poruke.
  • actions navodi izvršavanja alata koja su pokrenuta tokom ovog kruga. Danas se emituju samo function_call stavke (uz type, name, status: "completed").

POST /v1/chat/stream

Varijanta za strimovanje (streaming) za /v1/chat. Vraća Content-Type: text/event-stream sa Server-Sent Events (SSE).

Telo zahteva (Request body)

Ista struktura kao POST /v1/chat. Oznaka stream u telu nije obavezna - korišćenje ove putanje je ono što pokreće SSE.

Telo odgovora (SSE događaji)

  • message.reset - odbacite tekst akumuliran za trenutni odgovor i počnite ponovo da prikupljate delte. Ovo se može dogoditi kada se generisanje ponovo pokrene; dodavanje obe verzije bi prikazalo duplirani ili zamenjeni odgovor.
  • message.delta - fragment sadržaja { "content": "..." }. Više ovakvih događaja se strimuje kako tokeni pristižu.
  • action - izvršavanje alata { "type", "name", "status": "executing" }. Emituje se kada bot pokrene poziv funkcije.
  • message.done - završni događaj sa conversationId, model, usage i (ako postoji) završenom actions listom.
  • error - šalje se ako generisanje ne uspe; strim se nakon toga prekida.

Keep-alive SSE komentari (:keepalive) šalju se svakih 15 sekundi tokom dugih generisanja. Vremenska ograničenja na strani servera: 30 sekundi za prvi token, ukupno 120 sekundi po strimu.

Primer za 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

Izlistajte konverzacije za bota povezanog sa Vašim ključem, kroz sve izvore (widget, WhatsApp, API, itd).

Parametri upita (Query parameters)

  • limit - 1-100, podrazumevano 20. Vrednosti izvan ovog opsega se automatski ograničavaju.
  • cursor - neprozirna (opaque) vrednost vraćena u nextCursor na prethodnoj stranici. Izostavite za prvu stranicu.

Telo odgovora (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 je skraćen na 100 znakova sa sufiksom ....
  • nextCursor je null na poslednjoj stranici; prosledite ga kao cursor da biste preuzeli sledeću.

GET /v1/conversations/{conversation_id}

Sačuvane poruke konverzacije koje ova krajnja tačka prikazuje.

Telo odgovora (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"}
  ]
}

Vraćaju se samo uloge user i assistant; interne system poruke i poruke alata su filtrirane. Vraća 404 not_found_error ako konverzacija ne pripada botu povezanom sa Vašim ključem.

Da biste pregledali konfiguraciju bota, koristite Management API krajnju tačku GET /v1/management/bots/{bot_id} sa Management ključem.

Zaglavlja ograničenja brzine (rate limit)

Odgovori koji dođu do faze provere ograničenja brzine (odnosno, prošli su autentifikaciju i belu listu IP adresa) sadrže:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - gornja granica po ključu koja je zapravo primenjena na ovaj poziv (podrazumevano 60, ili Vaš konfigurisani rateLimitPerMinute ako je niži).
  • X-RateLimit-Remaining - preostali tokeni u skladištu (bucket) neposredno nakon ovog poziva.
  • X-RateLimit-Reset - Unix epoch sekunde u kojima sledeći token postaje dostupan (nije potpuno resetovanje skladišta; ono se dopunjava neprekidno). Kada je skladište puno, ovo je trenutno vreme.

U odgovorima 429 rate_limit_exceeded, takođe je postavljeno zaglavlje Retry-After, izraženo u celim sekundama dok se ne oslobodi bar jedan token.

Greške pre autentifikacije (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) i 403 ip_not_whitelisted ne sadrže zaglavlja X-RateLimit-* - mehanizam ograničenja se proverava tek nakon uspešne autentifikacije i provera IP adrese.

Format grešaka

Sve greške dele jedinstveni format omotača:

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

Uobičajeni HTTP kodovi:

  • 400 invalid_request_error - neispravan unos (invalid_parameter)
  • 415 invalid_request_error - nepodržani tip sadržaja (unsupported_media_type)
  • 401 authentication_error - ključ nedostaje (missing_api_key), nepoznat ključ (invalid_api_key) ili opozvan ključ (revoked_api_key)
  • 402 quota_exceeded_error - iskorišćeni su krediti za poruke
  • 403 permission_error - IP adresa je blokirana (ip_blocked), IP adresa nije na beloj listi ključa (ip_not_whitelisted) ili tip ključa ne dozvoljava ovu krajnju tačku (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - razgovor ne pripada ovom botu
  • 405 invalid_request_error (method_not_allowed) - pogrešan HTTP metod na URL adresi
  • 429 rate_limit_error - previše zahteva (rate_limit_exceeded) ili previše paralelnih strimova (concurrent_streams_exceeded)
  • 500 api_error - interna greška

Povezano

Za operacije na nivou naloga (kreiranje botova, ažuriranje botova, pregled potrošnje), pogledajte Management API.

Pretražite sve člankePitajte agenta