Használd a saját rendszered adatait egy munkafolyamatban

Mikor használd

Akkor használj API hívás lépést, ha a munkafolyamatnak olyasmire van szüksége, amit csak a saját rendszered tud vagy csinál: lekérdezni egy rendelést, ellenőrizni, hogy él-e egy előfizetés, vagy létrehozni egy rekordot, például egy visszaküldési kérelmet. A lépés meghívja a rendszeredet, kiveszi a válaszból a kért értékeket, a munkafolyamat többi része pedig megmutathatja őket, vagy elágazhat rajtuk.

Ez nem ugyanaz, mint az AI ügynök API eszközei a Márka → Tudás oldalon. Azoknál az AI ügynök maga dönti el válaszadás közben, hogy meghívja-e őket, és mikor. Az API hívás lépés mindig lefut, pontosan ott, ahova a munkafolyamatban tetted.

1. Add hozzá a lépést

Nyisd meg a munkafolyamatot, egy kártyán kattints a Lépés hozzáadása gombra, és válaszd az API hívás lépést a Lezárja a kártyát — az utolsó lépés, kártyánként egy csoportból. Mindig a kártyája utolsó lépése, és két kimenete van: Sikerült és Nem sikerült. Mindkettőre add hozzá a következő kártyát a + gombjával.

Ha a hívásnak előbb szüksége van valamire a látogatótól, például egy rendelésszámra, kérd el egy korábbi lépésben, és mentsd el a választ egy néven — lásd: Adatgyűjtés workflow-val.

2. Állítsd be a kérést

• Metódus — GET, POST, PUT, PATCH vagy DELETE.
• Cím — a teljes cím, https-sel kezdve. Olyan értékeket is tartalmazhat, amelyek a munkafolyamatnak már megvannak, például https://api.example.com/orders/{{ order_id }}; ezeket automatikusan kódoljuk. Az Itt használható értékek kártya felsorolja őket. Amíg a cím üres, a kártyán ez áll: Még nincs beállítva — add meg a címet, és a munkafolyamatot nem lehet bekapcsolni (lásd a 7. részt).
• Yaplet aláírás — a legegyszerűbb módja annak, hogy a saját rendszered számára igazold: a hívás a Yaplettől jön. Kapcsold be, és adj meg egy közös titkos kulcsot, amelyet a szervered is tárol. Így minden hívás egy Signature fejlécet küld a kulcs SHA-256 lenyomatával — ugyanazt a fejlécet, amelyet az AI API-eszközei is küldenek —, a szervered pedig összeveti a saját példánya lenyomatával. A kulcsot jelszóként kezeljük (lásd lent).
• Fejlécek — fejlécenként egy sor, a Fejléc hozzáadása gombbal. Minden titkos értéknél, például egy API-kulcsnál, kapcsold be a Jelszó kapcsolót.
• Törzs (GET-nél nincs) — a Mit küldjön alatt válaszd a Nincs törzs, a Mezők (JSON-ként küldve) vagy a Magam írom a JSON-t lehetőséget. Az értékeket automatikusan biztonságossá tesszük, a Content-Type: application/json fejlécet pedig hozzáadjuk, hacsak nem adsz meg sajátot.
• Várakozás legfeljebb (másodperc) — alapból 8, legfeljebb 30.

Ha egy fejléc, törzsmező vagy címparaméter értéke üresnek bizonyul, kimarad a kérésből.

Hogyan őrizzük a jelszavakat

Miután elmentetted a munkafolyamatot, a Jelszó kapcsolóval megjelölt fejlécnél csak ez látszik: mentve ••••, mellette egy Csere gomb. Az értéket a szervereinken tároljuk, és soha többé senkinek nem mutatjuk meg. Csak arra a webcímre küldjük el, amelyhez elmentetted: ha a címet máshova irányítod, a jelszót töröljük, és újra meg kell adnod. Ugyanezért a jelszóhoz a címet teljesen ki kell írni — értékek kerülhetnek az útvonalba és a lekérdezésbe, a domainnévbe viszont nem.

Az AI által vázlatként hagyott lépés

Ha a Vex, a dashboardod asszisztense épít neked egy munkafolyamatot, és a szükséges hívás a rendszeredben még nem létezik, az API hívás lépést cím nélkül teszi be. Ilyenkor a lépés panelje egy megjegyzést mutat — Mit kell tennie ennek a hívásnak (az AI írta) —, amely leírja a fejlesztődnek, mit kell megépítenie. Ha elkészült, a címet — és a közös titkos kulcsot vagy bármilyen jelszót — te magad írd be a lépésbe, soha ne az AI-val folytatott chatbe. Ha már nincs szükséged a megjegyzésre, az Eltávolítás gombbal törölheted. Bővebben: Munkafolyamat építése AI-val.

