Přidat/Upravit integrace¶

Stránka API Integrations vám umožňuje konfigurovat nové integrace nebo upravovat existující. Integrace propojují vašeho AI agent s externími službami a datovými zdroji voláním definovaných endpointů během konverzací.

**📝 Poznámka**

Stránka API Integrations se používá pouze pro správu, testování a logování vašich integrací. Pro použití v dialogu potřebujete použít modul Integration a propojit ho s vaším dialog flow. Viz 2️⃣ Použít integrace

1. Ruční přidání¶

Pro přidání nové integrace ručně klikněte na tlačítko ➕ Přidat v levém dolním rohu:

Zobrazí se formulář se čtyřmi záložkami:

Záložka Nastavení¶

Záložka Nastavení je místo, kde konfigurujete základní chování vaší API integrace - včetně metody požadavku, URL endpointu, hlaviček a volitelných JavaScript hooků pro pre-processing a post-processing.

Pole a možnosti¶

Název a popis Používají se pro identifikaci integrace ve vašem seznamu. Nemají vliv na chování.
Metoda Vyberte HTTP metodu: GET, POST, PUT, PATCH nebo DELETE.
URL URL endpointu, který bude váš agent volat.

💡

Můžete použít $context proměnné (paměť bota) přímo v URL. Například pokud zákazník poskytne číslo objednávky, můžete na něj odkazovat takto: https://api.yourdomain.com/orders/$user_order

(Za předpokladu, že $user_order bylo získáno dříve v dialog flow AI Agent)

Timeout Jak dlouho (v milisekundách) by měl agent čekat na odpověď, než volání selže a pokračuje v dialog flow bez výsledku. Vždy doporučujeme nakonfigurovat tento fallback v dialog flow pro případ selhání - můžete přesměrovat dialog na operátora apod.

**📝 Poznámka**

Voiceboty vyžadují rychlé odpovědi. Vyhněte se pomalým API nebo místo toho použijte asynchronní volání (viz stránka Používání integrací pro více detailů). U chatbota nezáleží na zpoždění sekundy nebo dvou.

Hlavičky Přidejte jakékoliv vlastní hlavičky vyžadované API (např. Authorization, Content-Type). Můžete použít $context proměnné, stejně jako v poli URL.
Pre-process (JavaScript)

Tato volitelná sekce vám umožňuje manipulovat s hodnotami kontextu před odesláním požadavku. Máte plný přístup k aktuálnímu kontextu pomocí objektu context (context.$my_variable) a můžete vrátit objekt pro přidání nebo aktualizaci hodnot.

Příklady použití:

Sloučení nebo vyčištění uživatelského vstupu před použitím v požadavku
Formátování dat nebo ID
Dynamické sestavení payloadů požadavků nebo hlaviček apod.
Post-process (JavaScript)

Spouští se po přijetí API odpovědi a namapování na $context proměnné (v záložce Mapping). K oběma můžete přistupovat pomocí objektu context (context.$mapped_variable).

Použijte pro:

Vytvoření odvozených proměnných
Převod hodnot do formátů, které váš bot potřebuje
Provedení lehké obchodní logiky

**ℹ️ Info**

Bloky Pre-process i Post-process používají JavaScript a běží ve stejném prostředí jako Lambda moduly v Dialozích. Viz dokumentace Lambda Module pro další informace.

Záložka Test¶

Záložka Test vám umožňuje simulovat skutečný požadavek na váš nakonfigurovaný endpoint, abyste mohli ověřit, že vše funguje správně před nasazením nebo použitím v živém dialog flow.

To je obzvláště užitečné pro:

Ladění formátování požadavků
Validaci struktury dat odpovědi
Kontrolu, zda se vaše pre-processing, hlavičky nebo namapované hodnoty kontextu chovají podle očekávání

Dodání testovacích dat¶

Většina API požadavků spoléhá na hodnoty $context jako číslo objednávky, e-mailová adresa nebo ID zákazníka. Pro odeslání platného testovacího požadavku musíte tyto hodnoty nejprve poskytnout.

Můžete to udělat dvěma způsoby:

Ruční vstup (2)

