Open in
ہر کال کے لیے متغیرات اور سیاق
ایجنٹ کو تبدیل کیے بغیر، ہر کال کو اس کی اپنی تفصیلات دیں، چاہے prompt کے لیے نام زد متغیرات کی صورت میں ہوں یا آزاد طرز کی مختصر بریف کے طور پر۔
ہر کال میں کال کے لیے مخصوص ان پٹ کی دو اقسام شامل ہو سکتی ہیں۔ ان میں سے ایک، یا دونوں کو اکٹھا استعمال کریں:
variables: نام والی قدریں جو prompt میں موجود{{placeholders}}کو بھرتی ہیں۔ انہیں ان فیلڈز کے لیے استعمال کریں جن کا prompt نام سے حوالہ دیتا ہے، جیسے کال کرنے والے کا نام، اکاؤنٹ نمبر یا اپائنٹمنٹ کا وقت۔context: prompt کے بعد شامل کیا جانے والا آزاد متن۔ اسے ایسے بریف کے لیے استعمال کریں جو کسی ٹیمپلیٹ میں موزوں نہ ہو، جیسے اس کال کے کام کی وضاحت یا پہلے جمع کیے گئے نوٹس۔
دونوں محفوظ کردہ ایجنٹ اور ان لائن کنفیگریشن کے ساتھ، ذیل میں بیان کردہ کال شروع کرنے کے ہر طریقے میں کام کرتے ہیں۔ ان میں سے کوئی بھی محفوظ کردہ ایجنٹ، اس کی ورژن ہسٹری یا اس کی دیگر ترتیبات کو تبدیل نہیں کرتا۔
{
"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 کے ساتھ مسترد کر دیا جاتا ہے)۔
پلیس ہولڈرز اور ڈیفالٹس
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
ویری ایبلز بھرنے کے بعد اسے پرامپٹ کے آخر میں ایک حدبندی والے بلاک کے طور پر
شامل کرتا ہے:
<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 سائز میں شمار ہوتا ہے۔
اسٹیپس والے ایجنٹ میں، کانٹیکسٹ کال کے ہر ایجنٹ کے پرامپٹ کے بعد آتا ہے، ہر اسٹیپ کی ہدایات کے بعد نہیں۔
اقدار کہاں سے آتی ہیں
آؤٹ باؤنڈ API
POST /v1/call پر variables اور context بھیجیں:
{
"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 ایجنٹ کے لیے، کال کسی دوسری معاون زبان میں شروع ہونے پر بھی ایجنٹ کی آواز برقرار رہتی ہے: زبان کے لحاظ سے آواز کی میپنگز اور مقامی آواز کی تبدیلی اس کال پر لاگو نہیں ہوتیں۔
{
"agent_id": 12,
"variables": {"name": "Ada", "account_id": "A-17"},
"context": "[REDACTED_LITERAL]"
}{
"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 قبول کرتے ہیں؛ جب آپ کو
prompt یا دیگر سیٹنگز تبدیل کرنی ہوں تو اِن لائن کنفیگریشن واپس کریں۔ محفوظ شدہ ایجنٹ ویب ہک
جوابات فون اور ویجٹ، دونوں کالز پر ایجنٹ کی تعینات کردہ A/B تقسیم استعمال کرتے ہیں؛
ویری ایبلز ویرینٹ منتخب ہونے کے بعد رینڈر ہوتے ہیں۔ جب جواب کسی غیر مکمل ڈوپلیکس ایجنٹ کے لیے
language مقرر کرتا ہے، تو اگر ایجنٹ کے لیے اس زبان کی آواز مقرر ہو تو کال وہی آواز بھی
استعمال کرتی ہے۔ prompt پر مشتمل جواب ہمیشہ اِن لائن کنفیگریشن استعمال کرتا ہے: اس جواب میں موجود کوئی بھی agent_id نظر انداز کر دیا جاتا ہے، بشمول null یا غیر صحیح عددی میٹا ڈیٹا۔ اِن لائن prompt کو پھر بھی معمول کی توثیق سے گزرنا ضروری ہے۔
اِن لائن ویب ہک جوابات میں variables اور context بھی شامل ہو سکتے ہیں۔ ایسا context
جو اسٹرنگ نہ ہو یا بہت طویل ہو، تبادلے کو ناکام کر دیتا ہے: فون کال مسترد ہو جاتی ہے،
اور ویجٹ سیشن کی درخواست 400 کے ساتھ ناکام ہو جاتی ہے۔ محفوظ شدہ ایجنٹ ویب ہک
جوابات فون اور ویجٹ، دونوں کالز پر ایجنٹ کی تعینات کردہ A/B تقسیم استعمال کرتے ہیں؛
ویری ایبلز ویرینٹ منتخب ہونے کے بعد رینڈر ہوتے ہیں۔ آنے والی فون کالز کے لیے ایسا نمبر استعمال کریں جس کے ساتھ کوئی آنے والا
ایجنٹ مقرر نہ ہو اور اس کا فون نمبر یا تنظیمی ویب ہک کنفیگر کریں؛ ویجٹ کیز mode="webhook" استعمال کرتی ہیں۔ اینڈ پوائنٹ سسٹم کی آنے والی اطلاعات بلاکنگ
کنفیگریشن کے جوابات فراہم نہیں کرتیں۔
ایجنٹ کال سیٹ اپ webhook
کسی نمبر کو اس کے ایجنٹ کے لیے مختص رکھنے اور صرف کال کی قدریں بھرنے کے لیے، ایجنٹ کو ایک کال سیٹ اپ ویب ہک دیں۔
ہر آنے والی کال سے پہلے، جس کا ایجنٹ کسی نمبر پر جواب دیتا ہے، ویب ہک کو کال اور ایجنٹ کی id، نام اور ورژن موصول ہوتے ہیں، اور یہ agent_id کی ضرورت کے بغیر اوپر والی ہی variables، context، language اور فی کال timezone کے ساتھ جواب دیتا ہے۔ ایسا ایجنٹ جس کی ترتیبات میں ڈیفالٹ کے بغیر پلیس ہولڈر استعمال ہوتا ہو، فون نمبر پر جواب دینے کے لیے اسے اس ویب ہک کی ضرورت ہوتی ہے: ویب ہک ناکام ہونے پر کال شروع نہیں ہوتی۔ {{name|there}} جیسے ڈیفالٹ والے پلیس ہولڈر ایجنٹ کو اس کے بغیر جواب دینے دیتے ہیں۔
SIP ہیڈرز
وہ کالز جو SIP کے ذریعے کسی ایجنٹ تک پہنچتی ہیں (ایک SIP ایڈریس، یا دستی SIP کنکشن پر موجود نمبر) X-* اور User-to-User ہیڈرز میں سیاق لے جا سکتی ہیں۔ ہر ہیڈر ایک sip_ ویری ایبل بن جاتا ہے، جیسے {{sip_x_amzn_connectcontactid}} یا {{sip_uui}}، اور اس کی ترجیح سب سے کم ہوتی ہے: API یا webhook سے اسی نام کی ویلیو کو فوقیت ملتی ہے۔ SIP ہیڈرز میں کال کا سیاق منتقل کریں دیکھیں۔ ہیڈر ویلیوز بھیجنے والا مقرر کرتا ہے، اس لیے انہیں کسی بھی براؤزر سے فراہم کردہ ویلیو کی طرح غیر قابلِ اعتماد سمجھیں۔
ویجٹ سیشن API
POST /v1/widget/session اعلیٰ سطح کے variables اور language قبول کرتا ہے۔ اس کی publishable
key محفوظ شدہ ایجنٹ منتخب کرتی ہے۔ Webhook-mode keys ان اقدار کو
configuration webhook کو بھیجتی ہیں اور جواب کو اوپر بیان کردہ طریقے کے مطابق ضم کرتی ہیں۔
براؤزر سے فراہم کردہ widget variables کلائنٹ کے زیرِ کنٹرول ہوتے ہیں، اوپر بیان کردہ توثیق اور
string صفائی کے بعد بعینہٖ web.incoming میں بھیجے جاتے ہیں، اور completion webhooks اور کال ہسٹری میں
دوبارہ شامل کیے جاتے ہیں۔ انہیں قابلِ اعتماد شناخت یا authorization ڈیٹا نہ سمجھیں۔
ویجٹ کا اپنا براؤزر context فیلڈ مختلف ہے: یہ اس صفحے کا متن لے کر جاتا ہے
جس پر وزیٹر موجود ہے، جسے ایجنٹ ویب سائٹ کے مواد کے طور پر سمجھتا ہے
(ویب ویجٹ ایمبیڈ کریں دیکھیں)۔ ویجٹ کال کا
فی-کال کانٹیکسٹ، اوپر کی طرح، ویب ہک موڈ کی کی کنفیگریشن ویب ہک سے آتا ہے۔
جب کسی کال میں دونوں موجود ہوں تو پہلے فی-کال کانٹیکسٹ آتا ہے، پھر صفحے کا
مواد۔
ریئل ٹائم سیشن API
POST /v1/realtime/sessions، agent_id یا ان لائن config کے ساتھ، اعلیٰ سطح کے variables، context اور language قبول کرتا ہے:
{
"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 کے ذریعے ایجنٹ منتخب کریں؛ یہ اپ ڈیٹ موصول ہوتے ہی سیشن شروع ہو جاتا ہے:
{
"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 شامل ہو، ان میں بھی یہ شامل ہوتے ہیں:
{
"variables": {"name": "Ada", "account_id": "A-17"},
"unresolved_variables": ["appointment_slot"]
}کال کا prompt_snapshot (GET /v1/calls/{call_id}) ایجنٹ کا
prompt دکھاتا ہے، جس میں اس کے متغیرات بھرے گئے ہیں اور سیاق کا بلاک شامل ہے۔
مکمل شدہ کال کو اس کے ماخذ ریکارڈ سے جوڑنے کے لیے اپنا CRM یا ٹاسک شناخت کنندہ متغیرات کے آبجیکٹ میں محفوظ کریں۔ متغیرات اور سیاق کال ریکارڈ کے ساتھ برقرار رہتے ہیں؛ صرف وہ معلومات بھیجیں جنہیں کال ہسٹری اور ویب ہکس میں برقرار رکھنا مناسب ہو۔
کسی کال کے ری پلے، تصدیقی سیٹس، ری پلے رنز اور تحقیقات میں، زیرِ آزمائش prompt کے ساتھ اس کال کے متغیرات اور سیاق استعمال کرتے ہیں، تاکہ ری پلے اس بات کی جانچ کرے جو اس کال میں ایجنٹ کو بتائی گئی ہوتی۔
موجودہ prompt مطابقت
رینڈرنگ موجودہ محفوظ شدہ ایجنٹ اور A/B ویریئنٹ prompts، ان لائن
آؤٹ باؤنڈ اور ریئل ٹائم کنفیگریشنز، اور کنفیگریشن webhooks کے ذریعے واپس آنے والے prompts پر بھی لاگو ہوتی ہے۔ نامعلوم {{name}} پلیس ہولڈرز خالی متن بن جاتے ہیں، چاہے کوئی variables فراہم نہ کیے گئے ہوں۔ رول آؤٹ سے پہلے موجودہ prompts چیک کریں، جن میں بیرونی طور پر فراہم کردہ ان لائن/webhook prompts بھی شامل ہیں جن کی ThunderPhone فہرست نہیں بنا سکتا۔ Builder مائیک اور سمولیشن کالز بھی یہی ڈیفالٹ/خالی رویہ لاگو کرتی ہیں۔