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.

Prvi koraci

  1. Izaberite svog chatbota i idite na karticu API na vrhu stranice bota (Select Bot > API (Izaberi bota > API)).

Kartica Bot Talk API

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

Kartica API sa označenim dugmetom Create API Key

Brojač pored dugmeta prikazuje koliko je ključeva aktivno ("1 of 5 API keys active"). Link View API Documentation (Pogledaj API dokumentaciju) otvara ovu referencu, a curl isečak Quick Start (Brzi početak) daje Vam primer spreman za pokretanje.

  1. U dijalogu Create API Key (Kreiraj API ključ), dajte ključu naziv, opciono podesite belu listu IP adresa i ograničenje brzine (rate limit), izaberite dozvole koje ima, a zatim kliknite na Create (Kreiraj).

Dijalog Create API Key

  1. Kopirajte ceo ključ iz dijaloga o uspešnom kreiranju. Čist tekst ključa se prikazuje samo jednom.

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

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) - omogućava krajnje tačke /v1/chat i /v1/chat/stream.
  • Conversation history (list and read past conversations) - 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

POST /v1/chat

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

Telo zahteva

{
  "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 novi razgovor; ponovo upotrebite vrednost koju je server prethodno vratio da biste se nadovezali na postojeći.
  • metadata - opcioni objekat: {source, userName, userEmail, userPhone}. userEmail se takođe koristi za izvođenje internog ID-ja klijenta.

Telo odgovora (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 je uvek "assistant"; message.content je ceo odgovor.
  • model je ID modela na kom je bot radio za ovaj poziv.
  • usage.creditsUsed obuhvata poruku korisnika + odgovor bota (obično 2), plus jedan dodatni kredit po izvršenom pozivu alata.
  • actions navodi izvršavanja alata koja su pokrenuta tokom ovog koraka. Trenutno se emituju samo stavke function_call (sa type, name, status: "completed").

POST /v1/chat/stream

Striming varijanta krajnje tačke /v1/chat. Vraća Content-Type: text/event-stream sa Server-Sent Events.

Telo zahteva

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

Telo odgovora (SSE događaji)

  • message.delta - fragment sadržaja { "content": "..." }. Više ovih se strimuje kako tokeni pristižu.
  • action - izvršenje alata { "type", "name", "status": "executing" }. Emituje se kada bot pokrene poziv funkcije.
  • message.done - završni događaj sa parametrima conversationId, model, usage i (ako ih ima) završenom listom actions.
  • error - šalje se ako generisanje ne uspe; strim se nakon toga prekida.

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

Curl primer

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 razgovore za bota povezanog sa Vašim ključem, sa svih izvora (widget, WhatsApp, API, itd).

Parametri upita

  • limit - 1-100, podrazumevano 20. Vrednosti izvan ovog opsega se fiksiraju na granice.
  • cursor - neprozirna 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 se skraćuje na 100 znakova sa sufiksom ....
  • nextCursor je null na poslednjoj stranici; prosledite ga kao cursor za preuzimanje sledeće.

GET /v1/conversations/{conversation_id}

Kompletna istorija razgovora.

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 poruke system i poruke alata se filtriraju. Vraća 404 not_found_error ako razgovor ne pripada botu koji je povezan sa Vašim ključem.

Da biste pregledali konfiguraciju bota, koristite krajnju tačku Management API-ja 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 isti format:

{
  "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 (kodovi: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - nedostaje ključ (missing_api_key), nepoznat ključ (invalid_api_key) ili opozvan ključ (revoked_api_key)
  • 402 quota_exceeded_error - iskorišćeni 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 glagol na URL-u
  • 429 rate_limit_error - previše zahteva (rate_limit_exceeded) ili previše istovremenih 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