Súgóközpont
Chat API

Bot Talk API

Utoljára frissítve:

Bot Talk API

A Bot Talk API egy REST API, amellyel egy adott chatbotot szólíthat meg a saját alkalmazásából - egyedi alkalmazásokból, belső eszközökből vagy saját maga által épített automatizációkból. Létrehoz egy API-kulcsot a bot API lapján (tab), majd meghívja a chat végpontot a kulccsal mint Bearer tokennel, hogy megkapja a bot válaszait, akár egyetlen válaszként, akár SSE-n keresztül streamelve.

Első lépések

  1. Válassza ki a chatbotját, és lépjen az API lapra a bot oldalának tetején (Select Bot > API [Bot kiválasztása > API]).

Bot Talk API lap

  1. Kattintson a Create API Key (API-kulcs létrehozása) lehetőségre.

API lap a Create API Key gombbal kiemelve

A gomb melletti számláló mutatja, hogy hány kulcs aktív ("1 of 5 API keys active"). A View API Documentation (API-dokumentáció megtekintése) hivatkozás megnyitja ezt a segédletet, a Quick Start (Gyorsindítás) curl kódrészlet pedig egy azonnal futtatható példát nyújt.

  1. A Create API Key párbeszédpanelen adjon nevet a kulcsnak, opcionálisan állítson be egy IP-engedélyezési listát (whitelist) és egy sebességkorlátot (rate limit), válassza ki a hozzá tartozó engedélyeket, majd kattintson a Create (Létrehozás) gombra.

Create API Key párbeszédpanel

  1. Másolja ki a teljes kulcsot a sikeres műveletet jelző párbeszédpanelről. A titkosítatlan szöveg csak egyszer jelenik meg.

A kulcs a következőképpen néz ki: ck_abcdefghijklmnopqrstuvwxyz012345. Mindegyik kulcs ahhoz az egy slothoz/bothoz tartozik, így a kulccsal végrehajtott minden kérés azzal a bottal kommunikál - a botot a kulcs azonosítja, és soha nem szerepel az URL-ben.

Alap URL

https://api.chatlab.com/aichat

A jelen cikkben szereplő összes végpont ehhez az alap URL-hez képest relatív.

Kulcsengedélyek

Minden kulcs rendelkezik az alábbi engedélyek egyikével vagy mindkettővel, amelyeket a Create API Key párbeszédpanel kapcsolóival állíthat be:

  • Chat (send messages and receive responses) - engedélyezi a /v1/chat és a /v1/chat/stream végpontokat.
  • Conversation history (list and read past conversations) - engedélyezi a /v1/conversations végpontokat.

Az API lap az egyes kulcsokhoz megadott engedélyeket Chat és Conversations jelvényként jeleníti meg.

Hitelesítés

Minden kérésnél küldje el a kulcsot az Authorization fejlécben:

Authorization: Bearer ck_abcdefghijklmnopqrstuvwxyz012345

Az Authorization: Bearer ... fejléc nélküli kérések 401 missing_api_key hibát adnak vissza. Az ismeretlen kulcsok 401 invalid_api_key, a visszavont kulcsok pedig 401 revoked_api_key hibát eredményeznek. Ha ugyanarról az IP-címről egy percen belül öt érvénytelen kísérlet történik, az 60 perces letiltást von maga után.

Korlátok

  • Botonként legfeljebb 5 aktív Bot Talk kulcs
  • Kulcsonként legfeljebb 60 kérés percenként (token bucket algoritmus, 60-as kapacitás, egyenletes újratöltés másodpercenként 1 tokennel). Létrehozáskor lefelé módosítható - állítson be alacsonyabb rateLimitPerMinute értéket, és a felső korlát lecsökken, az újratöltési sebesség pedig ezzel arányosan változik.
  • Legfeljebb 4000 karakteres üzenethossz
  • A kulcsonkénti egyidejű SSE-streamek számára a fiókjára vonatkozó korlátok érvényesek

Végpontok

POST /v1/chat

Üzenetet küld a botnak, és a teljes választ egyetlen JSON-válaszban kapja meg.

Kéréstörzs

{
  "message": "Hi, can you help me track my order?",
  "conversationId": "550e8400-e29b-41d4-a716-446655440000",
  "metadata": {"userEmail": "alice@example.com"}
}
  • message - kötelező karakterlánc, legfeljebb 4000 karakter.
  • conversationId - opcionális UUID. Hagyja el új beszélgetéshez; használja újra a szerver által korábban visszaadott értéket a meglévőhöz való hozzáfűzéshez.
  • metadata - opcionális objektum: {source, userName, userEmail, userPhone}. A userEmail a belső ügyfélazonosító származtatására is szolgál.

Választörzs (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": []
}
  • A message.role értéke mindig "assistant"; a message.content a teljes válasz.
  • A model annak a modellnek az azonosítója, amelyen a bot futott ennél a hívásnál.
  • A usage.creditsUsed tartalmazza a felhasználói üzenetet + a bot válaszát (jellemzően 2), valamint végrehajtott eszközhívásonként egy további kreditet.
  • Az actions felsorolja az ezen forduló során lefutott eszközvégrehajtásokat. Jelenleg csak function_call bejegyzések jelennek meg (a következő mezőkkel: type, name, status: "completed").

