---
title: "telephony.incoming / web.incoming"
description: "येणाऱ्या कॉलचे कॉन्फिगरेशन रिअल टाइममध्ये आकार देणारा ब्लॉकिंग webhook."
---

जेव्हा इनबाउंड फोन कॉल **नियुक्त
एजंटशिवाय** असलेल्या नंबरवर येतो किंवा `mode="webhook"` मधील
पब्लिश करण्यायोग्य कीवर वेब विजेट सेशन सुरू होते, तेव्हा ThunderPhone तुमच्या
[लेगसी webhook URL](/api-reference/organizations#legacy-single-url-webhook)
वर **ब्लॉकिंग**
`telephony.incoming` / `web.incoming` विनंती पाठवते आणि कॉन्फिगरेशन प्रतिसादासाठी
कमाल **10 सेकंद** प्रतीक्षा करते. प्रत्येक कॉलसाठी prompt, आवाज आणि टूल्स
डायनॅमिकरीत्या निवडण्यासाठी हा विनिमय वापरा —
संपूर्ण पॅटर्नसाठी [डायनॅमिक कॉल कॉन्फिगरेशन मार्गदर्शक](/mr/guides/dynamic-call-config)
पाहा.

<Note>
  सबस्क्राइब केलेल्या [webhook एंडपॉइंट्स](/mr/webhooks/endpoints) ना देखील
  `telephony.incoming` / `web.incoming` प्राप्त होते — **प्रत्येक** इनबाउंड कॉल
  आणि वेब सेशनसाठी, एजंट कॉन्फिगर केलेला असो वा नसो — परंतु ही डिलिव्हरी
  `event_id` सह फायर-अँड-फॉरगेट सूचना असतात, कधीही ब्लॉकिंग नसतात.
  फक्त लेगसी सिंगल-URL webhook मध्ये या पेजवरील कॉन्फिगरेशन विनिमय असतो.
  एंडपॉइंट सूचना संरचना [इव्हेंट्स कॅटलॉग](/mr/webhooks/events)
  मध्ये आहेत.
</Note>

या ब्लॉकिंग विनिमयाला कोणताही फॉलबॅक नाही: तुमचा हँडलर नॉन-2xx स्टेटस परत करत असल्यास,
टाइम आउट झाल्यास किंवा व्हॅलिडेशन अयशस्वी होणारे कॉन्फिगरेशन परत करत असल्यास,
कॉल नाकारला जातो (फोन कॉल कनेक्ट होत नाही; विजेट सेशन विनंती `502`/`422` सह
अयशस्वी होते). त्वरीत प्रतिसाद द्या — तुम्ही निर्णय घेत असताना कॉलरला रिंगबॅक ऐकू येत असतो.

<Warning>
  **Webhook-कॉन्फिगर केलेल्या कॉलमध्ये ThunderPhone ची संमती
  सूचना नसते.** या विनिमयाद्वारे कॉन्फिगर केलेले कॉल एजंट-स्तरीय कॉल-स्टार्ट
  सूचना वगळतात आणि ThunderPhone च्या संमती-सूचना फ्रेमवर्कमधून (सेवा अटी,
  "रेकॉर्डिंग आणि संमती" विभाग) स्पष्टपणे वगळलेले असतात. या कॉलवर आवश्यक असलेल्या
  प्रत्येक रेकॉर्डिंग, मॉनिटरिंग, AI-सहभाग आणि कॉलर-ओळख सूचना व संमतीसाठी
  फक्त तुमची संस्था जबाबदार आहे — हे कॉल तरीही रेकॉर्ड, ट्रान्सक्राइब, विश्लेषित
  आणि AI द्वारे हाताळले जाऊ शकतात. हा मार्ग सक्षम करण्यापूर्वी तुमच्या स्वतःच्या
  कॉल फ्लोमध्ये आवश्यक प्रकटीकरणे समाविष्ट करा.
</Warning>

## विनंती पेलोड

फोन कॉलसाठी (`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 | सेशन उघडणाऱ्या पब्लिश करण्यायोग्य कीची सुरुवातीची अक्षरे |
| `language`, `primary_language` | string | विजेट सेशनने भाषा ओव्हरराइडची विनंती केल्यावर उपलब्ध असते |
| `voice` | string | विजेट सेशनने आवाज ओव्हरराइडची विनंती केल्यावर उपलब्ध असते |
| `website_context` | string | विजेटने प्रति-सेशन पेज कॉन्टेक्स्ट पास केल्यावर उपलब्ध असते |

<Note>
  Webhook-मोड विजेट्स ही विनंती पब्लिश करण्यायोग्य कीच्या स्वतःच्या
  `webhook_url` वर पाठवतात, तो सेट असल्यास; अन्यथा संस्था-स्तरीय
  webhook URL वापरतात. कोणत्याही परिस्थितीत ती संस्था webhook `secret` ने साइन केलेली असते.
</Note>

---

## प्रतिसाद स्कीमा

या कॉलसाठी एजंट कॉन्फिगरेशनचे वर्णन करणारा JSON ऑब्जेक्ट परत करा.
`prompt` आणि `voice` आवश्यक आहेत; इतर सर्व पर्यायी आहेत.

```json
{
  "prompt":  "You are a helpful booking assistant for Acme Restaurant.",
  "voice":   "john",
  "product": "spark",
  "background_track": null,
  "tools":   []
}
```

| फील्ड | प्रकार | आवश्यक | वर्णन |
|-------|------|----------|-------------|
| `prompt` | स्ट्रिंग | होय | एजंटला मार्गदर्शन करणारा सिस्टम prompt |
| `voice` | स्ट्रिंग | होय | [`GET /v1/voices`](/api-reference/agents#voices) मधील व्हॉइस आयडी, उदा. `john`. `voice_name` हे उपनाव म्हणून स्वीकारले जाते. अज्ञात व्हॉइस सत्यापनात अयशस्वी होतात आणि कॉल नाकारतात |
| `product` | स्ट्रिंग | नाही | डीफॉल्ट `spark`. अनुमत: `spark`, `bolt`, `storm-base`, `storm-base-with-ack`, `storm-extra`, `storm-extra-with-ack` |
| `thinking_level` | स्ट्रिंग | नाही | `minimal`, `base` (डीफॉल्ट), किंवा `extra`. Storm उत्पादनांसाठी ओव्हरराइड केले जाते: `storm-extra*` मुळे `extra` सक्तीचे होते, इतर `storm-*` मुळे `base` सक्तीचे होते |
| `audio_context_mode` | स्ट्रिंग | नाही | `full` (डीफॉल्ट) किंवा `reduced` |
| `watchdog_enabled` | बूलियन | नाही | या कॉलसाठी पर्यवेक्षण सक्षम करा. डीफॉल्ट `false` |
| `additional_audio_context` | बूलियन \| null | नाही | केवळ सर्वात अलीकडील टर्नऐवजी कॉलरच्या ऑडिओमधील शेवटचे काही टर्न समाविष्ट करा, ज्यामुळे कमी विलंब/खर्चाच्या वाढीसह दुरुस्त्या आणि स्पेलिंग/संख्या-केंद्रित डेटा संकलन सुधारते. इनबाउंड सत्रांसाठी डीफॉल्टने चालू आणि आउटबाउंड फोन कॉलसाठी बंद; `null` डीफॉल्ट कायम ठेवते |
| `storm_feedback_mode` | स्ट्रिंग | नाही | `none`, `acknowledgement` (डीफॉल्ट), किंवा `tick` |
| `language` | स्ट्रिंग | नाही | `primary_language` साठी संक्षिप्त रूप |
| `primary_language` | स्ट्रिंग | नाही | भाषा कोड, सामान्यीकृत (डीफॉल्ट `en`). निराकरण न होणारे कोड कॉल नाकारतात |
| `has_additional_languages` | बूलियन | नाही | डीफॉल्ट `false` |
| `additional_languages` | स्ट्रिंगचा अॅरे | नाही | एजंट ज्या अतिरिक्त भाषांवर स्विच करू शकतो त्या |
| `native_voice_switching` | बूलियन | नाही | डीफॉल्ट `false`. कॉल दुसऱ्या भाषेवर स्विच झाल्यावर, कॉन्फिगर केलेला व्हॉइस ठेवण्याऐवजी त्या भाषेतील मूळ व्हॉइसवर स्विच करा (लिंगानुसार जुळवलेला) |
| `background_track` | स्ट्रिंग \| null | नाही | पार्श्वभूमी ऑडिओ आयडी किंवा `null` |
| `acknowledgement_prompt_mode` | स्ट्रिंग | नाही | `auto` (डीफॉल्ट) किंवा `manual` (Storm-with-ack उत्पादने) |
| `acknowledgement_prompt` | स्ट्रिंग | नाही | `acknowledgement_prompt_mode="manual"` असताना वापरले जाते |
| `silence_interval_seconds` | पूर्णांक \| null | नाही | 5–120. तपासणीपूर्वी कॉलरच्या शांततेचे सेकंद |
| `silence_max_checkins` | पूर्णांक \| null | नाही | 1–10 |
| `silence_checkins_enabled` | बूलियन | नाही | डीफॉल्ट `true` |
| `connect_tone_enabled` | बूलियन | नाही | डीफॉल्ट `false` |
| `voicemail_action` | स्ट्रिंग | नाही | `prompt` (डीफॉल्ट), `hangup`, किंवा `message` |
| `voicemail_message` | स्ट्रिंग | नाही | `voicemail_action="message"` असताना वापरले जाते |
| `agent_name` | स्ट्रिंग | नाही | डॅशबोर्ड आणि विजेटला कळवले जाणारे प्रदर्शन नाव |
| `org_name` | स्ट्रिंग | नाही | एजंटच्या व्यक्तिमत्त्वासाठी संस्थेचे प्रदर्शन नाव |
| `tools` | अॅरे | नाही | इनलाइन फंक्शन-टूल स्कीमा ([Function Tools](/mr/tools/overview) पहा) |
| `call_id` | पूर्णांक | नाही | विनंतीच्या कॉल आयडीचा पर्यायी इको; दुर्लक्षित केला जातो |

<Note>
  अज्ञात शीर्ष-स्तरीय की शांतपणे **दुर्लक्षित केल्या जातात** — चुकीच्या शब्दलेखनाचा फील्ड
  नाव कॉन्फिगरेशन नाकारत नाही, ते फक्त लागू होत नाही. Speak-order
  आणि `max_hold_seconds` येथे स्वीकारले जात नाहीत; ते केवळ
  [Agent](/api-reference/agents) वरच कॉन्फिगर करता येतात.
</Note>

`prompt` आणि `voice` आवश्यक असल्यामुळे, `{}` किंवा सत्यापनात अयशस्वी होणारा कोणताही
प्रतिसाद कॉल `422` सह नाकारतो — या मार्गावर स्थिर-एजंट फॉलबॅक नाही (वेबहुक मोडमधील
नंबर किंवा कीला नियुक्त एजंट नसतो).

---

## प्रतिसाद आकार मर्यादा

<Warning>
  कॉन्फिगरेशन प्रतिसादांची मर्यादा **5 MiB** आहे. हँडलरने
  `2xx` स्थितीसह मोठा प्रतिसाद दिल्यास, ThunderPhone प्रतिसादाने
  मर्यादा ओलांडल्याचे नोंदवते आणि कॉल किंवा विजेट सत्र नाकारते. कॉल
  सेटअपसाठी आवश्यक असलेल्या फील्डपुरताच प्रतिसाद ठेवा; मोठा डेटा
  कॉन्फिगरेशनमध्ये एम्बेड करण्याऐवजी फंक्शन टूल्स किंवा दुसऱ्या
  सेवेमागे होस्ट करा.
</Warning>

---

## उदाहरण हँडलर

<CodeGroup>
```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({});
  },
);
```
</CodeGroup>

---

## फंक्शन टूल्ससह प्रतिसाद

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"
        }
      }
    }
  ]
}
```

