---
title: "telephony.incoming / web.incoming"
description: "உள்வரும் அழைப்பின் கட்டமைப்பை நிகழ்நேரத்தில் வடிவமைக்கும் தடைசெய்யும் webhook."
---

ஒதுக்கப்பட்ட ஏஜென்ட் **இல்லாத** எண்ணை உள்வரும் தொலைபேசி அழைப்பு அடையும்போது, அல்லது `mode="webhook"` இல் உள்ள வெளியிடக்கூடிய விசையில் வலை விட்ஜெட் அமர்வு தொடங்கும்போது, ThunderPhone உங்கள்
[மரபு வெப்ஹுக் URL](/api-reference/organizations#legacy-single-url-webhook)-க்கு **தடுக்கும்**
`telephony.incoming` / `web.incoming` கோரிக்கையை அனுப்பி, உள்ளமைவு பதிலுக்காக அதிகபட்சம் **10 வினாடிகள்** காத்திருக்கும். ஒவ்வொரு அழைப்பிற்கும் prompt, குரல் மற்றும் கருவிகளை மாறும் வகையில் தேர்ந்தெடுக்க இந்தப் பரிமாற்றத்தைப் பயன்படுத்துங்கள் —
முழுமையான செயல்முறைக்கு [மாறும் அழைப்பு உள்ளமைவு வழிகாட்டி](/ta/guides/dynamic-call-config)-ஐப் பார்க்கவும்.

<Note>
  சந்தா பெற்ற [வெப்ஹுக் இறுதிப்புள்ளிகளும்](/ta/webhooks/endpoints)
  `telephony.incoming` / `web.incoming` பெறும் — ஏஜென்ட் உள்ளமைக்கப்பட்டதா இல்லையா என்பதைப் பொருட்படுத்தாமல் **ஒவ்வொரு** உள்வரும் அழைப்பு
  மற்றும் வலை அமர்விற்கும் — ஆனால் அந்த அனுப்புதல்கள் `event_id` கொண்ட
  அனுப்பிவிட்டு மறக்கும் அறிவிப்புகளே; அவை ஒருபோதும் தடுப்பவை அல்ல.
  மரபு ஒற்றை-URL வெப்ஹுக் மட்டுமே இந்தப் பக்கத்தில் உள்ள உள்ளமைவுப்
  பரிமாற்றத்தைக் கொண்டுள்ளது. இறுதிப்புள்ளி அறிவிப்பு வடிவங்கள்
  [நிகழ்வுகள் பட்டியலில்](/ta/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` | 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` | array of string | இல்லை | ஏஜென்ட் மாறக்கூடிய கூடுதல் மொழிகள் |
| `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](/ta/tools/overview) ஐப் பார்க்கவும்) |
| `call_id` | integer | இல்லை | கோரிக்கையின் அழைப்பு id-யின் விருப்ப எக்கோ; புறக்கணிக்கப்படும் |

<Note>
  அறியப்படாத மேல்-நிலை விசைகள் அமைதியாக **புறக்கணிக்கப்படும்** — எழுத்துப்பிழையுள்ள புலப்
  பெயர் கட்டமைப்பை நிராகரிக்காது; அது பயன்படுத்தப்படாது. பேச்சு வரிசையும்
  `max_hold_seconds`-உம் இங்கே ஏற்கப்படாது; அவை [Agent](/api-reference/agents)-இல் மட்டுமே
  கட்டமைக்கப்படலாம்.
</Note>

`prompt` மற்றும் `voice` அவசியம் என்பதால், `{}` அல்லது சரிபார்ப்பில் தோல்வியடையும் எந்தப்
பதிலையும் திருப்பி அனுப்பினால் அழைப்பு `422` உடன் நிராகரிக்கப்படும் — இந்தப் பாதையில்
நிலையான ஏஜென்ட் மீள்பயன்பாடு இல்லை (வெப்ஹுக் முறையில் ஒரு எண்ணுக்கோ விசைக்கோ
ஒதுக்கப்பட்ட ஏஜென்ட் இல்லை).

---

## பதில் அளவு வரம்பு

<Warning>
  கட்டமைப்பு பதில்கள் **5 MiB** வரை மட்டுப்படுத்தப்பட்டுள்ளன. ஒரு ஹேண்ட்லர்
  `2xx` நிலையை உள்ளடக்கியிருந்தாலும், அதைவிட பெரிய பதிலைத் திருப்பினால்,
  பதில் வரம்பை மீறியதாக ThunderPhone தெரிவித்து அழைப்பு அல்லது விட்ஜெட்
  அமர்வை நிராகரிக்கும். அழைப்பு அமைப்பிற்குத் தேவையான புலங்களுக்குள் பதிலை
  வைத்திருங்கள்; பெரிய தரவை கட்டமைப்பில் உட்பொதிப்பதற்குப் பதிலாக function
  tools அல்லது வேறு சேவையின் பின்னால் ஹோஸ்ட் செய்யுங்கள்.
</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>

---

## function tools உடனான பதில்

உரையாடலின் நடுவில் AI உங்கள் API-களை அழைக்கக்கூடிய வகையில் tools-ஐ இணைக்கவும்:

```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>
  இந்த பரிமாற்றத்தில் கையொப்பமிட்ட அதே **நிறுவன webhook
  ரகசியம்** மூலம் tool-endpoint கோரிக்கைகளுக்கும் கையொப்பமிடப்படும்.
  துல்லியமான அமைப்பு மற்றும் கையொப்பமிடப்பட்ட கோரிக்கை வடிவத்திற்கு
  [Function Tools](/ta/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="/ta/webhooks/call-complete">
    செயல்பாட்டைத் தடுக்காத அழைப்பு-முடிவு நிகழ்வு.
  </Card>
  <Card title="செயல்பாட்டு கருவிகள்" icon="screwdriver-wrench" href="/ta/tools/overview">
    `tools[]`-க்கான முழுமையான JSON ஸ்கீமாவும் கையொப்பமிடப்பட்ட முடிவுப்புள்ளி ஒப்பந்தமும்.
  </Card>
  <Card title="வெப்ஹுக் முடிவுப்புள்ளிகள்" icon="bolt" href="/ta/webhooks/endpoints">
    பல URL-களை `telephony.incoming` / `web.incoming`-க்கு சந்தா செய்யுங்கள்.
  </Card>
  <Card title="மாறும் அழைப்பு கட்டமைப்பு" icon="wand-magic-sparkles" href="/ta/guides/dynamic-call-config">
    ஒவ்வொரு அழைப்பாளருக்கும் உரிய prompt-கள், கருவிகள் மற்றும் A/B சோதனைகளுக்கான வடிவங்கள்.
  </Card>
</CardGroup>