--- title: "telephony.incoming / web.incoming" description: "બ્લોકિંગ webhook જે આવનારા કૉલનું કન્ફિગરેશન વાસ્તવિક સમયમાં આકાર આપે છે." --- જ્યારે ઇનબાઉન્ડ ફોન કૉલ કોઈ **સોંપાયેલા એજન્ટ વિના** નંબર પર પહોંચે, અથવા વેબ વિજેટ સત્ર `mode="webhook"`માં publishable key પર શરૂ થાય, ત્યારે ThunderPhone તમારી [લેગસી webhook URL](/api-reference/organizations#legacy-single-url-webhook) પર **બ્લોકિંગ** `telephony.incoming` / `web.incoming` વિનંતી મોકલે છે અને કૉન્ફિગરેશન પ્રતિસાદ માટે **10 સેકન્ડ** સુધી રાહ જુએ છે. દરેક કૉલ માટે prompt, વૉઇસ અને ટૂલ્સને ડાયનેમિક રીતે પસંદ કરવા માટે આ વિનિમયનો ઉપયોગ કરો — સંપૂર્ણ પેટર્ન માટે [ડાયનેમિક કૉલ કૉન્ફિગરેશન માર્ગદર્શિકા](/gu/guides/dynamic-call-config) જુઓ. સબ્સ્ક્રાઇબ કરેલા [webhook એન્ડપૉઇન્ટ્સ](/gu/webhooks/endpoints)ને પણ `telephony.incoming` / `web.incoming` મળે છે — **દરેક** ઇનબાઉન્ડ કૉલ અને વેબ સત્ર માટે, એજન્ટ-કૉન્ફિગર કરેલું હોય કે ન હોય — પરંતુ આ ડિલિવરી `event_id` સાથેની ફાયર-એન્ડ-ફૉર્ગેટ સૂચનાઓ છે, ક્યારેય બ્લોકિંગ નથી. ફક્ત લેગસી સિંગલ-URL webhook આ પેજ પરનો કૉન્ફિગરેશન વિનિમય ધરાવે છે. એન્ડપૉઇન્ટ સૂચનાના સ્વરૂપો [ઇવેન્ટ્સ કૅટલૉગ](/gu/webhooks/events)માં છે. બ્લોકિંગ વિનિમયમાં કોઈ ફૉલબૅક નથી: જો તમારું હેન્ડલર non-2xx સ્ટેટસ પરત કરે, ટાઇમઆઉટ થાય, અથવા વૅલિડેશનમાં નિષ્ફળ જતું કૉન્ફિગ પરત કરે, તો કૉલ નકારવામાં આવે છે (ફોન કૉલ કનેક્ટ થતો નથી; વિજેટ સત્ર વિનંતી `502`/`422` સાથે નિષ્ફળ જાય છે). ઝડપથી જવાબ આપો — તમે નિર્ણય લઈ રહ્યાં હો ત્યારે કૉલરને રિંગબૅક સંભળાય છે. **Webhook-કૉન્ફિગર કરેલા કૉલમાં ThunderPhone સંમતિ જાહેરાત હોતી નથી.** આ વિનિમય દ્વારા કૉન્ફિગર કરાયેલા કૉલ એજન્ટ-સ્તરની કૉલ-પ્રારંભ જાહેરાતને બાયપાસ કરે છે અને ThunderPhoneના સંમતિ-જાહેરાત માળખા (સેવાની શરતો, "રેકૉર્ડિંગ અને સંમતિ" વિભાગ)માંથી સ્પષ્ટપણે બાકાત છે. આ કૉલ પર જરૂરી દરેક રેકૉર્ડિંગ, મૉનિટરિંગ, AI-ભાગીદારી અને કૉલર-ઓળખ સૂચના તથા સંમતિ માટે માત્ર તમારી સંસ્થા જવાબદાર છે — કૉલને હજી પણ રેકૉર્ડ, ટ્રાન્સક્રાઇબ, વિશ્લેષિત અને AI દ્વારા સેવા આપી શકાય છે. આ માર્ગ સક્ષમ કરતાં પહેલાં જરૂરી ખુલાસાઓને તમારા પોતાના કૉલ ફ્લોમાં સામેલ કરો. ## વિનંતી પેલોડ ફોન કૉલ માટે (`telephony.incoming`): ```json { "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" } } ``` | ફીલ્ડ | પ્રકાર | વર્ણન | |-------|------|-------------| | `call_id` | integer | કૉલ id — આ કૉલના તમામ ઇવેન્ટ્સમાં સ્થિર | | `from_number` | string | E.164 કૉલર નંબર | | `to_number` | string | E.164 ગંતવ્ય (તમારા ThunderPhone નંબરોમાંથી એક) | વેબ વિજેટ સત્રો માટે (`web.incoming`), `data` ફોન નંબરોના બદલે એમ્બેડિંગ પેજને ઓળખે છે: ```json { "type": "web.incoming", "data": { "call_id": 987654322, "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2" } } ``` | ફીલ્ડ | પ્રકાર | વર્ણન | |-------|------|-------------| | `call_id` | integer | કૉલ id | | `origin_domain` | string | વિજેટ હોસ્ટ કરતા પેજનું ઓરિજિન | | `publishable_key_prefix` | string | સત્ર ખોલનાર publishable keyના શરૂઆતના અક્ષરો | | `language`, `primary_language` | string | વિજેટ સત્રે ભાષા ઓવરરાઇડની વિનંતી કરી હોય ત્યારે હાજર | | `voice` | string | વિજેટ સત્રે વૉઇસ ઓવરરાઇડની વિનંતી કરી હોય ત્યારે હાજર | | `website_context` | string | વિજેટે પ્રતિ-સત્ર પેજ સંદર્ભ મોકલ્યો હોય ત્યારે હાજર | Webhook-મોડ વિજેટ્સ આ વિનંતીને publishable keyના પોતાના `webhook_url` પર મોકલે છે જ્યારે તે સેટ હોય, નહિતર સંસ્થા-સ્તરના webhook URL પર ફૉલબૅક કરે છે. બંને સ્થિતિમાં તે સંસ્થાના webhook `secret`થી સહી કરેલી હોય છે. --- ## પ્રતિસાદ સ્કીમા આ કૉલ માટે એજન્ટ કન્ફિગરેશનનું વર્ણન કરતું JSON ઑબ્જેક્ટ પરત કરો. `prompt` અને `voice` આવશ્યક છે; બાકીનું બધું વૈકલ્પિક છે. ```json { "prompt": "You are a helpful booking assistant for Acme Restaurant.", "voice": "john", "product": "spark", "background_track": null, "tools": [] } ``` | ફીલ્ડ | પ્રકાર | આવશ્યક | વર્ણન | |-------|------|----------|-------------| | `prompt` | string | હા | એજન્ટને સંચાલિત કરતો સિસ્ટમ prompt | | `voice` | string | હા | [`GET /v1/voices`](/api-reference/agents#voices) માંથી વૉઇસ id, દા.ત. `john`. `voice_name` ઉપનામ તરીકે સ્વીકારવામાં આવે છે. અજાણ્યા વૉઇસ વૅલિડેશનમાં નિષ્ફળ જાય છે અને કૉલ નકારવામાં આવે છે | | `product` | string | ના | ડિફૉલ્ટ `spark`. માન્ય: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` | | `thinking_level` | string | ના | `minimal`, `base` (ડિફૉલ્ટ), અથવા `extra`. Storm પ્રોડક્ટ્સ માટે ઓવરરાઇડ થાય છે: `storm-extra*` `extra` ફરજિયાત કરે છે, અન્ય `storm-*` `base` ફરજિયાત કરે છે | | `audio_context_mode` | string | ના | `full` (ડિફૉલ્ટ) અથવા `reduced` | | `watchdog_enabled` | boolean | ના | આ કૉલ માટે નિરીક્ષણ સક્રિય કરો. ડિફૉલ્ટ `false` | | `additional_audio_context` | boolean \| null | ના | ફક્ત સૌથી તાજેતરના ટર્નને બદલે કૉલરના ઑડિયોના છેલ્લા કેટલાક ટર્ન શામેલ કરો, જે નાના લેટન્સી/ખર્ચના ઓવરહેડ સાથે સુધારાઓ અને સ્પેલિંગ/નંબર-આધારિત ડેટા સંગ્રહને બહેતર બનાવે છે. ઇનબાઉન્ડ સત્રો માટે ડિફૉલ્ટ રૂપે ચાલુ અને આઉટબાઉન્ડ ફોન કૉલ્સ માટે બંધ; `null` ડિફૉલ્ટ જાળવી રાખે છે | | `storm_feedback_mode` | string | ના | `none`, `acknowledgement` (ડિફૉલ્ટ), અથવા `tick` | | `language` | string | ના | `primary_language` માટે સંક્ષિપ્ત રૂપ | | `primary_language` | string | ના | ભાષા કોડ, સામાન્યકૃત (ડિફૉલ્ટ `en`). ઉકેલી ન શકાય તેવા કોડ કૉલ નકારે છે | | `has_additional_languages` | boolean | ના | ડિફૉલ્ટ `false` | | `additional_languages` | string નો array | ના | એજન્ટ જે વધારાની ભાષાઓ પર સ્વિચ કરી શકે તે | | `native_voice_switching` | boolean | ના | ડિફૉલ્ટ `false`. કૉલ બીજી ભાષા પર સ્વિચ થાય ત્યારે, કન્ફિગર કરેલા વૉઇસને જાળવી રાખવાને બદલે તે ભાષાના મૂળ વક્તાનો વૉઇસ (લિંગ અનુસાર મેળ ખાતો) વાપરો | | `background_track` | string \| null | ના | એમ્બિયન્ટ ઑડિયો id અથવા `null` | | `acknowledgement_prompt_mode` | string | ના | `auto` (ડિફૉલ્ટ) અથવા `manual` (Storm-with-ack પ્રોડક્ટ્સ) | | `acknowledgement_prompt` | string | ના | `acknowledgement_prompt_mode="manual"` હોય ત્યારે વપરાય છે | | `silence_interval_seconds` | integer \| null | ના | 5–120. ચેક-ઇન પહેલાં કૉલરની નિઃશબ્દતાની સેકન્ડ સંખ્યા | | `silence_max_checkins` | integer \| null | ના | 1–10 | | `silence_checkins_enabled` | boolean | ના | ડિફૉલ્ટ `true` | | `connect_tone_enabled` | boolean | ના | ડિફૉલ્ટ `false` | | `voicemail_action` | string | ના | `prompt` (ડિફૉલ્ટ), `hangup`, અથવા `message` | | `voicemail_message` | string | ના | `voicemail_action="message"` હોય ત્યારે વપરાય છે | | `agent_name` | string | ના | ડેશબોર્ડ્સ અને વિજેટમાં દર્શાવાતું નામ | | `org_name` | string | ના | એજન્ટના પર્સોના માટે સંસ્થાનું દર્શાવાતું નામ | | `tools` | array | ના | ઇનલાઇન ફંક્શન-ટૂલ સ્કીમાઓ ([Function Tools](/gu/tools/overview) જુઓ) | | `call_id` | integer | ના | વિનંતીના કૉલ id નો વૈકલ્પિક ઇકો; અવગણવામાં આવે છે | અજાણી ટોપ-લેવલ કીઝને શાંતિથી **અવગણવામાં આવે છે** — ટાઇપોની ભૂલવાળું ફીલ્ડ નામ કન્ફિગને નકારતું નથી, તે ફક્ત લાગુ પડતું નથી. ઉચ્ચાર-ક્રમ અને `max_hold_seconds` અહીં સ્વીકારવામાં આવતા નથી; તેઓ ફક્ત [Agent](/api-reference/agents) પર જ કન્ફિગર કરી શકાય છે. `prompt` અને `voice` આવશ્યક હોવાથી, `{}` અથવા વૅલિડેશનમાં નિષ્ફળ જતો કોઈપણ પ્રતિસાદ કૉલને `422` સાથે નકારે છે — આ પાથ પર કોઈ સ્ટેટિક-એજન્ટ ફૉલબૅક નથી (વેબહૂક મોડમાં નંબર અથવા કીને કોઈ એજન્ટ અસાઇન કરેલો હોતો નથી). --- ## પ્રતિસાદ કદ મર્યાદા કન્ફિગરેશન પ્રતિસાદો **5 MiB** સુધી મર્યાદિત છે. જો હેન્ડલર `2xx` સ્ટેટસ સહિત વધુ મોટો પ્રતિસાદ આપે, તો ThunderPhone પ્રતિસાદ મર્યાદા કરતાં વધુ હોવાનું દર્શાવે છે અને કૉલ અથવા વિજેટ સત્રને નકારી કાઢે છે. કૉલ સેટઅપ માટે જરૂરી ફીલ્ડ્સ સુધી પ્રતિસાદ રાખો; મોટા ડેટાને કન્ફિગરેશનમાં એમ્બેડ કરવાને બદલે ફંક્શન ટૂલ્સ અથવા અન્ય સેવા પાછળ હોસ્ટ કરો. --- ## ઉદાહરણ હેન્ડલર ```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({}); }, ); ``` --- ## ફંક્શન ટૂલ્સ સાથેનો પ્રતિસાદ AI વાતચીત દરમિયાન તમારી API કૉલ કરી શકે તે માટે ટૂલ્સ જોડો: ```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" } } } ] } ``` ટૂલ-એન્ડપૉઇન્ટ વિનંતીઓ પર આ વિનિમય પર સહી કરવા માટે વપરાયેલા **સમાન સંસ્થા વેબહૂક સિક્રેટ** વડે સહી કરવામાં આવે છે. ચોક્કસ રચના અને સહી કરેલી વિનંતીના ફોર્મેટ માટે [ફંક્શન ટૂલ્સ](/gu/tools/overview) જુઓ. --- ## પ્રોડક્ટ સ્તર ચીટ શીટ | પ્રોડક્ટ | વિલંબતા | તર્ક | સ્વીકૃતિ | |---------|---------|-----------|-----------------| | `spark` | સૌથી ઓછી | મૂળભૂત | — | | `bolt` | ઓછી | સુધારેલ | — | | `storm-base` | મધ્યમ | મજબૂત | — | | `storm-base-with-ack` | મધ્યમ | મજબૂત | વિચાર દરમિયાન સ્વચાલિત ફિલર | | `storm-extra` | વધુ | ઊંડું | — | | `storm-extra-with-ack` | વધુ | ઊંડું | વિચાર દરમિયાન સ્વચાલિત ફિલર | --- ## સંબંધિત કૉલ સમાપ્ત થવાની નોન-બ્લોકિંગ ઇવેન્ટ. `tools[]` માટે સંપૂર્ણ JSON સ્કીમા અને સહી કરેલ એન્ડપોઇન્ટ કરાર. `telephony.incoming` / `web.incoming` માટે અનેક URLs સબ્સ્ક્રાઇબ કરો. દરેક કૉલર માટેના prompts, ટૂલ્સ અને A/B પરીક્ષણો માટેની પેટર્ન્સ.