Dokumentáció

Gyorsindítás

3 lépésben élesítheted az első chatbotodat:

Beágyazás

Egyetlen script-tag hozzáadásával megjelenik a chatbot-widget az oldaladon:

<script src="https://embed.chatautomata.hu/w.js?id=CHATBOT_ID" async></script>

A CHATBOT_ID-t a dashboard chatbot-szerkesztő oldalán találod.

Speciális beállítások

API Referencia

Alap URL: https://api.chatautomata.hu — minden végpont JSON-t fogad és ad vissza, kivéve az SSE stream-eket.

Chat

Chatbot kezelés

FAQ / Tudásbázis

Beszélgetések és Lead-ek

Webhook-ok

Rendszer

Publikus REST API — /api/v1 (API-kulccsal)

A szerver-szerver integrációhoz külön, stabil felület. Auth: Authorization: Bearer ca_live_… vagy X-API-Key (lásd Autentikáció). A :write végpontok api:write scope-ot igényelnek, a többi api:read-et.

Gépi leírás (OpenAPI 3.1) — importálható Postman/Insomnia-ba vagy SDK-generátorba: GET /api/v1/openapi.json

Példa — chatbotok lekérése (cURL)

curl https://api.chatautomata.hu/api/v1/chatbots \
  -H "Authorization: Bearer $CA_API_KEY"

Példa — tudásbázis-keresés (JavaScript)

const res = await fetch("https://api.chatautomata.hu/api/v1/knowledge/search", {
  method: "POST",
  headers: { "X-API-Key": process.env.CA_API_KEY, "content-type": "application/json" },
  body: JSON.stringify({ chatbot_id: "CHATBOT_UUID", query: "szállítási idő", limit: 5 }),
});
const { results } = await res.json();

Példa — tudásbázis bővítése (cURL, api:write)

curl -X POST https://api.chatautomata.hu/api/v1/knowledge \
  -H "Authorization: Bearer $CA_API_KEY" -H "content-type: application/json" \
  -d '{"chatbot_id":"CHATBOT_UUID","content":"A nyitvatartásunk H-P 9-17 óra között van...","title":"Nyitvatartás"}'

MCP (Model Context Protocol) — AI-asszisztensekhez

A platform natív MCP-szervert ad, amivel a Claude (és más MCP-kompatibilis kliensek) közvetlenül elérik a fiókod adatait és eszközeit. Csatlakozás: a kliensben add hozzá a https://api.chatautomata.hu/mcp URL-t — OAuth 2.1 + PKCE (Dynamic Client Registration) hitelesítéssel, a böngészőben engedélyezve. Eszközök közt: chatbot-, FAQ-, beszélgetés-, lead-kezelés, tudásbázis-keresés és -bővítés (mcp:read / mcp:write scope).

Autentikáció

A legtöbb API végpont Bearer JWT tokent vár az Authorization headerben:

Authorization: Bearer eyJhbGciOiJIUzI1NiIs...

A tokent a POST /v1/auth/login végponttól kapod:

POST /v1/auth/login
Content-Type: application/json

{
  "email": "pelda@ceg.hu",
  "password": "jelszo123"
}

// Válasz:
{
  "accessToken": "eyJhbG...",
  "refreshToken": "eyJhbG...",
  "user": { "id": "...", "email": "pelda@ceg.hu" }
}

Az access token 15 percig érvényes. A refresh token 7 napig — a POST /v1/auth/refresh végponttal megújítható.

Példa — hitelesített kérés (JavaScript)

const res = await fetch("https://api.chatautomata.hu/v1/chatbots", {
  headers: { "Authorization": "Bearer " + accessToken }
});
const { chatbots } = await res.json();

Példa — ugyanaz cURL-lel

curl https://api.chatautomata.hu/v1/chatbots \
  -H "Authorization: Bearer $TOKEN"

REST API-kulcsok (szerver-szerver integrációhoz)

Programozott (gép-gép) hozzáláshoz API-kulcsot hozhatsz létre a Beállítások → Fiók → REST API-kulcsok alatt. A teljes kulcs (ca_live_…) csak egyszer, létrehozáskor jelenik meg — utána már nem visszafejthető. A kulcsot a /api/v1 felületen használod, kétféleképp:

