--- title: "telephony.incoming / web.incoming" description: "Webhook inayozuia inayounda usanidi wa simu inayoingia kwa wakati halisi." --- Simu inayoingia inapofikia nambari **isiyo na ejenti aliyokabidhiwa**, au kipindi cha wijeti ya wavuti kinapoanza kwa ufunguo wa kuchapisha katika `mode="webhook"`, ThunderPhone hutuma ombi **la kusubiri** la `telephony.incoming` / `web.incoming` kwa [URL yako ya zamani ya webhook](/api-reference/organizations#legacy-single-url-webhook) na kusubiri hadi **sekunde 10** kupata jibu la usanidi. Tumia mabadilishano haya kuchagua kwa njia ya kubadilika prompt, sauti, na zana kwa kila simu — tazama [mwongozo wa usanidi wa simu unaobadilika](/sw/guides/dynamic-call-config) kwa mtiririko kamili. [Vituo vya webhook](/sw/webhooks/endpoints) vilivyosajiliwa pia hupokea `telephony.incoming` / `web.incoming` — kwa **kila** simu inayoingia na kipindi cha wavuti, iwe ejenti imesanidiwa au la — lakini uwasilishaji huo ni arifa za kutuma-bila-kusubiri zenye `event_id`, si za kusubiri kamwe. Webhook ya zamani ya URL moja pekee hubeba mabadilishano ya usanidi kwenye ukurasa huu. Miundo ya arifa za vituo iko kwenye [katalogi ya matukio](/sw/webhooks/events). Mabadilishano ya kusubiri hayana njia mbadala: ikiwa kishughulikiaji chako kinarejesha hali isiyo ya 2xx, kinaisha muda, au kinarejesha usanidi usiopitisha uthibitishaji, simu inakataliwa (simu ya simu haiunganishwi; ombi la kipindi cha wijeti linashindwa kwa `502`/`422`). Jibu haraka — mpigaji anasikia mlio wa kuita huku ukiamua. **Simu zilizosanidiwa kwa webhook hazina tangazo la idhini la ThunderPhone.** Simu zilizosanidiwa kupitia mabadilishano haya hupita tangazo la mwanzo wa simu la kiwango cha ejenti na zimeondolewa waziwazi kwenye mfumo wa matangazo ya idhini wa ThunderPhone (Masharti ya Huduma, sehemu ya "Kurekodi na idhini"). Shirika lako linawajibika pekee kwa kila taarifa na idhini ya kurekodi, kufuatilia, ushiriki wa AI, na utambulisho wa mpigaji inayohitajika kwenye simu hizi — simu bado zinaweza kurekodiwa, kunakiliwa kwa maandishi, kuchanganuliwa, na kuhudumiwa na AI. Jumuisha maelezo yanayohitajika kwenye mtiririko wako mwenyewe wa simu kabla ya kuwezesha njia hii. ## Payload ya ombi Kwa simu za simu (`telephony.incoming`): ```json { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | Sehemu | Aina | Maelezo | |-------|------|-------------| | `call_id` | integer | Kitambulisho cha simu — hubaki thabiti katika matukio yote ya simu hii | | `from_number` | string | Nambari ya mpigaji ya E.164 | | `to_number` | string | Lengwa la E.164 (mojawapo ya nambari zako za ThunderPhone) | Kwa vipindi vya wijeti ya wavuti (`web.incoming`), `data` hutambulisha ukurasa unaopachika wijeti badala ya nambari za simu: ```json { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | Sehemu | Aina | Maelezo | |-------|------|-------------| | `call_id` | integer | Kitambulisho cha simu | | `origin_domain` | string | Asili ya ukurasa unaohifadhi wijeti | | `publishable_key_prefix` | string | Herufi za kwanza za ufunguo wa kuchapisha uliofungua kipindi | | `language`, `primary_language` | string | Hupo wakati kipindi cha wijeti kiliomba kubatilisha lugha | | `voice` | string | Hupo wakati kipindi cha wijeti kiliomba kubatilisha sauti | | `website_context` | string | Hupo wakati wijeti ilipitisha muktadha wa ukurasa kwa kila kipindi | Wijeti za hali ya webhook huwasilisha ombi hili kwa `webhook_url` ya ufunguo wa kuchapisha wenyewe inapowekwa, na vinginevyo hutumia URL ya webhook ya kiwango cha shirika. Kwa vyovyote vile, ombi hili linatiwa sahihi kwa `secret` ya webhook ya shirika. --- ## Skima ya majibu Rudisha kitu cha JSON kinachoeleza usanidi wa ejenti kwa simu hii. `prompt` na `voice` zinahitajika; kila kitu kingine ni hiari. ```json { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | Sehemu | Aina | Inahitajika | Maelezo | |-------|------|----------|-------------| | `prompt` | string | ndiyo | Prompt ya mfumo inayoongoza ejenti | | `voice` | string | ndiyo | Kitambulisho cha sauti kutoka [`GET /v1/voices`](/api-reference/agents#voices), kwa mfano `john`. `voice_name` inakubaliwa kama jina mbadala. Sauti zisizojulikana hushindwa uthibitishaji na kukataa simu | | `product` | string | hapana | Chaguo-msingi ni `spark`. Zinazoruhusiwa: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | hapana | `minimal`, `base` (chaguo-msingi), au `extra`. Hubatilishwa kwa bidhaa za Storm: `storm-extra*` hulazimisha `extra`, na `storm-*` nyingine hulazimisha `base` | | `audio_context_mode` | string | hapana | `full` (chaguo-msingi) au `reduced` | | `watchdog_enabled` | boolean | hapana | Washa usimamizi kwa simu hii. Chaguo-msingi ni `false` | | `additional_audio_context` | boolean \| null | hapana | Jumuisha zamu chache za mwisho za sauti ya mpigaji simu badala ya zamu ya hivi karibuni pekee, kuboresha masahihisho na ukusanyaji wa data wenye tahajia/namba nyingi kwa ongezeko dogo la muda wa kusubiri/gharama. Huwashwa kwa chaguo-msingi kwa vipindi vinavyoingia na huzimwa kwa simu zinazotoka; `null` huhifadhi chaguo-msingi | | `storm_feedback_mode` | string | hapana | `none`, `acknowledgement` (chaguo-msingi), au `tick` | | `language` | string | hapana | Ufupisho wa `primary_language` | | `primary_language` | string | hapana | Msimbo wa lugha, uliosanifishwa (chaguo-msingi `en`). Misimbo isiyoweza kutatuliwa hukataa simu | | `has_additional_languages` | boolean | hapana | Chaguo-msingi ni `false` | | `additional_languages` | array of string | hapana | Lugha za ziada ambazo ejenti inaweza kubadilisha hadi kwazo | | `native_voice_switching` | boolean | hapana | Chaguo-msingi ni `false`. Simu inapobadilika hadi lugha nyingine, badilisha hadi sauti asilia ya lugha hiyo (inayolingana kwa jinsia) badala ya kuhifadhi sauti iliyosanidiwa | | `background_track` | string \| null | hapana | Kitambulisho cha sauti ya mazingira au `null` | | `acknowledgement_prompt_mode` | string | hapana | `auto` (chaguo-msingi) au `manual` (bidhaa za Storm-with-ack) | | `acknowledgement_prompt` | string | hapana | Hutumika wakati `acknowledgement_prompt_mode="manual"` | | `silence_interval_seconds` | integer \| null | hapana | 5–120. Sekunde za ukimya wa mpigaji simu kabla ya ukaguzi | | `silence_max_checkins` | integer \| null | hapana | 1–10 | | `silence_checkins_enabled` | boolean | hapana | Chaguo-msingi ni `true` | | `connect_tone_enabled` | boolean | hapana | Chaguo-msingi ni `false` | | `voicemail_action` | string | hapana | `prompt` (chaguo-msingi), `hangup`, au `message` | | `voicemail_message` | string | hapana | Hutumika wakati `voicemail_action="message"` | | `agent_name` | string | hapana | Jina la kuonyesha linaloripotiwa kwa dashibodi na wijeti | | `org_name` | string | hapana | Jina la kuonyesha la shirika kwa persona ya ejenti | | `tools` | array | hapana | Skima za ndani za zana za vitendaji (tazama [Zana za Vitendaji](/sw/tools/overview)) | | `call_id` | integer | hapana | Rudisho la hiari la kitambulisho cha simu cha ombi; hupuuzwa | Funguo zisizojulikana za kiwango cha juu **zinapuuzwa** kimyakimya — jina la sehemu lililoandikwa kimakosa halikatai usanidi, halitumiki tu. Mpangilio wa kuzungumza na `max_hold_seconds` hazikubaliki hapa; zinaweza kusanidiwa kwenye [Ejenti](/api-reference/agents) yenyewe pekee. Kwa kuwa `prompt` na `voice` zinahitajika, kurudisha `{}` au jibu lolote linaloshindwa uthibitishaji hukataa simu kwa `422` — hakuna ejenti mbadala thabiti kwenye njia hii (namba au ufunguo katika modi ya webhook haina ejenti iliyoteuliwa). --- ## Kikomo cha ukubwa wa jibu Majibu ya usanidi yana kikomo cha **5 MiB**. Ikiwa kishughulikiaji kinarejesha jibu kubwa zaidi, ikiwemo lenye hali ya `2xx`, ThunderPhone huripoti kwamba jibu limezidi kikomo na hukataa simu au kipindi cha wijeti. Weka kwenye jibu sehemu zinazohitajika kwa ajili ya usanidi wa simu; hifadhi data kubwa nyuma ya zana za function au huduma nyingine badala ya kuijumuisha kwenye usanidi. --- ## Mfano wa kishughulikiaji ```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({}); }, ); ``` --- ## Jibu lenye zana za function Ambatisha zana ili ejenti AI iweze kuita API zako katikati ya mazungumzo: ```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" } } } ] } ``` Maombi ya endpoint ya zana husainiwa kwa **siri ileile ya webhook ya shirika** iliyosaini ubadilishanaji huu. Tazama [Zana za Function](/sw/tools/overview) kwa muundo kamili na umbizo la ombi lililosainiwa. --- ## Muhtasari wa viwango vya bidhaa | Bidhaa | Ucheleweshaji | Uwezo wa kufikiri | Uthibitisho | |---------|---------|-----------|-----------------| | `spark` | Chini zaidi | Msingi | — | | `bolt` | Chini | Ulioboreshwa | — | | `storm-base` | Wastani | Imara | — | | `storm-base-with-ack` | Wastani | Imara | Kijazaji kiotomatiki wakati wa kufikiri | | `storm-extra` | Juu zaidi | Kina | — | | `storm-extra-with-ack` | Juu zaidi | Kina | Kijazaji kiotomatiki wakati wa kufikiri | --- ## Yanayohusiana Tukio lisilozuia la mwisho wa simu. Schemata kamili ya JSON ya `tools[]` na mkataba wa endpoint uliotiwa sahihi. Jiandikishe URL nyingi kwa `telephony.incoming` / `web.incoming`. Miundo ya prompt, zana na majaribio ya A/B kwa kila mpigaji.