<Tip>
  टूल-एंडपॉइंट विनंत्यांवर या एक्सचेंजवर स्वाक्षरी करणाऱ्या **त्याच
  संस्थेच्या वेबहुक सीक्रेटने** स्वाक्षरी केली जाते. अचूक स्वरूप आणि
  स्वाक्षरीयुक्त विनंती फॉरमॅटसाठी
  [फंक्शन टूल्स](/mr/tools/overview) पहा.
</Tip>

---

## उत्पादन स्तर जलद संदर्भ

| उत्पादन | विलंबता | तर्कशक्ती | पोचपावती |
|---------|---------|-----------|-----------------|
| `spark` | सर्वात कमी | मूलभूत | — |
| `bolt` | कमी | सुधारित | — |
| `storm-base` | मध्यम | सक्षम | — |
| `storm-base-with-ack` | मध्यम | सक्षम | विचार करताना स्वयंचलित फिलर |
| `storm-extra` | जास्त | सखोल | — |
| `storm-extra-with-ack` | जास्त | सखोल | विचार करताना स्वयंचलित फिलर |

---

## संबंधित

<CardGroup cols={2}>
  <Card title="telephony.complete / web.complete" icon="phone-slash" href="/mr/webhooks/call-complete">
    कॉलच्या शेवटची नॉन-ब्लॉकिंग घटना.
  </Card>
  <Card title="फंक्शन टूल्स" icon="screwdriver-wrench" href="/mr/tools/overview">
    `tools[]` साठी पूर्ण JSON स्कीमा आणि स्वाक्षरीकृत एंडपॉइंट करार.
  </Card>
  <Card title="Webhook एंडपॉइंट्स" icon="bolt" href="/mr/webhooks/endpoints">
    `telephony.incoming` / `web.incoming` साठी अनेक URLs सबस्क्राइब करा.
  </Card>
  <Card title="डायनॅमिक कॉल कॉन्फिगरेशन" icon="wand-magic-sparkles" href="/mr/guides/dynamic-call-config">
    प्रत्येक कॉलरसाठी prompt, टूल्स आणि A/B चाचण्यांचे पॅटर्न.
  </Card>
</CardGroup>