Přidejte $context proměnné jednu po druhé spolu s ukázkovými hodnotami.

Načtení z existující diskuze (1)

Zadejte Discussion ID existujícího chatu, hovoru nebo e-mailového vlákna (najdete ho na obrazovkách administrace Chat / Calls / Emails nebo na konci URL vybrané diskuze).

Systém automaticky načte všechny hodnoty kontextu z této diskuze.
Skvělé pro ladění a replikaci chování živého agent.

Jakmile je váš kontext načten, stiskněte tlačítko Odeslat požadavek pro odeslání požadavku. Uvidíte:

(1) Vaše namapované hodnoty kontextu (pokud jsou nakonfigurovány v záložce Mapping)
(2) Payload požadavku
(3) Surová API odpověď

Záložka Mapping¶

Záložka Mapping vám umožňuje vybrat, které hodnoty API odpovědi by měly být uloženy do $context proměnných, aby je váš agent mohl použít v odpovědích nebo podmínkách.

Obvykle nepotřebujete celou API odpověď. Chcete pouze konkrétní data jako stav objednávky, čas doručení nebo jméno zákazníka, aby byl váš bot chytřejší a dynamičtější.

**📝 Poznámka**

Než budete moci cokoliv mapovat, musíte odeslat testovací požadavek v záložce Test. Jakmile je odpověď přijata, objeví se v záložce Mapping a můžete vybrat, která pole mapovat.

Namapované hodnoty:

Jsou uloženy do $context (paměť vašeho AI Agent)
Mohou být použity v odpovědích bota
Mohou být použity v podmínkách (např. povolit zrušení objednávky pouze pokud je její stav "Zpracovává se")
Mohou být dále upraveny pomocí logiky post-process nebo lambda modulu

Jak nastavit mapping¶

Mapping podle stavového kódu (1)

Můžete definovat různé mappingy v závislosti na HTTP stavovém kódu odpovědi (např. 200, 404). Pokud nepotřebujete tuto úroveň kontroly, jednoduše použijte Výchozí mapping pro všechny odpovědi nebo ponechte jak je.

Náhled odpovědi (2)

Toto je struktura API odpovědi vrácené během vašeho posledního testu. Klikněte na ikonu ➕ vedle jakékoliv hodnoty pro její namapování do $context proměnné. Místo mapování můžete také zkontrolovat, zda je hodnota prázdná pomocí tlačítka Ø, které vytvoří boolean $context příznak (true nebo false).

Výstup + Prefix (3)

Seznam vpravo zobrazuje vaše aktuální pravidla mappingu.

Můžete nastavit prefix (např. $response, $order, $apiResult), který je přidán před každý název kontextu.

💡

Použijte jasný a unikátní prefix pro udržení organizovaných hodnot kontextu při použití více API.

Dynamické porty (4)

Každý modul Integration ("box" použitý, když propojíte vaši integraci s vaším dialog flow) obsahuje dva výchozí výstupy:

Success: požadavek úspěšně dokončen v nastaveném timeout období
Failure: požadavek selhal nebo vypršel timeout

Můžete také vytvořit vlastní výstupy (porty) jako např.:

Objednávka nenalezena → pokud $get_order_state Neexistuje
Objednávka doručena → pokud $get_order_state Se rovná "delivered"

**📝 Poznámka**

Podmínky v Dynamických portech jsou vyhodnocovány shora dolů. Takže v příkladu níže by se druhá podmínka Objednávka doručena nikdy nespustila, protože pokud se kontext $get_order_state rovná "delivered", znamená to také, že existuje a první port bude spuštěn.

Objednávka nalezena → $get_order_state kontext Existuje (jakákoliv hodnota je do něj namapována)

Objednávka doručena → $get_order_state Se rovná "delivered"

Záložka Log¶

Záložka Log poskytuje kompletní historii všech požadavků provedených přes tento endpoint, ať už to byly testovací požadavky nebo požadavky spuštěné během živých dialogů.

2. Import cURL¶

Můžete také importovat požadavek ve formátu cURL. Stále budete muset ručně nastavit mapping a v případě potřeby pre-/post-processing.