Skip to main content
Ve výchozím nastavení má každé telefonní číslo a každý veřejný klíč přiřazeného statického agenta. Když potřebujete přizpůsobení pro každého volajícího nebo pro každého návštěvníka — směrování VIP, kontext přihlášeného uživatele, A/B testy promptů — přepněte do režimu webhooku a nechte rozhodnutí na svém serveru.

Jak to funguje

  1. Přihlásíte se k odběru události telephony.incoming (telefon) nebo web.incoming (widget). Obě jsou blokující webhooky: ThunderPhone před pokračováním hovoru čeká na vaši odpověď až 10 sekund.
  2. 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).
  3. Váš server odpoví konfigurací agenta (prompt, hlas, produkt, nástroje). ThunderPhone tuto konfiguraci použije pro daný hovor.
  4. 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

Pro telefonní čísla přihlaste svůj endpoint k odběru telephony.incoming:
Odpověď obsahuje jednorázový 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í podle new 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.