API eszközök

Hogyan működnek az API eszközök

Amikor egy felhasználó kérdést tesz fel, az AI elemzi a beszélgetést és eldönti, hogy meghívjon-e egy API eszközt. Ha szükség van egy eszközre, az AI képes:

1. Közvetlen API hívásokat végezni statikus adatokhoz (nem szükséges felhasználói bevitel)
2. Űrlapokat megjeleníteni további információk begyűjtéséhez a felhasználóktól az API hívás előtt
3. Látogató adatokat automatikusan használni (név, email, csomag stb.)
4. Hibákat kecsesen kezelni tartalék stratégiákkal

Az első API eszközöd létrehozása

Alapbeállítások

Kezdd az eszközöd alapvető beállításaival:

Eszköz neve

• Egyedi azonosító (kisbetűk, csak aláhúzásjel)
• Példa: get_customer_data, check_order_status

Leírás

• Részletes magyarázat az AI számára (minimum 20 karakter)
• Tartalmazza: mit csinál az eszköz, mikor használja, válasz formátum
• Példa: "Lekéri az ügyfél előfizetési adatait. Használd, amikor a felhasználó a fiókjáról vagy csomagjáról kérdez. JSON-t ad vissza: {plan_name, billing_cycle, usage_limit, current_usage}. Formázd barátságos mondattá, mint A Pro csomagot használod (havi) és a korlátod 45%-át használtad el."

Dinamikus beviteli mezők

Adj hozzá interaktív űrlapokat, amelyek felhasználói bevitelt gyűjtenek az API hívás előtt:

Mező típusok

• Text: Egysoros bevitel (legördülő opciókkal is)
• Number: Numerikus bevitel (előre meghatározott opciókkal)
• Boolean: Igen/Nem kérdések egyéni címkékkel

Mező konfiguráció

• Key: Változó neve az API hívásokhoz (snake_case)
• Question: Amit a felhasználó lát
• Description: AI útmutatás az előre kitöltéshez
• Required: Kötelező-e a felhasználónak megadnia ezt az információt

Legördülő opciók Szöveg/numerikus mezőkhöz legördülő választásokat adhatsz:

• Label: Amit a felhasználók látnak (pl. "Prémium csomag")
• Value: Ami az API-nak küldődik (pl. "premium_plan")
• Multiple Selection: Több opció kiválasztásának engedélyezése

Űrlap megjelenítési mód

Szabályozd, mikor jelenjen meg az űrlap a felhasználóknak, illetve mikor kerüljön automatikusan beküldésre az AI által előre kitöltött értékek alapján:

Megjelenítési mód opciók

Mindig mutatja az űrlapot

• A látogatók mindig látják az űrlapot, még ha az AI előre ki is töltött értékeket
• A felhasználóknak manuálisan kell beküldeniük az űrlapot a folytatáshoz
• Legjobb: Kritikus információknál, amelyeket a felhasználóknak mindig át kell nézniük

Automatikus beküldés ha a kötelező mezők előre kitöltöttek

• Az űrlap megjelenítésének kihagyása, ha minden kötelező mező előre ki van töltve az AI által
• Az űrlap csak akkor jelenik meg, ha kötelező információ hiányzik
• Legjobb: A legtöbb esetben, ahol hatékonyságot szeretnél, de biztosítanod kell a kötelező adatokat

Automatikus beküldés ha minden mező előre kitöltött Alapértelmezett

• Az űrlap kihagyása csak akkor, ha MINDEN mező (kötelező és opcionális) előre ki van töltve
• Az űrlap megjelenítése, ha bármely mező üres
• Legjobb: Egyszerű űrlapokhoz, ahol maximális automatizálást szeretnél

Automatikus beküldés ha bármely mező előre kitöltött

