Jak to funguje
- Přihlásíte se k odběru události
telephony.incoming(telefon) neboweb.incoming(widget). Obě jsou blokující webhooky: ThunderPhone před pokračováním hovoru čeká na vaši odpověď až 10 sekund. - ThunderPhone vám odešle
{call_id, from_number, to_number}(relace widgetu obsahují místo čísel pole specifická pro widget — viz schéma požadavku). - Váš server odpoví konfigurací agenta (prompt, hlas, produkt, nástroje). ThunderPhone tuto konfiguraci použije pro daný hovor.
- Pokud vrátíte
{}, dojde k vypršení časového limitu nebo k chybě, jako záloha se použije staticky přiřazený agent. Bezpečné výchozí nastavení.
Funguje shodně pro telefonní hovory (
telephony.incoming) i relace widgetu
(web.incoming), ať jsou doručovány do endpointu webhooku
nebo do staršího webhooku s jedinou adresou URL.1. Nakonfigurujte cíl webhooku
- Telefonní hovory
- Webový widget
Pro telefonní čísla přihlaste svůj endpoint k odběru Odpověď obsahuje jednorázový
telephony.incoming:secret — uložte jej; použijete ho
k ověření podpisu.2. Implementujte obslužnou funkci
Tři základní pravidla:- Ověřte podpis u každého požadavku (viz Ověření podpisů webhooků). Nevynechávejte to ani při vývoji — nastavte to správně jednou a znovu použijte.
- Odpovídejte rychle. Deset sekund je pevný limit a každá sekunda je pro volajícího ticho. V případě potřeby proveďte vyhledání v databázi, ale nevolejte následné LLM synchronně — pokud chcete dynamicky generovat prompty, předem je vypočítejte a uložte do mezipaměti.
- Čistě použijte záložní řešení. Každý neočekávaný stav by měl vrátit
{}, aby hovor převzal staticky přiřazený agent.
3. Schéma odpovědi
Tělo odpovědi přesně odpovídá schématu odpovědi na příchozí hovor. Běžně používaná pole:Pořadí mluvení pro jednotlivé hovory a
max_hold_seconds nejsou v odpovědi
webhooku k dispozici. Nastavte je u
agenta, na kterého odkazujete.Vzory
Kontext přihlášeného uživatele
Ve widgetech v režimu webhooku stránka návštěvníka již ví, kdo je. Zavolejte svůj webhook s parametrem řetězce dotazu, který SDK widgetu předá dál (?customer_id=123), a vyhledejte zákazníka na straně serveru.
Zavádění výzev pomocí A/B testování
Než to začnete implementovat ručně, všimněte si, že ThunderPhone má nativní funkci Experimenty (/dashboard/experiments a kartu A/B v nástroji pro tvorbu agentů), která
definuje varianty, rozděluje provoz a porovnává výsledky pro jednotlivé varianty —
webhook není potřeba.
Pokud přesto potřebujete řízení na straně webhooku: zahashujte call_id → segment;
pro 0..49 použijte výzvu A a pro 50..99 výzvu B. Zaznamenejte, který
segment jste vybrali, do vlastní databáze a později jej porovnejte se
známkou dokončeného hovoru.
Směrování podle času
Během pracovní doby → agent pro „živou podporu“; mimo pracovní dobu → agent pro „záznam vzkazu“. Ve vašem handleru stačí prosté přepnutí podlenew Date().getUTCHours().
Další kroky
Referenční dokumentace webhooku pro příchozí hovory
Přesná schémata požadavků a odpovědí včetně všech konfiguračních klíčů.
Ověření podpisů webhooků
Nastavte HMAC správně jednou; pak jej používejte všude.
Vytvoření integrace nástroje
Zkombinujte dynamické směrování s nástroji pro jednotlivé agenty.
Sémantika doručování
Opakované pokusy, řazení, časové limity.