--- title: "Dynamiczna konfiguracja dla każdego połączenia" description: "Wybieraj agenta odbierającego — lub zmieniaj jego prompt i ustawienia — osobno dla każdego połączenia przychodzącego, na podstawie własnej logiki w webhooku, którym zarządzasz." --- Domyślnie do każdego numeru telefonu i klucza publikowalnego przypisany jest statyczny agent. 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`](/pl/webhooks/events) (telefon) lub [`web.incoming`](/pl/webhooks/events) (widżet). Oba to **blokujące** webhooki: ThunderPhone czeka na Twoją odpowiedź przed kontynuowaniem połączenia, maksymalnie 13 sekund w przypadku połączenia telefonicznego (w tym jedna ponowna próba) i 10 sekund w przypadku sesji widżetu. 2. ThunderPhone wysyła Ci `{call_id, from_number, to_number}` (sesje widżetu zawierają pola specyficzne dla widżetu zamiast numerów — zobacz [schemat żądania](/pl/webhooks/call-incoming)). 3. Twój serwer odpowiada konfiguracją agenta (prompt, głos, produkt, narzędzia). ThunderPhone używa tej konfiguracji podczas połączenia. 4. Nie ma agenta zapasowego. Jeśli zwrócisz `{}` lub nieprawidłową konfigurację albo żądanie nadal nie powiedzie się po [ponownej próbie](/pl/webhooks/call-incoming), połączenie telefoniczne zostanie natychmiast zakończone i zapisane z `end_reason` `inbound_config_webhook_failed`; żądanie sesji widżetu zakończy się niepowodzeniem. 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 jednym adresem URL. **W połączeniach skonfigurowanych przez wbudowany webhook nie jest odtwarzany komunikat ThunderPhone dotyczący zgody.** Ta ścieżka omija komunikat na początku połączenia na poziomie agenta i jest wyraźnie wyłączona z mechanizmu komunikatów dotyczących zgody ThunderPhone (Regulamin, sekcja „Nagrywanie i zgoda”). Twoja organizacja odpowiada za wszystkie komunikaty i zgody dotyczące nagrywania, monitorowania, udziału AI oraz identyfikacji rozmówcy w tych połączeniach. Udostępnij je we własnym przepływie — na przykład w skrypcie otwierającym promptu — przed włączeniem trybu wbudowanego webhooka. Odpowiedź webhooka odwołująca się do zapisanego `agent_id` korzysta ze standardowej polityki nagrywania i ujawniania informacji tego agenta. ## 1. Skonfiguruj miejsce docelowe webhooka W przypadku numerów telefonów zasubskrybuj swój punkt końcowy do `telephony.incoming`: ```bash curl -X POST https://api.thunderphone.com/v1/developer/webhook-endpoints \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "label": "Prod call-incoming", "url": "https://example.com/thunderphone/incoming", "events": ["telephony.incoming"] }' ``` Odpowiedź zawiera jednorazowy `secret` — zapisz go; użyjesz go do weryfikacji podpisu. W przypadku sesji widżetu utwórz klucz publikowalny w `mode="webhook"` z adresem URL punktu końcowego zapisanym w konfiguracji: ```bash curl -X POST https://api.thunderphone.com/v1/publishable-key \ -H "Authorization: Bearer sk_live_YOUR_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Dynamic widget", "mode": "webhook", "webhook_url": "https://example.com/thunderphone/widget-incoming", "allowed_domains": ["example.com"] }' ``` Widżet będzie wysyłać żądanie POST na ten adres URL przy każdym rozpoczęciu sesji. ## 2. Zaimplementuj handler Trzy praktyczne zasady: - **Weryfikuj podpis** przy każdym żądaniu (zobacz [Weryfikowanie podpisów webhooków](/pl/guides/verify-webhook-signatures)). Nie pomijaj tego w środowisku deweloperskim — zrób to poprawnie raz i używaj ponownie. - **Odpowiadaj szybko**. Pierwsza próba połączenia telefonicznego jest przerywana po 10 sekundach, a cała wymiana po 13, a każda sekunda to cisza dla rozmówcy. Wykonuj wyszukiwania w bazie danych, jeśli są potrzebne, 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. - **Płynnie stosuj konfigurację zapasową**. W przypadku każdego nieoczekiwanego stanu odpowiedz domyślnym `prompt` i `voice` (lub zapisanym `agent_id`). Zwrócenie `{}` albo statusu błędu kończy połączenie. ```python FastAPI import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, sig: str) -> bool: expected = hmac.new(SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, sig or "") @app.post("/thunderphone/incoming") async def incoming(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(401) event = json.loads(body) if event["type"] not in ("telephony.incoming", "web.incoming"): return {} # fall back to default caller = event["data"]["from_number"] # Cheap DB lookup: is this a known VIP? customer = lookup_customer(caller) if customer and customer.tier == "vip": return { "prompt": f"You are a VIP concierge for {customer.name}. Be proactive…", "voice": "john", "product": "storm-base", } return {} # default agent handles non-VIPs def lookup_customer(phone: str): # ... your CRM integration ... pass ``` ```javascript Express import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, sig) { const expected = crypto.createHmac("sha256", SECRET).update(body).digest("hex"); return sig && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(sig)); } app.post( "/thunderphone/incoming", express.raw({ type: "application/json" }), async (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); const IMPORTANT_TYPES = new Set([ "telephony.incoming", "web.incoming", ]); if (!IMPORTANT_TYPES.has(event.type)) return res.json({}); const customer = await lookupCustomer(event.data.from_number); if (customer?.tier === "vip") { return res.json({ prompt: `You are a VIP concierge for ${customer.name}. Be proactive…`, voice: "john", product: "storm-base", }); } res.json({}); // fall back to default agent }, ); ``` ## 3. Schemat odpowiedzi Treść odpowiedzi jest dokładnie zgodna ze [schematem odpowiedzi połączenia przychodzącego](/pl/webhooks/call-incoming). Najczęściej używane pola: | Pole | Typ | Opis | |-------|------|-------------| | `prompt` | string (wymagane) | Prompt systemowy dla agenta | | `voice` | string (wymagane) | Identyfikator głosu z [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | string | Domyślnie `spark`. Produkty eksperymentalne są dostępne tylko dla organizacji z listy dozwolonych. | | `background_track` | string \| null | Identyfikator dźwięku tła | | `acknowledgement_prompt_mode` | string | `auto` lub `manual` (tylko Storm z potwierdzeniem) | | `acknowledgement_prompt` | string | Wymagane, gdy tryb to `manual` | | `language_switching` | string | Dla agentów wielojęzycznych: `ask_first` lub `follow_caller` | | `tools` | array | Wbudowane schematy narzędzi funkcji — zobacz [Narzędzia funkcji](/pl/tools/overview) | Kolejność wypowiedzi dla pojedynczego połączenia oraz `max_hold_seconds` nie są dostępne w odpowiedzi webhooka. Ustaw je dla [Agenta](/api-reference/agents), do którego się odwołujesz. ### Zachowaj zapisanego agenta i przekaż zmienne Zwróć `{"agent_id": 12, "variables": {"name": "Ada"}}`, aby użyć zapisanego agenta tej organizacji z danymi dla konkretnego połączenia. Jego prompt może zawierać `{{name}}` lub `{{name|Friend}}`. Zmienne webhooka są scalane ze zmiennymi na poziomie żądania; wartość null używa wartości domyślnej symbolu zastępczego lub pustego tekstu, jeśli jej nie podano. Ostateczne wartości i nierozwiązane nazwy pojawiają się w szczegółach połączenia oraz webhookach zakończenia. Odpowiedzi zapisanych agentów akceptują wyłącznie `agent_id`, `variables` i `timezone`. Jeśli występuje `prompt`, odpowiedź używa konfiguracji wbudowanej i ignoruje `agent_id` (w tym metadane null lub niebędące liczbą całkowitą); wbudowany prompt nadal musi być prawidłowy. Odpowiedzi konfiguracji wbudowanej mogą również zawierać `variables`. Odpowiedzi zapisanych agentów używają wdrożonego przez agenta podziału A/B zarówno w połączeniach telefonicznych, jak i w widżecie, a następnie renderują zmienne. Zobacz [zmienne połączeń](/pl/guides/call-variables), aby poznać limity i obsługę interfejsu API sesji. Konfiguracja blokująca pochodzi ze starszego adresu URL numeru telefonu/organizacji albo z klucza widżetu w trybie webhooka; zdarzenia przychodzące systemu punktu końcowego są wyłącznie powiadomieniami. ### Ustaw strefę czasową dla każdego połączenia Jeden agent może obsługiwać kontakty w różnych strefach czasowych. Dodaj `timezone`, nazwę IANA, do zapisanej odpowiedzi agenta lub odpowiedzi inline, a agent poda datę i godzinę oraz zaproponuje terminy w tej strefie dla tego połączenia, niezależnie od własnej strefy czasowej agenta: ```json {"agent_id": 12, "timezone": "America/Chicago", "variables": {"name": "Ada"}} ``` Wysyłaj strefę zamiast znacznika czasu w `variables`: zegar agenta działa podczas połączenia, a przekazana godzina szybko staje się nieaktualna. Wartość, która nie jest strefą IANA, jest ignorowana, a połączenie zostaje nawiązane w strefie agenta. ## 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 zaimplementujesz to samodzielnie, pamiętaj, że ThunderPhone ma natywną funkcję [Eksperymenty](/pl/guides/concepts) (`/dashboard/experiments` oraz kartę **A/B** w kreatorze agentów), która definiuje warianty, dzieli ruch i porównuje wyniki dla każdego wariantu — webhook nie jest wymagany. Jeśli mimo to potrzebujesz kontroli po stronie webhooka: haszuj `call_id` → koszyk; podawaj 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 oparty na czasie Godziny pracy → agent „wsparcie na żywo”; poza godzinami pracy → agent „przyjmowanie wiadomości”. Czyste przełączenie na podstawie `new Date().getUTCHours()` w obsłudze. --- ## Kolejne kroki Dokładne schematy żądań i odpowiedzi, w tym każdy klucz konfiguracji. Poprawnie skonfiguruj HMAC raz i używaj go wszędzie. Połącz dynamiczny routing z narzędziami dla poszczególnych agentów. Ponowne próby, kolejność, limity czasu.