3. Olvasd ki az értékeket a válaszból

Az értékeket a panel A válaszból kiolvasott értékek részén veszed fel, az Érték hozzáadása gombbal, értékenként egy sort — legfeljebb 20-at:

• Hol van a válaszban — az érték útvonala. A pont egy szinttel mélyebbre visz, a [0] pedig egy lista első eleme: order.status, items[0].name. A betűknek, a kis- és nagybetűknek is egyezniük kell.
• Mentés így — a név, amellyel a későbbi lépések használják, például order_status. Csak betűk, számok és alulvonás.
• Típus — Szöveg, Szám, Igen / nem vagy Dátum. A Számot a Feltételekben nagyobb / kisebb alapon is összehasonlíthatod. Ha bizonytalan vagy, válaszd a Szöveget.

A rendszerednek Content-Type: application/json fejléccel kell válaszolnia; más válaszból egyetlen érték sem olvasható ki. A panel Példa megjelenítése gombja mutat egy mintaválaszt, és azt, hogy melyik útvonal mit olvas ki belőle.

4. Teszteld

A Teszt gomb azonnal meghívja a címet egy kitalált mintalátogatóval és azokkal a mintaértékekkel, amelyeket a kérés minden {{ … }} helyére beírsz. Megmutatja, hogy a hívás sikerült-e, a státuszt, hogy mennyi ideig tartott, magát a választ, és hogy melyik érték mire jött ki. Az a jelszó, amelyet beírtál, de még nem mentettél el, csak ehhez az egy teszthez használjuk, és nem tároljuk. A szervezeted percenként 10 tesztet futtathat.

5. Sikerült és Nem sikerült

A lépés a Nem sikerült ágon megy tovább, ha:

• a lépésnél be van kapcsolva a Csak azonosított látogatóknak beállítás, és a látogató nem azonosított — ilyenkor a rendszeredet meg sem hívjuk (lásd a 7. részt),
• elérte a hívási limitet: egy lépés percenként legfeljebb 60-szor hívja meg a rendszeredet, a szervezeted összes API hívás lépése együtt pedig legfeljebb 300-szor. E fölött a hívás kimarad, a Futások lapon pedig ez áll: „elérte a limitet — nem hívtuk meg”,
• a rendszered hibastátusszal válaszol,
• nem válaszol az időkorláton belül,
• a cím nem engedélyezett — például sima http, vagy egy belső hálózaton lévő cím,
• a válasz nagyobb 5 MB-nál,
• egy kiolvasott érték hiányzik vagy üres a válaszban (például null), vagy nem illik a választott típushoz. Kivétel a Nem kötelező jelölésű érték: ha a válaszból kimarad, egyszerűen üres marad, és a lépés a Sikerült ágon megy tovább. Olyasmire való, amit a rendszered csak néha küld, például egy jelzőre, amely szerint egy ügyintézőnek kell átvennie a beszélgetést.

Egy GET kérést időtúllépés, hálózati hiba vagy szerverhiba után még egyszer megpróbálunk. A többi metódust soha nem ismételjük meg, mert egy második próbálkozás kétszer is megváltoztathatna valamit.

A szerkesztő csak a Sikerült utáni kártyákon kínálja fel az értékeket. Bármi is az ok, ha a Nem sikerült ág után nincs kártya, a látogató ezt kapja: „Hiba történt a kérésed feldolgozása során. Egy ügyintéző hamarosan segít.”, a beszélgetés pedig a csapatodhoz kerül. Ha másképp kezelnéd, adj saját kártyát a Nem sikerült ágra (a + gombjával).

A munkafolyamat Futások lapja minden hívást megmutat: a státuszt, a próbálkozásokat, azt, hogy mely értékek hiányoztak, és ha gond volt, a válasz elejét.

6. Használd az értékeket

A Sikerült után minden későbbi lépés használhatja az értékeket. Írd be így: {{ order_status }} az Üzenet írása lépésbe, egy Link megnyitása címébe, az Ügyintéző kérése megjegyzésébe, a Küldés VEX AI-nak lépésbe, egy űrlap előkitöltésébe vagy egy másik API hívás lépésbe — vagy válaszd ki az értéket egy Feltételek szabályban. A válaszból semmi nem jut el a látogatóhoz, hacsak egy lépés ki nem írja.

