API eszközök

Hol találhatók az API eszközök

Nyisd meg a Márka → (a márkád) → Tudás oldalt, és válaszd a képernyő alsó felén az API eszközök fület. A fülön egy darabszám is látszik, így ránézésre tudod, hány eszköze van a márkának.

Minden sor mutatja az eszköz Név, Mikor használja, Módszer (GET vagy POST), Státusz — Aktív vagy Szüneteltetve — és Hozzáadva értékét. A sor menüje a Szerkesztés, az Engedélyezés vagy Szüneteltetés, és a Törlés műveletet kínálja.

Az eszközök a márkához tartoznak, a többi tudásával együtt. A létrehozásukhoz, szerkesztésükhöz, szüneteltetésükhöz és törlésükhöz egyaránt Vex AI jogosultság kell.

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ó — betűk, számok, aláhúzásjel és kötőjel, legfeljebb 64 karakter. A nevek összehasonlítása nem érzékeny a kis- és nagybetűkre, így egy márkánál nem lehet egyszerre get_order és Get_Order.
• 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, és mire ne használja
• Az eszközlista ezt a szöveget a Mikor használja oszlopban mutatja, mert valójában ez a dolga: az AI ebből dönti el, mikor hívja meg az eszközt. Azt a helyzetet írd le benne, amire az eszköz való, ne a mögötte lévő végpontot.
• Maradjon ennél a döntésnél. Egy egysoros utalás a válaszra belefér, de az, hogy hogyan mutassa be a visszakapott adatokat, a lenti Válaszkezelési utasítások mezőbe való — a leírást az AI minden körben elolvassa, akkor is, ha nem hívja meg az eszközt.
• 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."

Válaszkezelési utasítások Nem kötelező

• Szabályok a végpont válaszának bemutatásához: mely mezőket idézze és melyeket hagyja ki, mit jelentenek az egyes státuszkódok, mikor adja át a beszélgetést egy ügyintézőnek.
• Az AI ezt a szöveget a sikeres API-válasszal együtt kapja meg, sosem az eszköz leírásának részeként. A bemutatási szabályok így semmibe sem kerülnek azokban a körökben, amikor az eszköz nem fut, és pontosan azok mellé az adatok mellé érkeznek, amelyekre vonatkoznak.
• Mindenhol érvényes, ahol az eszköz fut: chat közben indított hívásnál, a látogató által beküldött űrlap utáni válaszban és telefonhívás közben is.
• Ha a hívás sikertelen, a Hibakezelés beállításai lépnek életbe, és ezek az utasítások nem kerülnek felhasználásra.
• Ha üresen hagyod, semmi sem változik — az AI ugyanúgy a válaszból dolgozik, mint eddig.
• Példa: "A statusText mezőt szó szerint idézd. A statusCode alapján dönts: SHIPPED = átadva a futárnak, ON_HOLD = add át ügyintézőnek. Soha ne találj ki kézbesítési dátumot."

Válasz formátuma

Válaszd ki, hogyan jelenjen meg az eszköz válasza a csevegésben:

Szöveg Alapértelmezett

• Az AI elolvassa a választ és a saját szavaival válaszol. Ezt használd fiókadatokhoz, rendelési állapothoz, elérhetőség-ellenőrzéshez — bármihez, amit az AI-nak társalogva kell elmagyaráznia.

Termékkártyák

• A válasz gazdag, vizuális termékkártyákként jelenik meg közvetlenül a csevegésben — kép, cím, ár és egy kattintható link. Tökéletes termékkereséshez, ajánlásokhoz vagy „mit árultok?” jellegű kérdésekhez, amelyek mögött egy élő katalógus- vagy készlet-API áll.

Ha a Termékkártyák lehetőséget választod, a végpontodnak egy products tömböt kell visszaadnia:

{
    "products": [
        {
            "title": "Barista Pro Espresso Machine",
            "price": "$649.00",
            "image": "https://example.com/img/espresso-pro.jpg",
            "url": "https://example.com/products/espresso-pro",
            "description": "15-bar pump, dual boiler, PID temperature control."
        }
    ]
}

Csak a title kötelező — minden más mező opcionális (egy kép vagy ár nélküli kártya is megjelenik). A mezőnevek rugalmasak, így általában egy meglévő katalógus-API-ra is ráirányíthatsz egy eszközt anélkül, hogy át kellene alakítanod a kimenetét. Ezek az aliasok mind elfogadottak:

A terméktömb a válasz legfelső szintjén is lehet, vagy a products, items, results, illetve data kulcs alatt.

Adj meg minden termékhez egy állandó id mezőt (vagy external_id, sku, illetve product_id mezőt), hogy a kártya megőrizze az azonosságát, amikor az eszköz újra lefut. Ha egyik sincs megadva, a Yaplet automatikusan generál egyet.

A Yaplethez közvetlenül feltöltött termékekről (nem a saját API-dból élőben lekért termékekről) lásd: AI adatok és termékek.

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 — csak betűk, számok és aláhúzásjel (az order_id és az orderId is jó), és az eszközön belül egyedinek kell lennie
• 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

