Skip to main content
Gdy przychodzące połączenie telefoniczne trafia na numer bez przypisanego agenta lub sesja widżetu internetowego rozpoczyna się przy użyciu klucza publikowalnego w mode="webhook", ThunderPhone wysyła blokujące żądanie telephony.incoming / web.incoming do Twojego starszego adresu URL webhooka i czeka do 10 sekund na odpowiedź z konfiguracją. Użyj tej wymiany, aby dynamicznie wybrać prompt, głos i narzędzia dla każdego połączenia — pełny wzorzec znajdziesz w przewodniku po dynamicznej konfiguracji połączeń.
Subskrybowane punkty końcowe webhooków również otrzymują telephony.incoming / web.incoming — dla każdego przychodzącego połączenia i sesji internetowej, niezależnie od konfiguracji agenta — ale te dostarczenia są powiadomieniami typu fire-and-forget z event_id i nigdy nie blokują. Tylko starszy webhook z jednym adresem URL obsługuje wymianę konfiguracji opisaną na tej stronie. Struktury powiadomień punktów końcowych znajdziesz w katalogu zdarzeń.
Blokująca wymiana nie ma rozwiązania zapasowego: jeśli Twój handler zwróci status inny niż 2xx, przekroczy limit czasu lub zwróci konfigurację, która nie przejdzie walidacji, połączenie zostanie odrzucone (połączenie telefoniczne nie zostanie zestawione; żądanie sesji widżetu zakończy się błędem 502/422). Odpowiadaj szybko — rozmówca słyszy sygnał oczekiwania, podczas gdy podejmujesz decyzję.

Ładunek żądania

Dla połączeń telefonicznych (telephony.incoming):
W przypadku sesji widżetu internetowego (web.incoming) pole data identyfikuje stronę osadzającą zamiast numerów telefonów:
Widżety w trybie webhooka dostarczają to żądanie do własnego webhook_url klucza publikowalnego, jeśli jest ustawiony, a w przeciwnym razie do adresu URL webhooka na poziomie organizacji. W obu przypadkach jest ono podpisywane sekretem webhooka organizacji secret.

Schemat odpowiedzi

Zwróć obiekt JSON opisujący konfigurację agenta dla tego połączenia. prompt i voice są wymagane; wszystkie pozostałe pola są opcjonalne.
Nieznane klucze najwyższego poziomu są po cichu ignorowane — pole z literówką w nazwie nie powoduje odrzucenia konfiguracji, ale po prostu nie zostaje zastosowane. Kolejność wypowiedzi oraz max_hold_seconds nie są tutaj akceptowane; można je skonfigurować wyłącznie w samym agencie.
Ponieważ prompt i voice są wymagane, zwrócenie {} lub dowolnej odpowiedzi, która nie przejdzie walidacji, powoduje odrzucenie połączenia z kodem 422 — nie ma awaryjnego użycia statycznego agenta na tej ścieżce (numer lub klucz w trybie webhooka nie ma przypisanego agenta).

Przykładowy handler


Odpowiedź z narzędziami funkcji

Dołącz narzędzia, aby AI mogła wywoływać Twoje API w trakcie rozmowy:
Żądania do endpointów narzędzi są podpisywane tym samym sekretem webhooka organizacji, którym podpisano tę wymianę. Dokładną strukturę i format podpisanego żądania znajdziesz w sekcji Narzędzia funkcji.

Ściągawka dotycząca poziomów produktów


Powiązane

telephony.complete / web.complete

Nieblokujące zdarzenie zakończenia połączenia.

Narzędzia funkcji

Pełny schemat JSON dla tools[] oraz kontrakt podpisanego punktu końcowego.

Punkty końcowe webhooków

Subskrybuj wiele adresów URL dla telephony.incoming / web.incoming.

Dynamiczna konfiguracja połączeń

Wzorce promptów, narzędzi i testów A/B dla poszczególnych rozmówców.