1️⃣ Přidat/Upravit integrace

Stránka API Integrations umožňuje konfigurovat nové integrace nebo upravovat stávající. Integrace propojují vašeho AI agenta se službami a datovými zdroji prostřednictvím volání definovaných endpointů během konverzací.

1. Přidat ručně

Chcete-li přidat novou integraci, 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í

Na záložce Nastavení konfigurujete základní funkce vaší API integrace - včetně metody požadavku, URL endpointu, hlaviček a volitelných JavaScriptových háčků pro před- a po-procesování.

Pole a volby

• Název a Popis
  Slouží k identifikaci integrace ve vašem seznamu. Nemá žádný vliv na funkce.

• Metoda
  Vyberte metodu HTTP: GET, POST, PUT, PATCH nebo DELETE.

• URL
  URL endpointu, který váš agent zavolá.

• Časový limit
  Délka (v milisekundách), kterou má agent čekat na odpověď, než požadavek selže a dialogový tok bude pokračovat bez výsledku. Vždy doporučujeme nastavit tuto alternativu v dialogovém toku pro případ selhání - například přesměrování dialogu na operátora apod.

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

• Před-proces (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 prostřednictvím objektu context (context.$my_variable) a můžete vrátit objekt pro přidání nebo aktualizaci hodnot.

Příklady využití:

• Sloučit nebo vyčistit uživatelský vstup před jeho použitím v požadavku

• Formátovat data nebo ID

• Dynamicky sestavovat obsah požadavků nebo hlavičky atd.

return {
  $full_name: context.$first_name + ' ' + context.$last_name
};

• Post-process (JavaScript)

Prováděno po přijetí odpovědi API a mapování na proměnné $context (v kartě Mapping). Můžete přistupovat k oběma pomocí objektu context (context.$mapped_variable).

Použijte toto k:

• Vytvoření odvozených proměnných

• Převod hodnot do formátů, které váš bot potřebuje

• Provádění lehkého obchodního logiky

return {
  $readable_date: new Date(context.$response_timestamp).toLocaleDateString()
};

Testovací karta

Karta Test umožňuje simulovat skutečný požadavek na nakonfigurovaný koncový bod, aby jste ověřili, že vše správně funguje před jeho nasazením nebo použitím v živém dialogovém toku.

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

• Ladění formátování požadavků

• Ověřování struktury dat odpovědi

• Kontrola, zda vaše předzpracování, hlavičky nebo mapované hodnoty kontextu fungují podle očekávání

Dodávání testovacích dat

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

To můžete provést dvěma způsoby:

• Manuální zadání (2)

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

• Načíst z existující diskuze (1)

Uveďte ID diskuze pro existující chatovací, hlasový nebo e-mailový vlákno (najdete v administraci Chaty / Hovory / E-maily nebo na konci URL adresy 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 agenta.

Jakmile je váš kontext načten, stiskněte tlačítko Odeslat požadavek k odeslání požadavku. Budete moci vidět:

• (1) Vaše mapované kontextové hodnoty (pokud jsou nastaveny na kartě Mapování)

• (2) Požadavek payload

• (3) Surová odpověď API

Režim Mapování

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

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

Mapované hodnoty:

• Jsou uloženy do $context (paměti vašeho AI Agenta)

• Mohou být použity v odpovědích bota

• Mohou být použity v podmínkách (např. umožnit zrušení objednávky pouze pokud její stav je „Zpracovává se“)

• Mohou být dále upraveny pomocí logiky post-process nebo modulu lambda

Jak nastavit mapovaní

Mapování podle kódu stavu (1)

Můžete definovat různá mapování v závislosti na kódu stavu odpovědi HTTP (např. 200, 404).
Pokud takovou úroveň kontroly nepotřebujete, použijte jednoduše Výchozí mapování pro všechny odpovědi nebo ponechejte jako je.

Náhled odpovědi (2)

Toto je struktura odpovědi API vrácená během vašeho posledního testu.
Klikněte na ikonu ➕ vedle jakékoli hodnoty a namapujte ji na proměnnou $context.
Namísto mapování můžete také ověřit, zda je hodnota prázdná, pomocí tlačítka Ø, což vytvoří logickou $context proměnnou (true nebo false).

Výstup + prefix (3)

Seznam napravo ukazuje vaše aktuální pravidla mapování.

Můžete nastavit prefix (např. $response, $order, $apiResult), kterého je přidána k každému názvu kontextu.

Dynamické porty (4)

Každý Modul Integrace („krabička“, kterou použijete při připojení integrace do vašeho dialogového toku) obsahuje dva výchozí výstupy:

• Úspěch: požadavek úspěšně dokončen v nastavené době čekání

• Neúspěch: požadavek selhal nebo časový limit vypršel

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

• Objednávka nenalezena → pokud $get_order_state Neexistuje

• Objednávka doručena → pokud $get_order_state Je rovna "doručeno"

Karta Logy

Karta Logy poskytuje kompletní historii všech požadavků provedených prostřednictvím tohoto koncového bodu, ať už se jedná o testovací požadavky nebo požadavky spuštěné během živých dialogů.

2. Importovat cURL

Můžete také importovat požadavek ve formátu cURL. Stále však budete muset ručně nastavit mapování a pokud je potřeba, tak před-/po-zpracování.