---
title: "ہر کال کے لیے متغیرات اور سیاق"
description: "ایجنٹ کو تبدیل کیے بغیر، ہر کال کو اس کی اپنی تفصیلات دیں، چاہے prompt کے لیے نام زد متغیرات کی صورت میں ہوں یا آزاد طرز کی مختصر بریف کے طور پر۔"
---

ہر کال میں کال کے لیے مخصوص ان پٹ کی دو اقسام شامل ہو سکتی ہیں۔ ان میں سے
ایک، یا دونوں کو اکٹھا استعمال کریں:

- **`variables`**: نام والی قدریں جو prompt میں موجود `{{placeholders}}` کو بھرتی ہیں۔ انہیں
  ان فیلڈز کے لیے استعمال کریں جن کا prompt نام سے حوالہ دیتا ہے، جیسے کال کرنے والے کا نام،
  اکاؤنٹ نمبر یا اپائنٹمنٹ کا وقت۔
- **`context`**: prompt کے بعد شامل کیا جانے والا آزاد متن۔ اسے ایسے بریف کے لیے استعمال کریں جو
  کسی ٹیمپلیٹ میں موزوں نہ ہو، جیسے اس کال کے کام کی وضاحت یا پہلے جمع کیے گئے نوٹس۔

دونوں محفوظ کردہ ایجنٹ اور ان لائن کنفیگریشن کے ساتھ، ذیل میں بیان کردہ کال
شروع کرنے کے ہر طریقے میں کام کرتے ہیں۔ ان میں سے کوئی بھی محفوظ کردہ ایجنٹ، اس کی ورژن
ہسٹری یا اس کی دیگر ترتیبات کو تبدیل نہیں کرتا۔

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "appointment_slot": "Tuesday at 10 AM"},
  "context": "Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number."
}
```

## متغیرات

اپنے محفوظ کردہ ایجنٹ کے prompt میں پلیس ہولڈرز شامل کریں، پھر کال شروع کرتے وقت ایک `variables`
آبجیکٹ فراہم کریں۔ ThunderPhone کال کی کنفیگریشن کو وائس رن ٹائم پر بھیجنے سے پہلے متن رینڈر کرتا ہے۔

جب کسی قدر کی ضرورت نہ ہو تو `variables` شامل نہ کریں، `null` نہ بھیجیں (`400` کے ساتھ مسترد کر دیا جاتا ہے)۔

### پلیس ہولڈرز اور ڈیفالٹس

```text
You are calling {{name|Friend}} about account {{account_id}}.
The available appointment is {{ appointment_slot }}.
```

ناموں میں بڑے اور چھوٹے حروف کا فرق ہوتا ہے اور وہ `[A-Za-z_][A-Za-z0-9_]*` کی پیروی کرتے ہیں۔ نام کے
اردگرد خالی جگہ کی اجازت ہے؛ `|` کے بعد کی خالی جگہ ڈیفالٹ کا حصہ ہوتی ہے اور برقرار رہتی ہے۔
جب `name` موجود نہ ہو یا `null` ہو تو `{{name|Friend}}`، `Friend` استعمال کرتا ہے؛ خالی اسٹرنگ واضح طور پر فراہم کردہ قدر ہوتی ہے۔ ڈیفالٹ کے بغیر غائب قدریں خالی اسٹرنگ بن جاتی ہیں اور ان کے نام `unresolved_variables` میں ظاہر ہوتے ہیں۔
ڈبل بریکٹس کے درمیان موجود متن جو درست پلیس ہولڈر نہ ہو، ہٹا دیا جاتا ہے۔ فراہم کردہ ہر قدر کے اندر موجود ڈبل بریکٹس والا
متن الگ سے ہٹا دیا جاتا ہے؛ کوئی قدر اردگرد کے prompt متن یا کسی دوسری قدر کو نہیں ہٹا سکتی۔ غیر جوڑے والے ڈبل بریکٹ ڈیلیمیٹرز
بھی ہٹا دیے جاتے ہیں۔ prompt میں JSON مثالوں میں `{{` استعمال نہیں ہونا چاہیے۔
قدریں سادہ متن ہوتی ہیں، انہیں کبھی کوڈ کے طور پر جانچا نہیں جاتا
اور نہ ہی ٹیمپلیٹس کے طور پر بار بار پھیلایا جاتا ہے۔

ویری ایبلز تصدیقی prompts، آؤٹ باؤنڈ وائس میل
پیغامات، اور رضامندی کے اعلان کے متن میں بھی ظاہر ہو سکتے ہیں، جب وہ فیلڈ فون کال کے لیے بھیجا جائے۔ ایجنٹ کے لیے الگ `first_message` فیلڈ نہیں ہے: اس کی ابتدائی ہدایات prompt میں رکھیں۔ موجودہ وائس میل کے `{agent_name}` اور `{org_name}`
پلیس ہولڈرز کام کرتے رہتے ہیں۔

### قدریں اور حدود

قدریں اسٹرنگز، نمبرز، بولینز، یا `null` ہو سکتی ہیں؛ بولینز `true`
اور `false` کے طور پر رینڈر ہوتے ہیں۔ نیو لائن (`\n`)، ٹیب (`\t`)،
اور کیریج ریٹرن (`\r`) کے علاوہ یونیکوڈ کنٹرول (`Cc`) کریکٹرز، زیرو وِڈتھ
نان جوائنر اور جوائنر (U+200C، U+200D، جو انڈک اور عربی رسم الخط والی
زبانوں میں الفاظ کی املا کرتے ہیں) کے علاوہ فارمیٹ (`Cf`) کریکٹرز، اور
سروگیٹ (`Cs`) کوڈ پوائنٹس ہٹا دیے جاتے ہیں؛ `\r\n` کو `\n` میں نارملائز
کیا جاتا ہے۔ رینڈر ہونے پر ہر قدر
2,000 کریکٹرز تک محدود ہوتی ہے۔ فراہم کردہ اسٹرنگز کو اسٹوریج سے پہلے بھی
صاف اور مختصر کیا جاتا ہے۔ اصل آبجیکٹ **UTF-8 JSON کے 32 KB** میں سما جانا
لازمی ہے؛ بڑے آبجیکٹس کو کال/سیشن ریکویسٹس پر `400` ملتا ہے، جبکہ کیمپین
امپورٹس ہر غلط قطار کی انفرادی رپورٹ دیتے ہیں۔ اریز اور نیسٹڈ آبجیکٹس
قدروں کے طور پر قبول نہیں کیے جاتے۔ غیر مطابقت رکھنے والی میٹاڈیٹا کیز
(مثلاً اسپیس والا CSV ہیڈر) برقرار رکھی اور واپس دکھائی جاتی ہیں، لیکن
انہیں پلیس ہولڈر کے ذریعے ریفرنس نہیں کیا جا سکتا۔

## کانٹیکسٹ

`context` زیادہ سے زیادہ **20,000 کریکٹرز** کی ایک اسٹرنگ ہے۔ ThunderPhone
ویری ایبلز بھرنے کے بعد اسے پرامپٹ کے آخر میں ایک حدبندی والے بلاک کے طور پر
شامل کرتا ہے:

```text
<your prompt, with its variables filled in>

Details for this call:
<call_context>
Ada rescheduled twice last month. She prefers mornings and asked us not to call her work number.
</call_context>
```

ایجنٹ اسے اپنی ہدایات کے ساتھ پڑھتا ہے، اس لیے اسے اس طرح لکھیں جیسے آپ
کال سے پہلے کسی ساتھی کو بریف کر رہے ہوں۔ کانٹیکسٹ ٹیمپلیٹ نہیں ہے:
اس کے اندر `{{name}}` جوں کا توں رہتا ہے۔ اگر متن کو کسی قدر کی ضرورت ہو تو
بھیجنے سے پہلے وہ قدر خود شامل کریں۔

- `null`، خالی اسٹرنگ، یا صرف وائٹ اسپیس کا مطلب ہے کہ کوئی کانٹیکسٹ نہیں ہے۔
- جو قدر اسٹرنگ نہ ہو، یا 20,000 حروف سے زیادہ طویل ہو، اسے کال اور سیشن کی درخواستوں پر `400` کے ساتھ مسترد کر دیا جاتا ہے؛ کنفیگریشن webhook سے یہ تبادلہ اسی طرح ناکام ہوتا ہے جیسے غلط `variables` کی صورت میں ہوتا ہے (نیچے دیکھیں)۔
- شروع اور آخر کی وائٹ اسپیس ہٹا دی جاتی ہے، اور وہی کنٹرول اور فارمیٹ حروف بھی ہٹا دیے جاتے ہیں جو ویری ایبل اقدار میں ہٹائے جاتے ہیں۔
- کانٹیکسٹ کال کے prompt کا حصہ ہے، اس لیے یہ کال کے [prompt سائز](/ur/guides/pricing) میں شمار ہوتا ہے۔

[اسٹیپس](/ur/guides/agent-steps) والے ایجنٹ میں، کانٹیکسٹ کال کے ہر ایجنٹ کے
پرامپٹ کے بعد آتا ہے، ہر اسٹیپ کی ہدایات کے بعد نہیں۔

## اقدار کہاں سے آتی ہیں

### آؤٹ باؤنڈ API

`POST /v1/call` پر `variables` اور `context` بھیجیں:

```json
{
  "from_number": "+15551234567",
  "to_number": "+14155552671",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  },
  "context": "Ada asked to be called back about the late fee on her March invoice."
}
```

دونوں فون نمبر کے ڈیفالٹ آؤٹ باؤنڈ ایجنٹ کے ساتھ یا ان لائن `config.prompt` کے ساتھ بھی کام کرتے ہیں۔ ان لائن کنفیگ کے ساتھ، `context` کو `config` کے اندر بھی رکھا جا سکتا ہے، جو وہی فیلڈ ہے جسے کنفیگریشن ویب ہک واپس کرتا ہے؛ اگر آپ دونوں بھیجتے ہیں، تو ان کا متن یکساں ہونا ضروری ہے۔ مختلف variables یا مختلف context کے ساتھ idempotency key دوبارہ استعمال نہیں کی جا سکتی۔

### مہم CSV

فون نمبر کے علاوہ CSV کالم پہلے ہی رابطہ متغیرات کے طور پر محفوظ ہیں۔ اب ہر ڈائل انہیں خودکار طور پر استعمال کرتا ہے۔ اپنے پلیس ہولڈرز سے مطابقت کے لیے `name`، `account_id`، اور `appointment_slot` جیسے ہیڈرز استعمال کریں۔ موجودہ نام میپنگ پہلے اور آخری نام کے کالموں کو `name` متغیر میں یکجا کر سکتی ہے۔ مہم کے رابطوں کے لیے ہر رابطے کا الگ کانٹیکسٹ نہیں ہوتا۔

### متحرک کنفیگریشن webhook

بلاکنگ کنفیگریشن webhook پاتھ پر، اپنے ادارے میں موجود محفوظ کردہ ایجنٹ کے ساتھ ہر کال کی قدریں واپس کریں۔ Full duplex ایجنٹ کے لیے، کال کسی دوسری معاون زبان میں شروع ہونے پر بھی ایجنٹ کی آواز برقرار رہتی ہے: زبان کے لحاظ سے آواز کی میپنگز اور مقامی آواز کی تبدیلی اس کال پر لاگو نہیں ہوتیں۔

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "[REDACTED_LITERAL]"
}
```

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada", "account_id": "A-17"},
  "context": "Ada called yesterday about a leak in unit 4B; a plumber is booked for Friday."
}
```

جواب کے ویری ایبلز درخواست کی سطح کے ویری ایبلز کو اوور رائٹ کر دیتے ہیں، جبکہ درخواست کی دیگر کیز برقرار رہتی ہیں۔ `null` کی جوابی قدر پلیس ہولڈر کی ڈیفالٹ قدر منتخب کرتی ہے۔
ضم شدہ آبجیکٹ کا سائز بھی 32 KB کے اندر ہونا ضروری ہے۔ محفوظ شدہ ایجنٹ کے جوابات صرف
`agent_id`، `variables`، `context`، `language` اور فی کال
[`timezone`](/ur/guides/dynamic-call-config) قبول کرتے ہیں؛ جب آپ کو
prompt یا دیگر سیٹنگز تبدیل کرنی ہوں تو اِن لائن کنفیگریشن واپس کریں۔ محفوظ شدہ ایجنٹ ویب ہک
جوابات فون اور ویجٹ، دونوں کالز پر ایجنٹ کی تعینات کردہ A/B تقسیم استعمال کرتے ہیں؛
ویری ایبلز ویرینٹ منتخب ہونے کے بعد رینڈر ہوتے ہیں۔ جب جواب کسی غیر مکمل ڈوپلیکس ایجنٹ کے لیے
`language` مقرر کرتا ہے، تو اگر ایجنٹ کے لیے اس زبان کی آواز مقرر ہو تو کال وہی آواز بھی
استعمال کرتی ہے۔ `prompt` پر مشتمل جواب ہمیشہ اِن لائن کنفیگریشن استعمال کرتا ہے: اس جواب میں موجود کوئی بھی `agent_id` نظر انداز کر دیا جاتا ہے، بشمول null یا غیر صحیح عددی میٹا ڈیٹا۔ اِن لائن prompt کو پھر بھی معمول کی توثیق سے گزرنا ضروری ہے۔
اِن لائن ویب ہک جوابات میں `variables` اور `context` بھی شامل ہو سکتے ہیں۔ ایسا `context`
جو اسٹرنگ نہ ہو یا بہت طویل ہو، تبادلے کو ناکام کر دیتا ہے: فون کال مسترد ہو جاتی ہے،
اور ویجٹ سیشن کی درخواست `400` کے ساتھ ناکام ہو جاتی ہے۔ محفوظ شدہ ایجنٹ ویب ہک
جوابات فون اور ویجٹ، دونوں کالز پر ایجنٹ کی تعینات کردہ A/B تقسیم استعمال کرتے ہیں؛
ویری ایبلز ویرینٹ منتخب ہونے کے بعد رینڈر ہوتے ہیں۔ آنے والی فون کالز کے لیے ایسا نمبر استعمال کریں جس کے ساتھ کوئی آنے والا
ایجنٹ مقرر نہ ہو اور اس کا فون نمبر یا تنظیمی ویب ہک کنفیگر کریں؛ ویجٹ کیز `mode="webhook"` استعمال کرتی ہیں۔ اینڈ پوائنٹ سسٹم کی آنے والی اطلاعات بلاکنگ
کنفیگریشن کے جوابات فراہم نہیں کرتیں۔

### ایجنٹ کال سیٹ اپ webhook

کسی نمبر کو اس کے ایجنٹ کے لیے مختص رکھنے اور صرف کال کی قدریں بھرنے کے لیے، ایجنٹ کو ایک [کال سیٹ اپ ویب ہک](/ur/webhooks/call-incoming) دیں۔
ہر آنے والی کال سے پہلے، جس کا ایجنٹ کسی نمبر پر جواب دیتا ہے، ویب ہک کو کال اور ایجنٹ کی id، نام اور ورژن موصول ہوتے ہیں، اور یہ `agent_id` کی ضرورت کے بغیر اوپر والی ہی `variables`، `context`، `language` اور فی کال `timezone` کے ساتھ جواب دیتا ہے۔ ایسا ایجنٹ جس کی ترتیبات میں ڈیفالٹ کے بغیر پلیس ہولڈر استعمال ہوتا ہو، فون نمبر پر جواب دینے کے لیے اسے اس ویب ہک کی ضرورت ہوتی ہے: ویب ہک ناکام ہونے پر کال شروع نہیں ہوتی۔ `{{name|there}}` جیسے ڈیفالٹ والے پلیس ہولڈر ایجنٹ کو اس کے بغیر جواب دینے دیتے ہیں۔

### SIP ہیڈرز

وہ کالز جو SIP کے ذریعے کسی ایجنٹ تک پہنچتی ہیں (ایک [SIP ایڈریس](/ur/guides/sip-addresses)، یا دستی SIP کنکشن پر موجود نمبر) `X-*` اور `User-to-User` ہیڈرز میں سیاق لے جا سکتی ہیں۔ ہر ہیڈر ایک `sip_` ویری ایبل بن جاتا ہے، جیسے `{{sip_x_amzn_connectcontactid}}` یا `{{sip_uui}}`، اور اس کی ترجیح سب سے کم ہوتی ہے: API یا webhook سے اسی نام کی ویلیو کو فوقیت ملتی ہے۔ [SIP ہیڈرز میں کال کا سیاق منتقل کریں](/ur/guides/sip-addresses) دیکھیں۔ ہیڈر ویلیوز بھیجنے والا مقرر کرتا ہے، اس لیے انہیں کسی بھی براؤزر سے فراہم کردہ ویلیو کی طرح غیر قابلِ اعتماد سمجھیں۔

### ویجٹ سیشن API

`POST /v1/widget/session` اعلیٰ سطح کے `variables` اور `language` قبول کرتا ہے۔ اس کی publishable
key محفوظ شدہ ایجنٹ منتخب کرتی ہے۔ Webhook-mode keys ان اقدار کو
configuration webhook کو بھیجتی ہیں اور جواب کو اوپر بیان کردہ طریقے کے مطابق ضم کرتی ہیں۔
براؤزر سے فراہم کردہ widget `variables` کلائنٹ کے زیرِ کنٹرول ہوتے ہیں، اوپر بیان کردہ توثیق اور
string صفائی کے بعد بعینہٖ `web.incoming` میں بھیجے جاتے ہیں، اور completion webhooks اور کال ہسٹری میں
دوبارہ شامل کیے جاتے ہیں۔ انہیں قابلِ اعتماد شناخت یا authorization ڈیٹا نہ سمجھیں۔

ویجٹ کا اپنا براؤزر `context` فیلڈ مختلف ہے: یہ اس صفحے کا متن لے کر جاتا ہے
جس پر وزیٹر موجود ہے، جسے ایجنٹ ویب سائٹ کے مواد کے طور پر سمجھتا ہے
([ویب ویجٹ ایمبیڈ کریں](/ur/guides/embed-web-widget) دیکھیں)۔ ویجٹ کال کا
فی-کال کانٹیکسٹ، اوپر کی طرح، ویب ہک موڈ کی کی کنفیگریشن ویب ہک سے آتا ہے۔
جب کسی کال میں دونوں موجود ہوں تو پہلے فی-کال کانٹیکسٹ آتا ہے، پھر صفحے کا
مواد۔

### ریئل ٹائم سیشن API

`POST /v1/realtime/sessions`، `agent_id` یا ان لائن `config` کے ساتھ، اعلیٰ سطح کے `variables`، `context` اور `language` قبول کرتا ہے:

```json
{
  "agent_id": 12,
  "variables": {"name": "Ada"},
  "context": "Ada is calling from the front desk about a guest's lost key card."
}
```

`context` صرف ٹاپ لیول پر جاتا ہے؛ ان لائن `config` اسے نامعلوم فیلڈ کے
طور پر مسترد کرتا ہے۔

### ریئل ٹائم WebSocket

محفوظ شدہ ایجنٹ کے ساتھ، محفوظ شدہ ایجنٹ کا تعینات کردہ prompt ہی اس کا prompt رہتا ہے۔
`session.instructions` کال کا سیاق بن جاتا ہے، `session.prompt.variables`
(یا `session.config.variables`) اس کے متغیرات بن جاتے ہیں، اور `session.language`
اس کی فی کال زبان بن جاتی ہے۔ پہلی `session.update` میں
`session.prompt.id` کے ذریعے ایجنٹ منتخب کریں؛ یہ اپ ڈیٹ موصول ہوتے ہی سیشن شروع ہو جاتا ہے:

```json
{
  "type": "session.update",
  "session": {
    "type": "realtime",
    "prompt": {"id": "12", "variables": {"name": "Ada"}},
    "instructions": "Ada asked for a callback about her delivery window."
  }
}
```

کنکشن URL پر `?agent_id=12` ساکٹ کے منسلک ہوتے ہی، کسی بھی
`session.update` سے پہلے ایجنٹ شروع کر دیتا ہے، اس لیے اس میں ہر کال کا کوئی ان پٹ نہیں ہوتا۔ پہلے
`session.update` کا انتظار کرنے اور اس کی ہدایات اور متغیرات استعمال کرنے کے لیے
`&wait_for_session_update=1` شامل کریں۔

اِن لائن سیشن میں (محفوظ شدہ ایجنٹ کے بغیر)، `session.instructions` پہلے کی طرح
خود prompt ہوتا ہے۔ Builder مائیک اور نقلی ٹیسٹ کالز ڈیفالٹس اور غائب پلیس ہولڈرز کو حل کرتی ہیں، لیکن ان میں ہر کال کے لیے متغیرات یا کانٹیکسٹ ان پٹ نہیں ہوتا۔

## کال کے بعد

`GET /v1/calls`، `GET /v1/calls/{call_id}`، `telephony.complete`، اور `web.complete` میں
حتمی مرج شدہ `variables` اور `unresolved_variables` شامل ہوتے ہیں۔ وہ legacy completion payloads
جن میں `data.history` شامل ہو، ان میں بھی یہ شامل ہوتے ہیں:

```json
{
  "variables": {"name": "Ada", "account_id": "A-17"},
  "unresolved_variables": ["appointment_slot"]
}
```

کال کا `prompt_snapshot` (`GET /v1/calls/{call_id}`) ایجنٹ کا
prompt دکھاتا ہے، جس میں اس کے متغیرات بھرے گئے ہیں اور سیاق کا بلاک شامل ہے۔

مکمل شدہ کال کو اس کے ماخذ ریکارڈ سے جوڑنے کے لیے اپنا CRM یا ٹاسک شناخت کنندہ
متغیرات کے آبجیکٹ میں محفوظ کریں۔ متغیرات اور سیاق کال ریکارڈ کے ساتھ برقرار رہتے ہیں؛
صرف وہ معلومات بھیجیں جنہیں کال ہسٹری اور ویب ہکس میں برقرار رکھنا مناسب ہو۔

کسی کال کے ری پلے، [تصدیقی سیٹس](/api-reference/validation-sets)،
[ری پلے رنز](/api-reference/replay-runs) اور
[تحقیقات](/api-reference/investigations) میں، زیرِ آزمائش prompt کے ساتھ اس کال کے متغیرات اور
سیاق استعمال کرتے ہیں، تاکہ ری پلے اس بات کی جانچ کرے جو اس کال میں ایجنٹ کو بتائی گئی ہوتی۔

## موجودہ prompt مطابقت

رینڈرنگ موجودہ محفوظ شدہ ایجنٹ اور A/B ویریئنٹ prompts، ان لائن
آؤٹ باؤنڈ اور ریئل ٹائم کنفیگریشنز، اور کنفیگریشن webhooks کے ذریعے واپس آنے والے prompts پر بھی لاگو ہوتی ہے۔ نامعلوم `{{name}}` پلیس ہولڈرز خالی متن بن جاتے ہیں، چاہے کوئی `variables` فراہم نہ کیے گئے ہوں۔ رول آؤٹ سے پہلے موجودہ prompts چیک کریں، جن میں بیرونی طور پر فراہم کردہ ان لائن/webhook prompts بھی شامل ہیں جن کی ThunderPhone فہرست نہیں بنا سکتا۔ Builder مائیک اور سمولیشن کالز بھی یہی ڈیفالٹ/خالی رویہ لاگو کرتی ہیں۔
