Skip to main content
Gdy przychodzące połączenie telefoniczne trafia na numer bez przypisanego agenta albo sesja widżetu internetowego rozpoczyna się przy użyciu klucza publikowalnego w mode="webhook", ThunderPhone wysyła blokujące żądanie telephony.incoming / web.incoming na Twój starszy adres 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 schemat 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 pojedynczym adresem URL obsługuje wymianę konfiguracji opisaną na tej stronie. Struktury powiadomień punktów końcowych znajdziesz w katalogu zdarzeń.
Wymiana blokująca nie ma mechanizmu awaryjnego: jeśli procedura obsługi zwróci status spoza 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ł zwrotny, 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 na własny webhook_url klucza publikowalnego, jeśli jest ustawiony, a w przeciwnym razie korzystają z adresu URL webhooka na poziomie organizacji. W obu przypadkach żądanie jest podpisywane za pomocą secret webhooka organizacji.

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 — literówka w nazwie pola nie odrzuca konfiguracji, ale pole po prostu nie zostanie zastosowane. Kolejność wypowiedzi i max_hold_seconds nie są tutaj akceptowane; można je konfigurować wyłącznie w samym agencie.
Ponieważ prompt i voice są wymagane, zwrócenie {} lub dowolnej odpowiedzi, która nie przejdzie walidacji, odrzuca połączenie z kodem 422 — nie ma statycznego agenta zastępczego dla tej ścieżki (numer lub klucz w trybie webhooka nie ma przypisanego agenta).

Limit rozmiaru odpowiedzi

Odpowiedzi konfiguracji są ograniczone do 5 MiB. Jeśli procedura obsługi zwróci większą odpowiedź, również ze statusem 2xx, ThunderPhone zgłosi, że odpowiedź przekroczyła limit, i odrzuci połączenie lub sesję widżetu. Ogranicz odpowiedź do pól potrzebnych do konfiguracji połączenia; umieść duże dane za narzędziami funkcji lub w innej usłudze, zamiast osadzać je w konfiguracji.

Przykładowa obsługa


Odpowiedź z narzędziami funkcyjnymi

Dołącz narzędzia, aby AI mogła wywoływać Twoje interfejsy API w trakcie rozmowy:
Żądania do punktów końcowych narzędzi są podpisywane przy użyciu tego samego sekretu webhooka organizacji, który podpisał tę wymianę. Dokładną strukturę i format podpisanego żądania znajdziesz w sekcji Narzędzia funkcyjne.

Ściąga 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.