POST /v1/chat/stream

A /v1/chat streamelési változata. Content-Type: text/event-stream fejlécet ad vissza Server-Sent Events formátumban.

Kéréstörzs

Megegyezik a POST /v1/chat formátumával. A törzsben lévő stream jelző nem kötelező - ennek az útvonalnak a használata váltja ki az SSE-t.

Választörzs (SSE-események)

  • message.delta - tartalomtöredék { "content": "..." }. Ezekből több is érkezik a tokenek beérkezésekor.
  • action - eszközvégrehajtás { "type", "name", "status": "executing" }. Akkor kerül kiküldésre, amikor a bot függvényhívást indít.
  • message.done - lezáró esemény a következő mezőkkel: conversationId, model, usage, valamint (ha van) a befejezett actions lista.
  • error - akkor kerül elküldésre, ha a generálás meghiúsul; a stream ezt követően megszakad.

A kapcsolat fenntartását szolgáló SSE-megjegyzéseket (:keepalive) a rendszer 15 másodpercenként küldi a hosszú generálások során. Szerveroldali időkorlátok: 30 másodperc az első tokenre, streamenként összesen 120 másodperc.

Curl példa

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

Listázza a kulcsához kötött bot beszélgetéseit az összes forrásból (widget, WhatsApp, API stb.).

Lekérdezési paraméterek

  • limit - 1-100, alapértelmezett: 20. A tartományon kívüli értékek korlátozásra kerülnek.
  • cursor - az előző oldalon a nextCursor mezőben visszaadott érték. Az első oldalnál hagyja el.

Választörzs (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
}
  • A lastMessagePreview 100 karakterre van lerövidítve ... utótaggal.
  • A nextCursor értéke az utolsó oldalon null; adja át cursor értékként a következő lekéréséhez.

GET /v1/conversations/{conversation_id}

Teljes beszélgetési előzmény.

Választörzs (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"}
  ]
}

Csak a user és az assistant szerepkörök kerülnek visszaadásra; a belső system és az eszközüzenetek szűrésre kerülnek. 404 not_found_error hibát ad vissza, ha a beszélgetés nem a kulcsához kapcsolt bothoz tartozik.

A bot konfigurációjának vizsgálatához használja a Management API GET /v1/management/bots/{bot_id} végpontját egy Management kulccsal.

Sebességkorlátozási fejlécek

A sebességkorlátozási szakaszt elérő válaszok (azaz sikeres hitelesítés és IP-engedélyezési lista ellenőrzés után) a következőket tartalmazzák:

X-RateLimit-Limit: 60
X-RateLimit-Remaining: 57
X-RateLimit-Reset: 1715430000
  • X-RateLimit-Limit - az ehhez a híváshoz ténylegesen alkalmazott kulcsonkénti felső korlát (alapértelmezés szerint 60, vagy a beállított rateLimitPerMinute, ha az alacsonyabb).
  • X-RateLimit-Remaining - a bucketben közvetlenül a hívás után fennmaradó tokenek száma.
  • X-RateLimit-Reset - Unix epoch másodpercek, amikor a következő token elérhetővé válik (nem a teljes bucket visszaállítása; a bucket folyamatosan újratöltődik). Ha a bucket tele van, ez a jelenlegi idő.

A 429 rate_limit_exceeded válaszoknál a Retry-After is be van állítva, egész másodpercekben kifejezve, amíg legalább egy token fel nem szabadul.

A hitelesítés előtti hibák (401 missing_api_key, 401 invalid_api_key, 403 ip_blocked) és a 403 ip_not_whitelisted nem tartalmazzák az X-RateLimit-* fejléceket - a korlátozó ellenőrzése csak a hitelesítés és az IP-ellenőrzés sikere után történik meg.

Hibaformátum

Minden hiba egyetlen közös struktúrában jelenik meg:

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

Gyakori HTTP-kódok:

  • 400 invalid_request_error - hibásan formázott bemenet (kódok: invalid_parameter, unsupported_media_type)
  • 401 authentication_error - hiányzó kulcs (missing_api_key), ismeretlen kulcs (invalid_api_key) vagy visszavont kulcs (revoked_api_key)
  • 402 quota_exceeded_error - az üzenetkreditek elfogytak
  • 403 permission_error - letiltott IP (ip_blocked), az IP nem szerepel a kulcs engedélyezési listáján (ip_not_whitelisted), vagy a kulcstípus nem engedélyezi ezt a végpontot (key_type_not_allowed, insufficient_permissions)
  • 404 not_found_error - a beszélgetés nem ehhez a bothoz tartozik
  • 405 invalid_request_error (method_not_allowed) - helytelen HTTP-művelet az URL-en
  • 429 rate_limit_error - túl sok kérés (rate_limit_exceeded) vagy túl sok egyidejű stream (concurrent_streams_exceeded)
  • 500 api_error - belső hiba

Kapcsolódó témakörök

A fiókszintű műveletekhez (botok létrehozása, botok frissítése, használati adatok lekérése) tekintse meg a Management API dokumentációját.

Keresés az összes cikkbenKérdezze az agenst