> ## Documentation Index > Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt > Use this file to discover all available pages before exploring further. # Dynaaminen puhelukohtainen määritys > Valitse agentti — tai kirjoita kehote uudelleen — jokaiselle saapuvalle puhelulle webhookissa määrittämäsi mukautetun logiikan perusteella. Oletusarvoisesti jokaiselle puhelinnumerolle ja julkaistavalle avaimelle on määritetty staattinen agentti. Kun tarvitset **soittajakohtaista** tai **kävijäkohtaista** mukautusta — VIP-reititystä, kirjautuneen käyttäjän kontekstia tai A/B-kehotetestejä — vaihda webhook-tilaan ja anna palvelimesi päättää. ## Näin se toimii 1. Tilaa [`telephony.incoming`](/fi/webhooks/events) (puhelin)- tai [`web.incoming`](/fi/webhooks/events) (widget) -tapahtuma. Molemmat ovat **estäviä** webhookeja: ThunderPhone odottaa vastaustasi enintään 10 sekuntia ennen puhelun jatkamista. 2. ThunderPhone lähettää sinulle `{call_id, from_number, to_number}` (widget- istunnot sisältävät numeroiden sijaan widget-kohtaisia kenttiä — katso [pyyntöskeema](/fi/webhooks/call-incoming)). 3. Palvelimesi vastaa agentin määrityksellä (kehote, ääni, tuote, työkalut). ThunderPhone käyttää tätä määritystä puhelussa. 4. Jos palautat `{}`, vastaus aikakatkaistaan tai tapahtuu virhe, staattisesti määritettyä agenttia käytetään varavaihtoehtona. Turvallinen oletus. Toimii samalla tavalla puheluissa (`telephony.incoming`) ja widget- istunnoissa (`web.incoming`), toimitetaanko ne webhook-päätepisteeseen vai vanhaan yhden URL-osoitteen webhookiin. ## 1. Määritä webhook-kohde Tilaa puhelinnumeroita varten päätepisteellesi `telephony.incoming`: ```bash theme={null} 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"] }' ``` Vastaus sisältää kertaluonteisen `secret`-arvon — tallenna se; käytät sitä allekirjoituksen varmennukseen. Luo widget-istuntoja varten `mode="webhook"`-tilassa julkaistava avain, johon päätepisteesi URL-osoite on sisällytetty: ```bash theme={null} 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"] }' ``` Widget lähettää POST-pyynnön tähän URL-osoitteeseen jokaisen istunnon alkaessa. ## 2. Toteuta käsittelijä Kolme nyrkkisääntöä: * **Vahvista allekirjoitus** jokaisessa pyynnössä (katso [Vahvista webhook-allekirjoitukset](/fi/guides/verify-webhook-signatures)). Älä ohita tätä kehityksessä — tee se oikein kerran ja käytä uudelleen. * **Vastaa nopeasti**. Kymmenen sekuntia on ehdoton enimmäisaika, ja jokainen sekunti on soittajalle hiljaisuutta. Tee tarvittaessa tietokantahakuja, mutta älä kutsu jatkoketjun LLM:iä synkronisesti — jos haluat dynaamisen promptin luomisen, esilaske ja tallenna välimuistiin. * **Käytä selkeää varavaihtoehtoa**. Kaikissa odottamattomissa tiloissa tulee palauttaa `{}`, jotta staattisesti määritetty agentti käsittelee puhelun. ```python FastAPI theme={null} 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 theme={null} 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. Vastausskeema Vastauksen runko vastaa täsmälleen [saapuvan puhelun vastausskeemaa](/fi/webhooks/call-incoming). Yleisesti käytetyt kentät: | Kenttä | Tyyppi | Kuvaus | | ----------------------------- | ----------------------- | -------------------------------------------------------------------------------- | | `prompt` | merkkijono (pakollinen) | Agentin järjestelmäprompti | | `voice` | merkkijono (pakollinen) | Äänitunnus kohteesta [`GET /v1/voices`](/api-reference/agents#voices) | | `product` | merkkijono | Oletusarvo on `spark` | | `background_track` | merkkijono \| null | Taustaäänen tunnus | | `acknowledgement_prompt_mode` | merkkijono | `auto` tai `manual` (vain Storm-with-ack) | | `acknowledgement_prompt` | merkkijono | Pakollinen, kun tila on `manual` | | `tools` | taulukko | Upotetut funktiotyökalujen skeemat — katso [Funktiotyökalut](/fi/tools/overview) | Puhelukohtainen puhejärjestys ja `max_hold_seconds` eivät ole käytettävissä webhook-vastauksessa. Määritä ne siinä [agentissa](/api-reference/agents), johon viittaat. ## Käyttömallit ### Sisäänkirjautuneen käyttäjän konteksti Webhook-tilan widgeteissä vierailijan sivu tietää jo, kuka hän on. Kutsu webhookiasi kyselymerkkijonoparametrilla, jonka widgetin SDK välittää (`?customer_id=123`), ja hae asiakas palvelinpuolella. ### A/B-kehotteiden käyttöönotto Ennen kuin toteutat tämän itse, huomaa, että ThunderPhonessa on sisäänrakennettu [Kokeilut](/fi/guides/concepts) -ominaisuus (`/dashboard/experiments` ja agentin rakennustyökalun **A/B**-välilehti), joka määrittää variantit, jakaa liikenteen ja vertaa tuloksia varianttikohtaisesti — webhookia ei tarvita. Jos tarvitset silti hallintaa webhook-puolella: hajauta `call_id` → ryhmä; tarjoa kehote A arvoille `0..49` ja kehote B arvoille `50..99`. Tallenna valitsemasi ryhmä omaan tietokantaasi ja yhdistä se myöhemmin valmistuneen puhelun arvioon. ### Aikaperusteinen reititys Aukioloaika → "live-tuki"-agentti; aukioloaikojen ulkopuolella → "jätä viesti" -agentti. Toteuta tämä käsittelijässäsi pelkkänä ehtovalintana käyttäen `new Date().getUTCHours()`. *** ## Seuraavat vaiheet Täsmälliset pyyntö- ja vastausskeemat, mukaan lukien kaikki määritysavaimet. Tee HMAC oikein kerran; käytä sitä uudelleen kaikkialla. Yhdistä dynaaminen reititys agenttikohtaisiin työkaluihin. Uudelleenyritykset, järjestys, aikakatkaisut.