Webhooky

This post is also available in: Angličtina Polský

Využijte ohromné analytické schopnosti Samby pro segmentaci vašich zákazníků a pomocí webhooků ji napojte na API jakékoli aplikace třetí strany. Samba podle nastavené logiky ve Flow kampani v okamžik jejího vyhodnocení odešle HTTP požadavek, jehož obsahem mohou být libovolná data vašich zákazníků. Můžete tak snadno např. do vašeho kontaktního centra odesílat údaje důležitých zákazníků, kteří dosud nezareagovali na retenční e-mailovou kampaň, a spustit pro ně telefonickou kampaň.

Webhook funguje jako ostatní kanály ve Flow kampani, tj. zpracuje všechny zákazníky, kteří do něj dotečou z ostatních uzlů na něj napojených. V nastavení webhooku si pak můžete zvolit nejen adresu API, ale také detailně definovat formát požadavku, jak mají být data přes API odeslána.

Podrobnosti k účtování této funkce naleznete v článku Platební plány.

Aktivace služeb

V případě zájmu o aktivaci této služby nás prosím kontaktujte na sales@samba.ai.

Nastavení webhooku

Ve Flow kampani vyberte z nabídky vpravo uzel Webhook.

Základní nastavení

V nastavení webhooku si jej můžete pro snazší správu kampaně pojmenovat, případně lze jeho aktivaci jednoduše vypnout pomocí přepínače.

Endpoint

Zvolte metodu pro HTTP požadavek, na výběr máte mezi GET, POST, PUT, PATCH, DELETE.

Do pole URL požadavku vložte validní adresu pro API spojení včetně protokolu (http/https).

Autentizace

Pro zabezpečení komunikace můžete využít jednu z nabízených možností – Bez autentizace, Základní autentizace ( jméno + heslo ) nebo Bearer Token
Do vlastní hlavičky můžete také vložit jakýkoli další údaj ve formě Název + Hodnota.

 

Handlebars v hlavičce

Také v hlavičce můžete používat konstrukce Handlebars.js stejně jako v těle požadavku včetně dynamickým proměnných.

Pre-request

Pre-request představuje fázi, během níž se provádí určité operace před samotným hlavním požadavkem v rámci uzlu webhooku.

Během pre-requestu může být zasílán samostatný požadavek na jiný server nebo službu, a jeho odpověď pak může být využita pro následnou autentizaci a konfiguraci vlastních hlaviček pro hlavní požadavek, například při využití autentizace pomocí Bearer Tokenu.

Kopírování odpovědi Pre-requestu

Odpověď Pre-Requestu je možné pomocí tlačítka „Kopírovat odpověď pre-requestu do schránky“  zkopírovat jako merge tag a vložit do vlastních hlaviček v následujícím formátu: {{ dynamic.[0] }}. Tento postup umožňuje získávat konkrétní informace z odpovědi a dynamicky je využít v připravovaných hlavičkách pro další požadavek.

Například pokud odpověď obsahuje token a expirační datum v tomto formátu