7. Biztonság

• Csak https. A sima http hívást elutasítjuk.
• Cím nélkül nincs bekapcsolás. Amíg bármelyik API hívás lépésnek nincs címe, a szerkesztő Közzététel gombja és a Munkafolyamatok lista Aktív kapcsolója is elutasítja a kérést, ezzel az angol üzenettel: „Fill in the address of every Call an API step before switching this workflow on.” (Add meg minden API hívás lépés címét, mielőtt bekapcsolod ezt a munkafolyamatot.) Egy már bekapcsolt munkafolyamat mentését is elutasítjuk: „Fill in the address of every Call an API step before saving — a switched-on workflow cannot have a Call an API step without an address.” (Mentés előtt add meg minden API hívás lépés címét — egy bekapcsolt munkafolyamatban nem lehet cím nélküli API hívás lépés.) A kikapcsolt munkafolyamat a szokott módon menthető, így egy vázlatlépés nyugodtan várhat a címére.
• A hívást senki nem hagyja jóvá. Abban a pillanatban lefut, amikor a munkafolyamat eléri a lépést, a látogató megkérdezése nélkül. A felhasználó mondja triggernél ráadásul maga az AI ügynök indítja el a munkafolyamatot. Mielőtt bármit megváltoztatnál — rendelést törölnél, címet módosítanál —, tegyél be egy Gombok lépést, amely megerősítést kér a látogatótól, és csak az „Igen” kártyáról hívd a rendszeredet.
• Csak a külső azonosító ellenőrzött. A {{ external_id }} az a felhasználói azonosító, amelyet a weboldalad aláír, amikor azonosít egy bejelentkezett felhasználót (lásd: Azonosítsd a bejelentkezett felhasználóidat egyedi adatokkal). Minden más — név, e-mail cím, a látogató válaszai — a böngészőjéből jön, és kitalálható. Soha ne engedd, hogy a rendszered csak azért mutassa meg vagy módosítsa valakinek az adatait, mert egyezik egy név vagy egy e-mail cím.
• Csak azonosított látogatóknak. Ha ezt a lépés paneljén bekapcsolod, a hívás csak azoknál a látogatóknál történik meg, akiket a weboldalad a Yaplet.identify segítségével bejelentkeztetett, a weboldalad chat widgetjében. Mindenki más a lépés Nem sikerült kimenetén megy tovább, és a rendszeredet nem hívjuk meg. A Facebookról, Instagramról, e-mailben és telefonon érkezők soha nem számítanak azonosítottnak, mert a feladó és a telefonszám hamisítható. Akkor hasznos, ha egy mindenkinek nyitott munkafolyamatban van egyetlen érzékeny hívás: a munkafolyamat többi része minden látogatónak lefut, a Nem sikerült ágon lévő kártya pedig megkérheti őket, hogy jelentkezzenek be. Alapból ki van kapcsolva. Ha az egész munkafolyamatot csak azonosított látogatóknak szánod, inkább az Akkor indul, amikor kártyán kapcsold be ugyanezt a beállítást.
• Minden hívásnak saját azonosítója van. Minden hívás küld egy X-Yaplet-Call-Id fejlécet egy egyedi azonosítóval. Ha egy GET kérést újra elküldünk, az azonosító ugyanaz marad, így a rendszered felismeri az ismétlést, és figyelmen kívül hagyhatja, ahelyett hogy kétszer csinálná meg ugyanazt.
• A másolatok viszik a jelszavakat. A Duplikálás és a Másolás másik márkába… a munkafolyamattal együtt az elmentett jelszavakat is átmásolja.

8. Telefonhívásokon

A lépés a hangügyintéző által fogadott hívásokon is lefut. Ott legfeljebb 4 másodpercet vár, bármit állítasz be, és csak egyszer próbálkozik. Ha nem sikerül, és a Nem sikerült ág után nincs kártya, a hívó egy rövid bocsánatkérést hall („Sajnálom, ezt most nem tudom elintézni.”), ahelyett hogy a csapatodhoz kerülne.

Következő lépés

Hogy hol fut még egy munkafolyamat, itt olvashatod: Hol futhat egy munkafolyamat. Az eredményeket egy megjegyzésben adhatod át a csapatodnak: Átadás workflow-ból emberi ügyintézőnek. Magáról a szerkesztőről a Folyamatszerkesztő dokumentációban olvashatsz.