---
title: "telephony.incoming / web.incoming"
description: "بلاکنگ webhook جو آنے والی کال کی کنفیگریشن کو حقیقی وقت میں تشکیل دیتا ہے۔"
---

جب کسی نمبر پر **مقرر کردہ ایجنٹ کے بغیر**
ان باؤنڈ فون کال آتی ہے، یا کسی قابلِ اشاعت کلید پر
`mode="webhook"` میں ویب ویجٹ سیشن شروع ہوتا ہے، تو ThunderPhone آپ کے
[پرانے ویب ہک URL](/api-reference/organizations#legacy-single-url-webhook)
کو ایک **روکنے والی**
`telephony.incoming` / `web.incoming` درخواست بھیجتا ہے اور کنفیگریشن کے جواب کے لیے
**10 سیکنڈ** تک انتظار کرتا ہے۔ ہر کال کے لیے پرامپٹ، آواز اور ٹولز
متحرک طور پر منتخب کرنے کے لیے اس تبادلے کو استعمال کریں —
مکمل طریقۂ کار کے لیے [متحرک کال کنفیگریشن گائیڈ](/ur/guides/dynamic-call-config)
دیکھیں۔

<Note>
  سبسکرائب شدہ [ویب ہک اینڈ پوائنٹس](/ur/webhooks/endpoints) کو بھی
  `telephony.incoming` / `web.incoming` موصول ہوتے ہیں — **ہر** ان باؤنڈ کال
  اور ویب سیشن کے لیے، خواہ ایجنٹ کنفیگر ہو یا نہ ہو — لیکن یہ ترسیلات
  `event_id` کے ساتھ بغیر انتظار کی اطلاعات ہوتی ہیں، کبھی روکنے والی نہیں۔
  صرف پرانا واحد-URL ویب ہک اس صفحے پر موجود کنفیگریشن تبادلہ رکھتا ہے۔
  اینڈ پوائنٹ اطلاعات کی ساختیں [ایونٹس کیٹلاگ](/ur/webhooks/events)
  میں موجود ہیں۔
</Note>

اس روکنے والے تبادلے کا کوئی متبادل نہیں: اگر آپ کا ہینڈلر
غیر-2xx اسٹیٹس واپس کرے، وقت ختم ہو جائے، یا ایسی کنفیگ واپس کرے جو
توثیق میں ناکام ہو، تو کال مسترد کر دی جاتی ہے (فون کال کنیکٹ نہیں ہوتی؛
ویجٹ سیشن کی درخواست `502`/`422` کے ساتھ ناکام ہوتی ہے)۔ فوری جواب دیں —
جب آپ فیصلہ کر رہے ہوتے ہیں تو کال کرنے والا رنگ بیک سن رہا ہوتا ہے۔

<Warning>
  **ویب ہک سے کنفیگر شدہ کالز میں ThunderPhone کی رضامندی کا
  اعلان شامل نہیں ہوتا۔** اس تبادلے کے ذریعے کنفیگر کی گئی کالز
  ایجنٹ سطح کے کال-آغاز اعلان کو نظر انداز کرتی ہیں اور ThunderPhone کے
  رضامندی-اعلان فریم ورک (سروس کی شرائط، "ریکارڈنگ اور رضامندی" سیکشن)
  سے واضح طور پر خارج ہیں۔ ان کالز پر درکار ہر ریکارڈنگ، نگرانی،
  AI-شرکت، اور کالر-شناخت کے نوٹس اور رضامندی کی مکمل ذمہ داری صرف
  آپ کی تنظیم کی ہے — ان کالز کو پھر بھی ریکارڈ، نقلِ تحریر، تجزیہ،
  اور AI کے ذریعے سروس فراہم کی جا سکتی ہے۔ اس راستے کو فعال کرنے سے پہلے
  مطلوبہ انکشافات کو اپنے کال فلو میں شامل کریں۔
</Warning>

## درخواست پے لوڈ

فون کالز کے لیے (`telephony.incoming`):

```json
{
  "type": "telephony.incoming",
  "data": {
    "call_id":     987654321,
    "from_number": "+14155550199",
    "to_number":   "+15551234567"
  }
}
```

| فیلڈ | قسم | وضاحت |
|-------|------|-------------|
| `call_id` | عدد صحیح | کال آئی ڈی — اس کال کے تمام ایونٹس میں مستقل |
| `from_number` | اسٹرنگ | E.164 کالر نمبر |
| `to_number` | اسٹرنگ | 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` | عدد صحیح | کال آئی ڈی |
| `origin_domain` | اسٹرنگ | ویجٹ کی میزبانی کرنے والے صفحے کا اصل ماخذ |
| `publishable_key_prefix` | اسٹرنگ | سیشن کھولنے والی قابلِ اشاعت کلید کے ابتدائی حروف |
| `language`, `primary_language` | اسٹرنگ | ویجٹ سیشن میں زبان تبدیل کرنے کی درخواست ہونے پر موجود |
| `voice` | اسٹرنگ | ویجٹ سیشن میں آواز تبدیل کرنے کی درخواست ہونے پر موجود |
| `website_context` | اسٹرنگ | ویجٹ کے ذریعے ہر سیشن کے لیے صفحے کا سیاق بھیجے جانے پر موجود |

<Note>
  ویب ہک موڈ ویجٹس، جب قابلِ اشاعت کلید کا اپنا `webhook_url` مقرر ہو،
  تو یہ درخواست اسی پر بھیجتے ہیں، ورنہ تنظیمی سطح کے ویب ہک URL کو استعمال کرتے ہیں۔
  دونوں صورتوں میں اس پر تنظیم کے ویب ہک `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` | اسٹرنگ | ہاں | ایجنٹ کو چلانے والا سسٹم پرامپٹ |
| `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` ڈیفالٹ برقرار رکھتا ہے |
| `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` |
| `acknowledgement_prompt_mode` | اسٹرنگ | نہیں | `auto` (ڈیفالٹ) یا `manual` (Storm-with-ack پروڈکٹس) |
| `acknowledgement_prompt` | اسٹرنگ | نہیں | جب `acknowledgement_prompt_mode="manual"` ہو تو استعمال ہوتا ہے |
| `silence_interval_seconds` | انٹیجر \| نل | نہیں | 5–120۔ چیک اِن سے پہلے کالر کی خاموشی کے سیکنڈز |
| `silence_max_checkins` | انٹیجر \| نل | نہیں | 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](/ur/tools/overview) دیکھیں) |
| `call_id` | انٹیجر | نہیں | درخواست کی کال آئی ڈی کا اختیاری ایکو؛ نظر انداز کیا جاتا ہے |

<Note>
  نامعلوم ٹاپ لیول کیز کو خاموشی سے **نظر انداز** کر دیا جاتا ہے — غلط ہجے والا
  فیلڈ نام کنفیگ کو مسترد نہیں کرتا، بس لاگو نہیں ہوتا۔ بولنے کی ترتیب
  اور `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 گفتگو کے دوران آپ کی APIs کو کال کر سکے:

```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>
  ٹول-اینڈپوائنٹ درخواستوں پر اسی **ادارے کے ویب ہک سیکرٹ**
  سے دستخط ہوتے ہیں جس سے اس تبادلے پر دستخط ہوئے تھے۔ درست ساخت اور
  دستخط شدہ درخواست کے فارمیٹ کے لیے
  [فنکشن ٹولز](/ur/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="/ur/webhooks/call-complete">
    کال ختم ہونے کا نان بلاکنگ ایونٹ۔
  </Card>
  <Card title="فنکشن ٹولز" icon="screwdriver-wrench" href="/ur/tools/overview">
    `tools[]` اور دستخط شدہ اینڈ پوائنٹ معاہدے کے لیے مکمل JSON اسکیما۔
  </Card>
  <Card title="ویب ہک اینڈ پوائنٹس" icon="bolt" href="/ur/webhooks/endpoints">
    `telephony.incoming` / `web.incoming` کے لیے متعدد URLs سبسکرائب کریں۔
  </Card>
  <Card title="متحرک کال کنفیگریشن" icon="wand-magic-sparkles" href="/ur/guides/dynamic-call-config">
    ہر کالر کے لیے پرامپٹس، ٹولز، اور A/B ٹیسٹس کے نمونے۔
  </Card>
</CardGroup>