{"token": "this is the current token value, "expiration": "2024-01-10T19:21:46.385Z" }

tak můžeme pomocí tečkové notace {{ dynamic.[0].token }} získat aktuální hodnotu tokenu a vložit ji do nastavení vlastních hlaviček pro hlavní požadavek.
Více o tečkových notacích se můžete dočíst v naší dokumentaci.

Nastavení Pre-requestu

Nastavení Pre-requestu se v ničem neliší od nastavení hlavního požadavku, tedy zvolíte metodu požadavku a vložíte validní adresu pro API spojení včetně protokolu (http/https).
Následně zvolíte vhodnou Autentizaci a vyplníte datový obsah, kterému se budeme podrobněji věnovat níže v tomto článku.

Cachování odpovědi

Cachování odpovědi přináší možnost ovlivnit frekvenci provedení pre-requestu. Tím určujete, jak často se má tento předchozí požadavek vykonávat. Během tohoto období se pro hlavní požadavek využívá poslední uložená odpověď.
Cachování odpovědi doporučujeme využívat. Jeho zakázání může mít významný dopad na snížení výkonu jak na straně rozhraní API připojené služby, tak na straně Samby.

Datový obsah

Zde definujete formát, v jakém má být požadavek odeslán, a také se zde konstruuje tělo požadavku se zákaznickými daty.

Formát požadavku

Na výběr máte z těchto základních MIME typů: JSON, JSON stream, CSV a XML

JSON stream

Typ JSON stream je zpravidla nejběžnější způsob pro využití dávkového odesílání. Implementace v Sambě využívá konkrétně typ "application/json-seq", přičemž nedochází k navazování spojení pro průběžné odesílání jednotlivých json souborů, nýbrž se celý požadavek posílá najednou jakožto stream jsonů.

Pokud potřebujete zvolit jiný typ, který nenajdete v základním výběru, vyberte prosím možnost Vlastní a do vstupního pole napište požadovaný typ, např.

  • text/plain

  • multipart/form-data

  • application/x-www-form-urlencoded

Dávkové odesílání

Dávkové odesílání umožňuje efektivní komunikaci s API tak, aby nemusel být každý jednotlivý zákazník odesílán v samostatném požadavku. V rámci dávkového odesílání místo toho Samba odešle najednou více zákazníků v jednom požadavku, čímž minimalizuje počet spojení s třetí stranou. Maximálně lze v jedné dávce odeslat až 1000 zákazníků.

Pro vytvoření korektního výsledného formátu může být potřeba každého zákazníka oddělit čárkou, novým řádkem či jiným symbolem. Viz příklad na využití funkce unless.

Doporučujeme

Velmi doporučujeme využívat dávkové odesílání vždy, když to API umožňuje. Pro větší objemy zákazníků v řádu tisíců je totiž zpravidla nežádoucí zahlcovat server tolika dotazy a může to vést ke značnému zpomalení nebo úplnému zablokování komunikace. Většina aplikací má přísná omezení na maximální počet spojení (tzv. rate limity) a díky využití dávkového odesílání se těmto omezením snáze vyhnete.

Tělo požadavku

Pro tvorbu těla požadavku se využívá šablonovací jazyk Handlebars.js.

Základní podoba požadavku musí vždy obsahovat iteraci přes zákazníky v následující podobě:

{{# each customers }}

...
{{/ each }}

Zákaznické atributy

Do požadavku lze vkládat následující zákaznické atributy formou merge tagů podobně jako do e-mailové šablony (jen pozor, že zápis se může od e-mailových merge tagů lišit). Pomocí Zkopírovat do schránky si příslušný merge tag jednoduše zkopírujete a poté pomocí Ctrl+V vložíte na požadované místo v těle požadavku.

  • Základní
    • ID: {{ id }}
    • E-mailová adresa: {{ email }}
    • Telefonní číslo: {{ phone }}
    • Křestní jméno: {{ firstName }}
    • Příjmení: {{ lastName }}
    • Datum registrace: {{ registeredOn }}
    • PSČ: {{ zipCode }}
  • Vlastní parametry
    • Zde naleznete všechny vlastní zákaznické parametry, které jsou uvedeny v zákaznickém feedu.
    • Merge tag: {{ lookup parameters "PARAMETER NAME" }}

Jednoduchá konstrukce těla požadavku obsahujícího zákaznické ID, e-mailovou adresu a vlastní parametr „Bonus body“ by vypadala takto:

{{# each customers }}
{
"customer_id": "{{ id }}",
"email_address": "{{ email }}",
"bonus_points": "{{ lookup parameters "Bonus body" }}"
}
{{/ each }}
Vkládání vlastních parametrů

Pro vkládání vlastních parametrů doporučujeme vždy využít rozhraní aplikace pro zkopírování merge tagu, protože Samba tak automaticky escapuje speciální znaky v názvu parametru.

Funkce Handlebars.js

K dispozici jsou základní funkce šablonovacího jazyka Handlebars.js a také vybrané pomocné funkce (tzv. helpers), které lze použít pro transformaci zákaznických atributů a požadavku jako takového. Dokumentaci k těmto funkcím naleznete v tomto článku

V rozhraní je k dispozici také interaktivní našeptávadlo dostupným funkcí a atributů.

Validace a testování

Pomocí Validovat datový obsah můžete ještě před pokusem o zavolání API prověřit, jestli máte vše, co se týče syntaxe, správně.

Pro odeslání testovacího požadavku s aktuálně nastaveným endpointem a formátem datového obsahu využijte tlačítko Odeslat testovací požadavek. Pokud odeslání proběhne úspěšně, zobrazí se vám také výstup s konkrétní odpovědí na odeslaný požadavek.

Vyhodnocení webhooků

Detailní výsledky s celkovým počtem volání API i počtem úspěšně a neúspěšně exportovaných zákazníků naleznete v detailu uzlu Webhook v režimu Flow kampaně Výsledky.

K dispozici máte tyto statistiky

  • Celkový počet volání = počet odeslaných požadavků na API.
    • Počet úspěšných volání
    • Počet neúspěšných volání
      • Jedná se o selhané požadavky vlivem nevalidního požadavku, překročení rate limitů třetí strany nebo jiné chyby.
  • Celkový počet zákazníků = počet zákazníků v odeslaných požadavcích na API. 
    • Počet úspěšných zákazníků
      • Jen tyto záznamy jsou účtovány.
    • Počet neúspěšných zákazníků

Např. 2 odeslané požadavky s dávkovým odesíláním o 1000 zákaznících znamenají 2 volání a celkem 2000 zákazníků.

Sumární výsledky můžete také nalézt v dashboardu u Flow kampaní.

 

This post is also available in: Angličtina Polský

Upraveno 5 června, 2024

Byl pro vás tento článek užitečný?

Mohlo by vás zajímat