Authorization: Bearer ca_live_xxxxxxxx...
# vagy
X-API-Key: ca_live_xxxxxxxx...

Scope-ok: api:read (lekérdezés) és api:write (módosítás). Opcionálisan IP-engedélylista is megadható kulcsonként. Visszavonás bármikor a dashboardon — a kulcs azonnal érvénytelen.

curl https://api.chatautomata.hu/api/v1/chatbots \
  -H "Authorization: Bearer $CA_API_KEY"

Rate-limit: 120 kérés/perc/kulcs (X-RateLimit-* fejlécek). Ezen felül csomag-függő havi kvóta van (X-API-Quota-* fejlécek); túllépéskor 429 quota_exceeded. Az aktuális használat a GET /api/v1/me válaszában (usage).

Webhook-ok

A kimenő webhook-okat a dashboardon vagy a /v1/webhooks API-n regisztrálod. Minden kézbesítés egy HMAC-SHA256 aláírást és az alábbi fejléceket kapja:

POST https://a-te-url-ed/webhook
Content-Type: application/json
X-ChatAutomata-Signature: sha256=a1b2c3d4e5f6...
X-ChatAutomata-Event: lead.captured
X-ChatAutomata-Retry: 1

A törzs (body) JSON-formátuma:

{
  "event": "lead.captured",
  "timestamp": 1716652800000,
  "data": { ... }   // eseményfüggő adatok
}

Aláírás ellenőrzése

Számítsd ki a nyers kérés-törzsből a HMAC-SHA256(webhook_secret, raw_body) hex értéket, és hasonlítsd össze az X-ChatAutomata-Signature fejléc sha256= utáni részével (időállandó összehasonlítás ajánlott):

// Node.js (Express, express.raw a body-hoz)
import crypto from "node:crypto";

const sig = req.headers["x-chatautomata-signature"].split("=")[1];
const expected = crypto.createHmac("sha256", WEBHOOK_SECRET)
  .update(req.body)            // a NYERS body (Buffer/string)
  .digest("hex");
const ok = crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected));

Elérhető események

• lead.captured — Lead rögzítve (chat, flow vagy pre-chat űrlap)
• message.received — Látogatói üzenet érkezett
• conversation.ended — Beszélgetés lezárult (kézi lezárás vagy inaktivitás)
• conversation.assigned — Beszélgetés operátorhoz rendelve
• booking.created — Foglalás jött létre (AIBooking integráció)

Egy webhook feliratkozhat több eseményre, illetve a * minden eseményre. Kézbesítési hiba esetén 3× újrapróbálkozás (0/5/30 mp), a próbálkozások a dashboardon naplózva.

Widget testreszabás

A chatbot megjelenése 60+ beállítással finomhangolható a PATCH /v1/chatbots/:id végponton vagy a dashboard szerkesztőben:

Süti-hozzájárulás (GDPR)

A widget privacy by default elven működik: a látogatói analitika-események (GA4, Meta Pixel, TikTok — ha bekötötted az integrációk közt) csak akkor futnak le, ha a látogató hozzájárult a marketing/analitika sütikhez a TE oldaladon.

// elfogadáskor:
window.CAWidget.setConsent("analytics");

// visszavonáskor:
window.CAWidget.setConsent("");

<script>window.ChatAutomataConsent = "analytics";</script>
<script src="https://embed.chatautomata.hu/w.js?id=BOT_ID" async></script>

Rate limit-ek

Az API méltányos-használati korlátokkal véd a visszaélés ellen. A limit túllépésekor 429 Too Many Requests választ kapsz, Retry-After headerrel (másodperc).

A pontos havi üzenetkvótát a csomagod határozza meg (Ingyenes: 100/hó). BYOK-kulccsal a saját provider-kvótád érvényes, az üzenetszám csak statisztika.

Hibakódok

Minden hiba egységes JSON-formátumban érkezik:

{
  "error": "validation_error",
  "message": "A jelszó legalább 8 karakter legyen."
}

Tipp: a kliensed mindig a message mezőt jelenítse meg a felhasználónak (magyar, ember-olvasható), az error mezőt pedig programozott elágazáshoz használd.

Gyakori kérdések