• Az űrlap kihagyása, ha BÁRMELY mező előre ki van töltve az AI által
• Minden kötelező mezőnek továbbra is előre kitöltöttnek kell lennie a tényleges beküldéshez
• Legjobb: Rendelés azonosítás email cím vagy rendelési szám alapján

API konfiguráció

Konfiguráld, hogyan csatlakozik az eszközöd a külső rendszerekhez:

Végpont URL

• Az API végpont URL-ed
• Használd a {{ field }} szintaxist dinamikus adatok beillesztéséhez:
  • Látogató adatok: {{ name }}, {{ email }}, {{ plan }}, {{ external_id }}, {{ country }}, {{ phone }}
  • Felhasználói bevitel: {{ order_id }}, {{ plan_type }}
• Példa: https://api.yourcompany.com/customers?id={{ external_id }}&order={{ order_id }}

A {{ phone }} változó telefonálók esetén automatikusan ki van töltve (a hívó telefonszáma a kanonikus azonosító). Widget látogatóknál a látogatói rekordon tárolt értékre oldódik fel, vagy undefined-ra, ha még nem rögzítettünk telefonszámot az adott látogatóhoz.

HTTP metódus

• GET adatok lekéréséhez
• POST adatok küldéséhez vagy összetett lekérdezésekhez

Egyéni fejlécek

• Hitelesítési fejlécek, tartalomtípusok vagy API kulcsok hozzáadása
• Interpoláció támogatás dinamikus értékekhez

Kérés törzs (csak POST)

• JSON kulcs-érték párok POST kérésekhez
• Ugyanazt az interpolációs szintaxist támogatja, mint az URL-ek és fejlécek

Hitelesítés és biztonság

Biztonságos hitelesítés Minden kérés tartalmaz egy Signature fejlécet, amely a titkos kulcsod SHA-256 hash-ét tartalmazza. A szerverednek ezt kell ellenőriznie a kérések hitelesítéséhez.

// Példa ellenőrzés az API-dban
const crypto = require('crypto');
const expectedSignature = crypto.createHash('sha256').update(YOUR_SECRET_KEY).digest('hex');

if (request.headers.signature !== expectedSignature) {
    return res.status(401).json({ error: 'Invalid signature' });
}

Titkos kulcs kezelés

• Generálj egyedi kulcsokat minden eszközhöz
• Rendszeresen rotáld a kulcsokat a biztonság érdekében
• Soha ne tedd közzé a kulcsokat kliens oldali kódban

Megbízhatósági beállítások

Biztosítsd, hogy eszközeid megbízhatóak legyenek éles környezetben:

Timeout

• Mennyi ideig várakozzon API válaszokra (1 000-30 000ms)
• Alapértelmezett: 5 000ms

Újrapróbálkozási logika

• Újrapróbálkozási kísérletek száma hiba esetén (0-5)
• Exponenciális visszalépést használ

Sebességkorlátozás

• Maximális hívások percenként (0-100)
• Megakadályozza az API kvóta kimerülését

Hibakezelés

Határozd meg, mi történjen, ha az API hívások sikertelenek:

Hiba műveletek

Egyéni üzenet megjelenítése Felhasználóbarát üzenet megjelenítése, ha az API nem elérhető.

Emberi ügyintéző kérése Eszkaláció emberi támogatásra egyéni üzenettel. Telefonhívás esetén nincs élő ügyintézőhöz kapcsolás — a beállított üzenetet a hívó hangban hallja, és a hívás folytatódik, akárcsak az "Egyéni üzenet megjelenítése" esetén.

Visszaállás más kontextusra A beszélgetés folytatása a meglévő dokumentumok és GYIK használatával.

Telefonhívás-specifikus viselkedés

Telefonhíváson néhány dolog másképp működik, mint a widgetben:

