--- title: "telephony.incoming / web.incoming" description: "Blokeeriv veebikonks, mis kujundab sissetuleva kõne konfiguratsiooni reaalajas." --- Kui sissetulev telefonikõne jõuab numbrini **ilma määratud agendita** või veebividina seanss algab avaldatava võtmega `mode="webhook"`, saadab ThunderPhone sinu [pärandveebihaagi URL-ile](/api-reference/organizations#legacy-single-url-webhook) **blokeeriva** `telephony.incoming` / `web.incoming` päringu ja ootab konfiguratsioonivastust kuni **10 sekundit**. Kasuta seda andmevahetust, et valida iga kõne jaoks dünaamiliselt viip, hääl ja tööriistad — täielikku mustrit vaata [dünaamilise kõnekonfiguratsiooni juhendist](/et/guides/dynamic-call-config). Tellitud [veebihaagi lõpp-punktid](/et/webhooks/endpoints) saavad samuti `telephony.incoming` / `web.incoming` — **iga** sissetuleva kõne ja veebiseansi kohta, olenemata sellest, kas agent on konfigureeritud — kuid need edastused on blokeerimata teavitused koos `event_id`-ga, mitte kunagi blokeerivad. Ainult pärandne ühe URL-iga veebikonks kannab sellel lehel kirjeldatud konfiguratsioonivahetust. Lõpp-punkti teavituste vormid leiad [sündmuste kataloogist](/et/webhooks/events). Blokeerival andmevahetusel puudub varuvariant: kui sinu töötleja tagastab muu olekukoodi kui 2xx, aegub või tagastab valideerimisel ebaõnnestuva konfiguratsiooni, lükatakse kõne tagasi (telefonikõne ei ühendata; vidina seansipäring nurjub koodiga `502`/`422`). Vasta kiiresti — kuni otsustad, kuuleb helistaja kutsungit. **Veebihaagiga konfigureeritud kõned ei sisalda ThunderPhone'i nõusolekuteadet.** Selle andmevahetuse kaudu konfigureeritud kõned jätavad vahele agenditaseme kõne alguse teate ning on selgesõnaliselt välistatud ThunderPhone'i nõusolekuteadete raamistikust (teenusetingimuste jaotis „Salvestamine ja nõusolek“). Sinu organisatsioon vastutab ainuisikuliselt kõigi nende kõnede puhul nõutavate salvestamise, jälgimise, AI osalemise ja helistaja tuvastamise teadete ning nõusolekute eest — kõnesid saab siiski salvestada, transkribeerida, analüüsida ja AI abil teenindada. Enne selle tee lubamist lisa nõutavad teavitused oma kõnevoogu. ## Päringu sisu Telefonikõnede jaoks (`telephony.incoming`): ```json { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | Väli | Tüüp | Kirjeldus | |-------|------|-------------| | `call_id` | integer | Kõne ID — püsib sama selle kõne kõigi sündmuste korral | | `from_number` | string | Helistaja E.164-number | | `to_number` | string | E.164 sihtnumber (üks sinu ThunderPhone'i numbritest) | Veebividina seansside puhul (`web.incoming`) tuvastab `data` telefoninumbrite asemel manustatud lehe: ```json { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | Väli | Tüüp | Kirjeldus | |-------|------|-------------| | `call_id` | integer | Kõne ID | | `origin_domain` | string | Vidinat majutava lehe päritolu | | `publishable_key_prefix` | string | Seansi avanud avaldatava võtme esimesed märgid | | `language`, `primary_language` | string | Esineb, kui vidina seansis taotleti keele ülekirjutamist | | `voice` | string | Esineb, kui vidina seansis taotleti hääle ülekirjutamist | | `website_context` | string | Esineb, kui vidin edastas seansipõhise lehekonteksti | Veebihaagi režiimis vidinad edastavad selle päringu avaldatava võtme enda `webhook_url`-ile, kui see on määratud, ning muul juhul organisatsioonitaseme veebihaagi URL-ile. Mõlemal juhul on see allkirjastatud organisatsiooni veebihaagi `secret`-iga. --- ## Vastuse skeem Tagasta JSON-objekt, mis kirjeldab selle kõne häälagendi konfiguratsiooni. `prompt` ja `voice` on kohustuslikud; kõik muu on valikuline. ```json { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Väli | Tüüp | Kohustuslik | Kirjeldus | |-------|------|----------|-------------| | `prompt` | string | jah | Häälagenti juhtiv süsteemiviip | | `voice` | string | jah | Hääle ID asukohast [`GET /v1/voices`](/api-reference/agents#voices), nt `john`. Aliaseks aktsepteeritakse `voice_name`. Tundmatud hääled ei läbi valideerimist ja kõne lükatakse tagasi | | `product` | string | ei | Vaikeväärtus on `spark`. Lubatud: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | ei | `minimal`, `base` (vaikimisi) või `extra`. Stormi toodete puhul kirjutatakse üle: `storm-extra*` sunnib kasutama `extra`, muud `storm-*` sunnivad kasutama `base` | | `audio_context_mode` | string | ei | `full` (vaikimisi) või `reduced` | | `watchdog_enabled` | boolean | ei | Luba selle kõne järelevalve. Vaikeväärtus `false` | | `additional_audio_context` | boolean \| null | ei | Kaasa helistaja heli viimased mõned voorud, mitte ainult kõige hiljutisem voor; see parandab paranduste ning õigekirja- või numbrimahuka andmekogumise täpsust väikese latentsuse- ja kululisaga. Sissetulevate seansside puhul on vaikimisi sisse lülitatud ning väljaminevate telefonikõnede puhul välja lülitatud; `null` säilitab vaikeväärtuse | | `storm_feedback_mode` | string | ei | `none`, `acknowledgement` (vaikimisi) või `tick` | | `language` | string | ei | Lühivorm `primary_language` jaoks | | `primary_language` | string | ei | Keelekood, normaliseeritud (vaikimisi `en`). Lahendamatud koodid lükkavad kõne tagasi | | `has_additional_languages` | boolean | ei | Vaikeväärtus `false` | | `additional_languages` | stringide massiiv | ei | Lisakeeled, millele häälagent võib üle minna | | `native_voice_switching` | boolean | ei | Vaikeväärtus `false`. Kui kõne läheb üle teisele keelele, vaheta sellele keelele omase hääle vastu (sobitatud soo järgi), selle asemel et säilitada konfigureeritud hääl | | `background_track` | string \| null | ei | Taustaheli ID või `null` | | `acknowledgement_prompt_mode` | string | ei | `auto` (vaikimisi) või `manual` (Storm-with-ack toodete puhul) | | `acknowledgement_prompt` | string | ei | Kasutatakse, kui `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | integer \| null | ei | 5–120. Helistaja vaikuse sekundite arv enne kontrollpäringut | | `silence_max_checkins` | integer \| null | ei | 1–10 | | `silence_checkins_enabled` | boolean | ei | Vaikeväärtus `true` | | `connect_tone_enabled` | boolean | ei | Vaikeväärtus `false` | | `voicemail_action` | string | ei | `prompt` (vaikimisi), `hangup` või `message` | | `voicemail_message` | string | ei | Kasutatakse, kui `voicemail_action="message"` | | `agent_name` | string | ei | Kuvanimi, millest teavitatakse juhtpaneele ja vidinat | | `org_name` | string | ei | Organisatsiooni kuvanimi häälagendi persooni jaoks | | `tools` | massiiv | ei | Reasisesed funktsioonitööriistade skeemid (vt [Funktsioonitööriistad](/et/tools/overview)) | | `call_id` | integer | ei | Taotluse kõne ID valikuline kajastus; ignoreeritakse | Tundmatud tipptaseme võtmed **ignoreeritakse** vaikselt — kirjaveaga välja nimi ei lükka konfiguratsiooni tagasi, seda lihtsalt ei rakendata. Kõnejärjekorda ja `max_hold_seconds` siin ei aktsepteerita; neid saab konfigureerida ainult [häälagendil](/api-reference/agents) endal. Kuna `prompt` ja `voice` on kohustuslikud, lükkab `{}` või mis tahes valideerimist mitte läbiv vastus kõne tagasi koodiga `422` — sellel teel puudub staatilise häälagendi varuvariant (veebikonksu režiimis olevale numbrile või võtmele ei ole häälagenti määratud). --- ## Vastuse suuruse piirang Konfiguratsioonivastuste suurus on piiratud **5 MiB-ga**. Kui töötleja tagastab suurema vastuse, sealhulgas `2xx` olekukoodiga, teatab ThunderPhone, et vastus ületas piirangu, ja lükkab kõne või vidina seansi tagasi. Hoia vastuses ainult kõne seadistamiseks vajalikud väljad; suurte andmete jaoks kasuta funktsioonitööriistu või muud teenust, selle asemel et need konfiguratsiooni manustada. --- ## Näidistöötleja ```python Python (FastAPI) import hashlib import hmac import json import os from fastapi import FastAPI, HTTPException, Request app = FastAPI() WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"] def verify(body: bytes, signature: str) -> bool: expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature or "") @app.post("/thunderphone-webhook") async def webhook(request: Request): body = await request.body() if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")): raise HTTPException(status_code=401) event = json.loads(body) if event["type"] == "telephony.incoming": caller = event["data"]["from_number"] prompt = ( "Greet the caller as a San Francisco local…" if caller.startswith("+1415") else "You are a friendly customer support agent…" ) return { "prompt": prompt, "voice": "john", "product": "spark", } if event["type"] == "web.incoming": return { "prompt": "You are the website's helpful voice assistant…", "voice": "john", "product": "spark", } return {} ``` ```javascript Node.js (Express) import crypto from "node:crypto"; import express from "express"; const app = express(); const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET; function verify(body, signature) { const expected = crypto .createHmac("sha256", SECRET) .update(body) .digest("hex"); return signature && crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature)); } app.post( "/thunderphone-webhook", express.raw({ type: "application/json" }), (req, res) => { if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) { return res.sendStatus(401); } const event = JSON.parse(req.body.toString("utf8")); if (event.type === "telephony.incoming" || event.type === "web.incoming") { const caller = event.data.from_number || "web"; const prompt = caller.startsWith("+1415") ? "Greet the caller as a San Francisco local…" : "You are a friendly customer support agent…"; return res.json({ prompt, voice: "john", product: "spark", }); } res.json({}); }, ); ``` --- ## Vastus funktsioonitööriistadega Lisa tööriistad, et tehisintellekt saaks vestluse ajal sinu API-sid kasutada: ```json { "prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.", "voice": "john", "product": "spark", "tools": [ { "type": "function", "function": { "name": "search_appointments", "description": "Find available appointment slots", "parameters": { "type": "object", "properties": { "date": { "type": "string", "description": "YYYY-MM-DD" }, "service": { "type": "string" } }, "required": ["date"] } }, "endpoint": { "url": "https://api.example.com/appointments/search", "method": "POST", "headers": { "X-Api-Key": "your-key" } } } ] } ``` Tööriista lõpp-punkti päringud on allkirjastatud **sama organisatsiooni webhooki saladusega**, millega see vahetus allkirjastati. Vaata [funktsioonitööriistade](/et/tools/overview) lehelt täpset struktuuri ja allkirjastatud päringu vormingut. --- ## Toote tasemete kiirülevaade | Toode | Latentsus | Arutlusvõime | Kinnitus | |---------|---------|-----------|-----------------| | `spark` | Madalaim | Põhiline | — | | `bolt` | Madal | Täiustatud | — | | `storm-base` | Keskmine | Tugev | — | | `storm-base-with-ack` | Keskmine | Tugev | Automaatne täitesõnum mõtlemise ajal | | `storm-extra` | Kõrgem | Sügav | — | | `storm-extra-with-ack` | Kõrgem | Sügav | Automaatne täitesõnum mõtlemise ajal | --- ## Seotud Mitteblokeeriv kõne lõppemise sündmus. Täielik JSON-skeem `tools[]` jaoks ja allkirjastatud lõpp-punkti leping. Telli mitu URL-i sündmustele `telephony.incoming` / `web.incoming`. Mustrid helistajapõhiste viipade, tööriistade ja A/B-testide jaoks.