Súgóközpont
Chat API

Bot Talk API

Utoljára frissítve:

Bot Talk API

A Bot Talk API egy REST API, amellyel egyetlen konkrét chatbottal beszélgethet a saját alkalmazásából - egyedi appokból, belső eszközökből vagy saját maga által épített automatizációkból. Ön létrehoz egy API-kulcsot a bot API lapján, 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 navigáljon 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) gombra.

Kiemelt API lap; a Create API Key az oldal tartalmában található

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

  1. A Create API Key (API-kulcs létrehozása) párbeszédpanelen adjon nevet a kulcsnak, opcionálisan állítson be egy IP-engedélyezési listát és egy sebességkorlátot (rate limit), válassza ki a jogosultságait, 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édpanelből. A szöveges kulcs csak egyszer jelenik meg.

A kulcs formátuma a következő: ck_abcdefghijklmnopqrstuvwxyz012345. Minden kulcs ahhoz az egy dothoz tartozik, így a kulccsal végrehajtott minden kérés azzal a bottal kommunikál - a botot a kulcs azonosítja, és soha nem jelenik meg az URL-ben.

  1. Futtassa le a szerveréről az alábbi curl-példát a kulcsával és egy rövid tesztüzenettel. Mentse el a visszaadott conversationId értékét, majd használja fel újra a folytatáshoz. Ellenőrizze a választ és a beszélgetést a bot Chatlogs (Csevegési naplók) lapján.

A ck_ kulcsokat a szerverén tárolja, ne a weboldal JavaScript-kódjában vagy mobilalkalmazás-csomagokban. A Conversations jogosultság hozzáférést biztosít a bot látogatókon átívelő, megőrzött beszélgetéseihez, így az alkalmazásának hitelesítenie kell minden egyes végfelhasználót, mielőtt visszaadná ezeket az adatokat. A kulcs visszavonásához használja a Revoke (Visszavonás) vagy Delete (Törlés) lehetőséget az API lapon; egyik művelet sem fedi fel újra a kulcs egyszerű szöveges formáját.

A kezdés előtt hozza létre és trénelje a chatbotját, valamint ellenőrizze, hogy a fiókja tartalmaz-e API-hozzáférést, és rendelkezik-e üzenetkreditekkel.

Alap URL

https://api.chatlab.com/aichat

A jelen cikkben szereplő összes végpont ehhez az alap URL-hez viszonyított.

Kulcsjogosultságok

Minden kulcs rendelkezik az alábbi jogosultságok 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 jogosultságokat Chat és Conversations jelvényekként jeleníti meg.

Hitelesítés

Minden kérésben 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 választ eredményeznek. Ha ugyanarról az IP-címről egy percen belül 5 é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, 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, ekkor a felső korlát csökken, és az újratöltési sebesség ezzel arányosan skálázódik.
  • Maximális üzenethossz: 4 000 karakter
  • A kulcsonkénti egyidejű SSE-streamek számára a fiókjának korlátai é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ő szöveges mező (string), legfeljebb 4 000 karakter.
  • conversationId - opcionális UUID. Hagyja ki új beszélgetéshez; egy meglévő folytatásához használja fel újra a szerver által korábban visszaadott értéket.
  • metadata - opcionális objektum, amely a {source, userName, userEmail, userPhone} mezőket fogadja el. Jelenleg ebből csak a userEmail kerül felhasználásra az ügyfélazonosító származtatásához; a csatorna API-ként kerül rögzítésre. Ne hagyatkozzon arra, hogy a többi metadata mező elmentődik egy érdeklődői (lead) rekordba.

Választörzs (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": []
}
  • 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 ehhez a híváshoz futott.
  • A usage.creditsUsed jelenleg 2 kreditet jelez, plusz befejezett fordulónként egyet a jelentett eszközhívások után. Ez a válaszbeli számláló nem tartalmazza a modell-/kontextuskredit-szorzókat, és nem használható számlázási főkönyvként. A fiókfogyasztást illetően használja a Management API-használatot, és tekintse meg az üzenetkreditekről szóló cikket.
  • Az actions felsorolja az ebben a körben lefutott eszközvégrehajtásokat. Jelenleg csak function_call bejegyzések jelennek meg (a type, name, status: "completed" mezőkkel).

POST /v1/chat/stream

A /v1/chat streamelt változata. Content-Type: text/event-stream választ ad vissza Server-Sent Events formátumban.

Kéréstörzs

Ugyanaz a struktúra, mint a POST /v1/chat esetén. A törzsben nem kötelező a stream jelző - maga ennek az útvonalnak a használata váltja ki az SSE-t.

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

  • message.reset - elveti az aktuális válaszhoz eddig összegyűjtött szöveget, és újra elkezdi gyűjteni a deltákat. Ez akkor fordulhat elő, ha a generálás újraindul; mindkét verzió hozzáfűzése ismétlődő vagy felülírt választ eredményezne.
  • message.delta - tartalomtöredék { "content": "..." }. Ezekből több is érkezik a tokenek beérkezésével párhuzamosan.
  • action - eszközvégrehajtás { "type", "name", "status": "executing" }. Akkor kerül elküldésre, amikor a bot függvényhívást indít.
  • message.done - záró esemény a conversationId, model, usage adatokkal és (ha van) a befejezett actions listával.
  • error - akkor küldésre kerül, ha a generálás meghiúsul; a stream ezt követően lezárul.

Hosszabb generálások során 15 másodpercenként kapcsolatfenntartó SSE-megjegyzések (:keepalive) érkeznek. Szerveroldali időtúllépések: az első tokenre 30 másodperc, 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 kulcshoz rendelt bot beszélgetéseit minden forrásból (widget, WhatsApp, API stb.).

Lekérdezési paraméterek (Query parameters)

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

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 csonkítva egy ... végződéssel.
  • A nextCursor értéke null az utolsó oldalon; a következő lekéréséhez adja át cursor értékként.

GET /v1/conversations/{conversation_id}

A végpont által elérhetővé tett, megőrzött beszélgetési üzenetek.

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 eszközüzenetek ki vannak szűrve. 404 not_found_error hibát ad vissza, ha a beszélgetés nem a kulcshoz rendelt 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át-fejlécek (Rate limit headers)

A sebességkorlátozási szakaszt elérő válaszok (azaz a hitelesítés és az IP-engedélyezési lista ellenőrzése sikeres volt) az alábbiakat 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 konfigurált rateLimitPerMinute, ha alacsonyabb).
  • X-RateLimit-Remaining - a hívás után közvetlenül a bucketben maradt tokenek száma.
  • X-RateLimit-Reset - Unix-korszak szerinti 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). Amikor a bucket tele van, ez az aktuális időpont.

429 rate_limit_exceeded válaszok esetén a Retry-After is beállításra kerül, 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 hordozzák az X-RateLimit-* fejléceket - a korlátozó csak a sikeres hitelesítés és IP-ellenőrzések után lép működésbe.

Hibaformátum

Minden hiba egyetlen közös burkolóstruktúrát használ:

{
  "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ás formátumú bemenet (invalid_parameter)
  • 415 invalid_request_error - nem támogatott tartalomtípus (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 nincs 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) - nem megfelelő HTTP-ige 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ó anyagok

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

Keresés az összes cikkbenKérdezze az agenst