Jak to działa
- Subskrybujesz zdarzenie
telephony.incoming(telefon) lubweb.incoming(widżet). Oba są blokującymi webhookami: ThunderPhone czeka do 10 sekund na Twoją odpowiedź, zanim kontynuuje połączenie. - ThunderPhone wysyła
{call_id, from_number, to_number}(sesje widżetu zawierają pola specyficzne dla widżetu zamiast numerów — zobacz schemat żądania). - Twój serwer odpowiada konfiguracją agenta (prompt, głos, produkt, narzędzia). ThunderPhone używa tej konfiguracji podczas połączenia.
- Jeśli zwrócisz
{}, przekroczysz limit czasu lub wystąpi błąd, jako rozwiązanie awaryjne zostanie użyty statycznie przypisany agent. Bezpieczne ustawienie domyślne.
Działa identycznie dla połączeń telefonicznych (
telephony.incoming) i sesji
widżetu (web.incoming), niezależnie od tego, czy są dostarczane do punktu końcowego webhooka,
czy do starszego webhooka z pojedynczym adresem URL.1. Skonfiguruj miejsce docelowe webhooka
- Połączenia telefoniczne
- Widżet internetowy
W przypadku numerów telefonów zasubskrybuj swój punkt końcowy do Odpowiedź zawiera jednorazowy
telephony.incoming:secret — zapisz go; użyjesz go
do weryfikacji podpisu.2. Zaimplementuj obsługę
Trzy praktyczne zasady:- Weryfikuj podpis przy każdym żądaniu (zobacz Weryfikowanie podpisów webhooków). Nie pomijaj tego w środowisku deweloperskim — zrób to poprawnie raz i wykorzystuj ponownie.
- Odpowiadaj szybko. Dziesięć sekund to nieprzekraczalny limit, a każda sekunda to cisza dla rozmówcy. W razie potrzeby wykonuj wyszukiwania w bazie danych, ale nie wywołuj podrzędnych modeli LLM synchronicznie — jeśli potrzebujesz dynamicznego generowania promptów, oblicz je wcześniej i zapisuj w pamięci podręcznej.
- Stosuj przejrzysty mechanizm awaryjny. Każdy nieoczekiwany stan powinien zwracać
{}, aby statycznie przypisany agent obsłużył połączenie.
3. Schemat odpowiedzi
Treść odpowiedzi dokładnie odpowiada schematowi odpowiedzi na połączenie przychodzące. Najczęściej używane pola:Kolejność wypowiedzi dla połączenia i
max_hold_seconds nie są dostępne w
odpowiedzi webhooka. Ustaw je w
Agencie, do którego się odwołujesz.Wzorce
Kontekst zalogowanego użytkownika
W widżetach w trybie webhooka strona odwiedzającego już wie, kim on jest. Wywołaj webhook z parametrem ciągu zapytania, który SDK widżetu przekazuje dalej (?customer_id=123), i wyszukaj klienta po stronie serwera.
Wdrażanie promptów A/B
Zanim wdrożysz własne rozwiązanie, pamiętaj, że ThunderPhone ma natywną funkcję Eksperymenty (/dashboard/experiments oraz kartę A/B w kreatorze agenta), która
definiuje warianty, dzieli ruch i porównuje wyniki dla każdego wariantu —
bez potrzeby używania webhooka.
Jeśli mimo to potrzebujesz kontroli po stronie webhooka: zahaszuj call_id → koszyk;
obsługuj prompt A dla 0..49 i prompt B dla 50..99. Zapisz wybrany
koszyk we własnej bazie danych, a później skoreluj go z oceną zakończonego połączenia.
Routing zależny od czasu
Godziny pracy → agent „wsparcia na żywo”; poza godzinami pracy → agent „przyjmowania wiadomości”. W obsłudze wystarczy proste przełączenie na podstawienew Date().getUTCHours().
Następne kroki
Dokumentacja webhooka połączeń przychodzących
Dokładne schematy żądań i odpowiedzi, w tym każdy klucz konfiguracji.
Weryfikacja podpisów webhooków
Poprawnie skonfiguruj HMAC raz, a potem używaj go wszędzie.
Tworzenie integracji z narzędziem
Połącz dynamiczny routing z narzędziami przypisanymi do poszczególnych agentów.
Semantyka dostarczania
Ponowne próby, kolejność, limity czasu.