A Key, a Question és a Description mindegyikét ki kell tölteni. Ha egy mezőből bármelyik hiányzik, az eszköz nem menthető, és a hibaüzenet megmutatja, melyik mezőről van szó. (A Required ettől eltérő beállítás — azt szabályozza, hogy a felhasználónak kötelező-e válaszolnia, nem azt, hogy neked ki kell-e töltened a mezőt.)

Ha a probléma olyan fülön van, amelyet éppen nem nézel, az ablak átugrik arra a fülre és ráállítja a kurzort a hibás mezőre, ahelyett hogy a Mentés gomb élettelennek tűnne.

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

Minden opcióhoz kell Label és Value is — ha bármelyik üresen marad, az eszköz szintén nem menthető.

Ű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: {{ email }}, {{ external_id }}, {{ last_url }} — a teljes lista lentebb
  • Felhasználói bevitel: {{ order_id }}, {{ plan_type }}
• Példa: https://api.yourcompany.com/customers?id={{ external_id }}&order={{ order_id }}

Az URL-be kerülő értékek automatikusan URL-kódolást kapnak, így egy & vagy ? karaktert tartalmazó név vagy azonosító egyetlen értékként megy át, és nem módosítja a kérést. A fejlécek és a kérés törzse változatlanul kerül elküldésre.

Látogatói változók

Ezek a látogató rekordjából jönnek. Amit egy adott látogatóról soha nem rögzítettünk, annak nincs értéke, és kimarad a kérésből — lásd Üres és hiányzó értékek lentebb.

Ugyanaz a változólista működik mindenhol: az élő hívásnál, amelyet az AI beszélgetés közben indít, a látogató űrlapbeküldése után indított hívásnál, és a Végpont tesztelése gombnál is.

Saját egyéni mezők

Bármi, amit a Yaplet.identify() hívásnak átadsz, és nem szerepel a fenti mezők között, egyéni adatként tárolódik, és custom_ előtaggal érhető el:

Yaplet.identify(
    "user_12345",
    {
        name: "Ada Lovelace",
        customData: { order_ref: "A-4417", tier: "gold" },
    },
    userHash, // HMAC of the user ID, computed on your server
);

Ebből {{ custom_order_ref }} és {{ custom_tier }} lesz.

Csak a legfelső szintű egyszerű értékekből (szöveg, szám, igaz/hamis) lesz változó — a beágyazott objektumok és listák kimaradnak. Legfeljebb 50 egyéni mező érhető el, mindegyik 512 karakterre vágva.

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

Üres és hiányzó értékek

Ha egy {{ placeholder }} mögött nincs érték — egy opcionális beviteli mezőt üresen hagyott a felhasználó, vagy egy látogatói mező soha nem lett beállítva —, az a rész teljesen kimarad a kérésből, ahelyett hogy üres karakterláncként vagy a undefined szövegként kerülne elküldésre:

• URL — az üres lekérdezési paraméterek eltávolításra kerülnek. A ?order={{ order_id }} egyszerűen eltűnik, ha az order_id-nak nincs értéke.
• Fejlécek — egy fejléc, amelynek értéke üresre oldódik fel, nem kerül elküldésre.
• Kérés törzs — egy törzs-mező, amely üresre oldódik fel, kimarad a JSON-ból.

Tervezd úgy a végpontodat, hogy ezeket a mezőket opcionálisként és esetlegesen hiányzóként kezelje. Azok az értékek, amelyeket a felhasználó megadott — beleértve a false és 0 értékeket is — mindig elküldésre kerülnek.

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

Meglévő eszköz szerkesztése

Egy eszköz szerkesztéséhez ugyanaz a Vex AI jogosultság kell, mint a létrehozásához, és minden szerkesztést pontosan ugyanúgy ellenőrzünk — a névre vonatkozó szabályokat, a timeoutot, az újrapróbálkozások számát és a sebességkorlátot mentéskor mind érvényesítjük és a megengedett tartományba szorítjuk.

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 márka többi tudásából.

Telefonhívás-specifikus viselkedés

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

• A márkának kell egy Vex AI ügynök. Híváson az API eszközeidet (és a forgatókönyv szerinti munkafolyamataidat) csak akkor kínáljuk fel a hangügyintézőnek, ha a márkának van Vex AI-ja is. Az a márka, amelynek van hangügyintézője, de nincs Vexe, továbbra is tud a márka tudásából válaszolni, de hívás közben nem tud API eszközt meghívni. Ha olyan márkához hozol létre hangügyintézőt, amelynek már van Vexe, a kettő automatikusan összekapcsolódik, így a legtöbb ügyfél sosem találkozik ezzel a korlátozással.
• 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
• A teszt ugyanabból a látogatói változólistából állítja össze a kérést, mint egy valódi hívás, így amit itt látsz, azt fogja a végpontod kapni
• A Termékkártyák eszközöknél a teszt azt is megerősíti, hány terméket észlelt, és előnézetet mutat a kártyákról — egy sikeres hívás, amely nem ad vissza felismerhető terméket, jelzésre kerül, így még éles használat előtt elkapod a hibás válaszformátumot

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 átalakítás szabályait az eszköz Válaszkezelési utasítások mezőjébe írd, ne a leírásába, így csak akkor jutnak el az AI-hoz, amikor van mit átalakítani.

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