ہر کال کے متغیرات

ہر کال کے لیے محفوظ شدہ ایجنٹ کو اس کے تعینات prompt، ٹولز یا ترتیبات تبدیل کیے بغیر ذاتی نوعیت دیں۔

اپنے محفوظ کردہ ایجنٹ کے 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) کریکٹرز، تمام فارمیٹ (Cf) کریکٹرز، اور سرگیٹ (Cs) کوڈ پوائنٹس ہٹا دیے جاتے ہیں؛ \r\n کو \n میں نارملائز کیا جاتا ہے۔ رینڈر ہونے پر ہر قدر 2,000 کریکٹرز تک محدود ہوتی ہے۔ فراہم کردہ اسٹرنگز کو اسٹوریج سے پہلے بھی صاف کیا جاتا ہے اور مختصر کیا جاتا ہے۔ اصل آبجیکٹ UTF-8 JSON کے 32 KB میں سما جانا چاہیے؛ اس سے بڑے آبجیکٹس کو کال/سیشن کی درخواستوں پر 400 ملتا ہے، جبکہ کیمپین امپورٹس ہر غلط قطار کو الگ سے رپورٹ کرتے ہیں۔ اریز اور نیسٹڈ آبجیکٹس کو قدروں کے طور پر قبول نہیں کیا جاتا۔ غیر مطابقت رکھنے والی میٹاڈیٹا کیز (مثلاً خالی جگہ والا CSV ہیڈر) برقرار رکھی جاتی ہیں اور واپس بھیجی جاتی ہیں، مگر انہیں پلیس ہولڈر کے ذریعے حوالہ نہیں دیا جا سکتا۔

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

آؤٹ باؤنڈ API

POST /v1/call میں agent_id کے ساتھ variables بھیجیں:

{
  "from_number": "+15551234567",
  "to_number": "+14155550199",
  "agent_id": 12,
  "variables": {
    "name": "Ada",
    "account_id": "A-17",
    "appointment_slot": "Tuesday at 10 AM"
  }
}

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

مہم CSV

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

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

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

{"agent_id": 12, "variables": {"name": "Ada", "account_id": "A-17"}}

رسپانس کی keys درخواست کی سطح کے variables کو اووررائٹ کرتی ہیں، جبکہ درخواست کی دیگر keys برقرار رہتی ہیں۔ null کی رسپانس قدر placeholder کا ڈیفالٹ منتخب کرتی ہے۔ مرج شدہ آبجیکٹ کو بھی 32 KB میں ہونا ضروری ہے۔ محفوظ ایجنٹ کے رسپانس صرف agent_id اور variables قبول کرتے ہیں؛ جب آپ کو prompt یا ترتیبات تبدیل کرنی ہوں تو ان لائن کنفیگریشن واپس کریں۔ prompt پر مشتمل رسپانس ہمیشہ ان لائن کنفیگریشن استعمال کرتا ہے: اس رسپانس میں موجود کوئی بھی agent_id نظر انداز کر دیا جاتا ہے، بشمول null یا غیر صحیح عددی metadata کے۔ ان لائن prompt کو پھر بھی عام توثیق سے گزرنا ضروری ہے۔ ان لائن webhook رسپانس میں بھی variables شامل ہو سکتے ہیں۔ محفوظ ایجنٹ webhook رسپانس فون اور widget دونوں کالز پر ایجنٹ کا ڈیپلائے شدہ A/B تقسیم استعمال کرتے ہیں؛ variant منتخب ہونے کے بعد variables رینڈر ہوتے ہیں۔ ان باؤنڈ فون کالز پر، ایسا نمبر استعمال کریں جس کے لیے کوئی ان باؤنڈ ایجنٹ مقرر نہ ہو اور اس کا فون نمبر یا تنظیم webhook کنفیگر کریں؛ widget keys mode="webhook" استعمال کرتی ہیں۔ Endpoint-system آنے والی اطلاعات بلاکنگ کنفیگریشن رسپانس فراہم نہیں کرتیں۔

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

POST /v1/realtime/sessions، agent_id (یا ان لائن config) کے ساتھ variables قبول کرتا ہے۔ یہ سیشن بنانے والے API فیلڈز ہیں۔ Realtime WebSocket bridge variables آپشن فارورڈ نہیں کرتا؛ اسے براہ راست سیشن بنانے والے API کو فراہم کریں۔ Widget کلائنٹس کو پوسٹ کیے گئے سیشن payload میں variables شامل کرنا ضروری ہے؛ SDK فارورڈنگ اس API تبدیلی کا حصہ نہیں ہے۔ Builder mic اور simulated test calls ڈیفالٹس اور غائب placeholders کو حل کرتے ہیں، مگر ان میں ہر کال کے variables کی ان پٹ نہیں ہوتی۔

کال کے بعد واپس آنے والی اقدار

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

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

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

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