Skip to main content
Domyślnie każdy numer telefonu i publikowalny klucz mają przypisanego statycznego agenta. Gdy potrzebujesz dostosowania dla każdego rozmówcy lub dla każdego użytkownika — routingu VIP, kontekstu zalogowanego użytkownika, testów A/B promptów — przełącz się na tryb webhooka i pozwól serwerowi podjąć decyzję.

Jak to działa

  1. Subskrybujesz zdarzenie telephony.incoming (telefon) lub web.incoming (widżet). Oba są blokującymi webhookami: ThunderPhone czeka do 10 sekund na Twoją odpowiedź, zanim kontynuuje połączenie.
  2. ThunderPhone wysyła {call_id, from_number, to_number} (sesje widżetu zawierają pola specyficzne dla widżetu zamiast numerów — zobacz schemat żądania).
  3. Twój serwer odpowiada konfiguracją agenta (prompt, głos, produkt, narzędzia). ThunderPhone używa tej konfiguracji podczas połączenia.
  4. 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

W przypadku numerów telefonów zasubskrybuj swój punkt końcowy do telephony.incoming:
Odpowiedź zawiera jednorazowy 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 podstawie new 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.