• Nincs űrlap megjelenítés. Ha az eszköz beviteli mezői nincsenek mind előre kitöltve, az AI hangban kérdezi meg a hívótól a hiányzó értékeket, mint Facebook/Instagram esetén. Telefonon nincs vizuális űrlap.
• Szigorúbb timeout. A telefonálás 4 másodpercre korlátozza az API timeoutot (a widget alapértelmezett 5 másodperc helyett). A lassú API-k SLA szerint nem voice-kompatibilisek — gyors handlereket írj, vagy számíts arra, hogy közben hangzik el a kitöltőszöveg ("Egy pillanat.").
• REQUEST_AGENT lefokozódik SHOW_MESSAGE-re. Telefonhíváson nincs élő ügyintézőhöz kapcsolás, így a sikertelenség- vagy API-flag-eszkaláció egyszerűen felolvassa a beállított üzenetet, és a beszélgetés folytatódik.

Hiba forgatókönyvek

• Hálózati timeout → Újrapróbálkozás a beállításaid alapján
• API hibák (4xx/5xx) → Hiba művelet aktiválása
• Érvénytelen válaszok → Tartalék viselkedés
• Sebességkorlát túllépés → Sebességkorlátozási beállítások tiszteletben tartása

Eszközök tesztelése

Élesítés előtt alaposan teszteld az API eszközeidet:

Végpont tesztelése gomb

• Kattints a "Végpont tesztelése" gombra a konfiguráció ellenőrzéséhez
• Beviteli mezőkkel rendelkező eszközökhöz adj meg teszt értékeket
• Tekintsd meg a tényleges API választ a helyes adatformátum ellenőrzéséhez

Teszt forgatókönyvek

• Sikeres esetek: Érvényes kérések a várt adatokkal
• Hibakezelés: Érvénytelen bemenetek, timeoutok, API hibák
• Szélsőséges esetek: Hiányzó adatok, szokatlan válaszok
• Hitelesítés: Aláírás ellenőrzés működésének vizsgálata

Legjobb gyakorlatok

Haladó használat

Automatikus ügyintéző kérés

Az API-d programozottan kérhet emberi ügyintéző segítséget speciális jelzők belefoglalásával a válaszba:

Ügyintéző kérés aktiválása Vedd bele a {"request_agent": true} részt az API válaszodba, amikor a rendszered megállapítja, hogy nem tudja teljesíteni a felhasználó kérését és emberi segítségre van szükség.

{
  "error": "Account requires manual review",
  "request_agent": true,
  "request_agent_message": "Your account needs special attention from our support team."
}

Egyéni üzenetek Opcionálisan vedd bele a request_agent_message részt egyéni üzenet megadásához, amelyet az AI küld el az ügyintézőhöz való csatlakozás előtt:

{
  "status": "requires_approval",
  "request_agent": true,
  "request_agent_message": "Your request needs approval from our team. Let me connect you with someone who can help."
}

Felhasználási esetek

• Összetett fiók problémák, amelyek manuális áttekintést igényelnek
• Nagy értékű tranzakciók, amelyekhez ellenőrzés szükséges
• Technikai problémák az automatizált kezelés határain túl
• Eszkaláció üzleti szabályok vagy kockázatértékelés alapján

Összetett munkafolyamatok

Láncolj össze több eszközt úgy, hogy az AI különböző eszközöket hív meg a felhasználói válaszok és korábbi API eredmények alapján.

Feltételes logika

Tervezd az API-dat különböző forgatókönyvek kezelésére a bemeneti paraméterek alapján, lehetővé téve, hogy egy eszköz több felhasználási esetet szolgáljon ki.

Adat transzformáció

Használd az AI természetes nyelvi képességeit a nyers API adatok beszélgetéses válaszokká alakításához.

Az API eszközök áthidalják a statikus tudás és a dinamikus, valós idejű adatok közötti szakadékot, hatékony felületté téve a chatbotodat az üzleti rendszereidhez. Megfelelő konfigurálással és teszteléssel személyre szabott, pontos válaszokat nyújthatnak, amelyeket a statikus kontextus önmagában nem képes elérni.