Open in
telephony.incoming / web.incoming
بلاکنگ webhook جو آنے والی کال کی کنفیگریشن کو حقیقی وقت میں تشکیل دیتا ہے۔
جب ایک آنے والی فون کال ایسے نمبر پر پہنچتی ہے جس کے لیے کوئی ایجنٹ مقرر نہیں
ہے (آپ کی باہر جانے والی کالوں کا جواب دینے والے کالرز کے لیے کال بیکس دیکھیں)، یا ویب وِجٹ سیشن کسی پبلش ایبل کلید پر
mode="webhook" میں شروع ہوتا ہے، تو ThunderPhone آپ کے
پرانے ویب ہک URL
کو ایک روکنے والی telephony.incoming / web.incoming درخواست بھیجتا ہے
اور کنفیگریشن کے جواب کا انتظار کرتا ہے: فون کال کے لیے 13 سیکنڈ تک،
جس میں ایک دوبارہ کوشش شامل ہے، اور وِجٹ سیشن کے لیے 10 سیکنڈ تک
(ٹائم آؤٹس اور دوبارہ کوششیں دیکھیں)۔ ہر کال کے لیے prompt، آواز اور ٹولز کو متحرک طور پر منتخب کرنے کے لیے اس تبادلے کو استعمال کریں —
مکمل طریقۂ کار کے لیے متحرک کال کنفیگریشن گائیڈ
دیکھیں۔
کسی ایجنٹ کے لیے مختص کردہ نمبر کا جواب وہی ایجنٹ دیتا ہے۔ جب ایجنٹ کا اپنا کال سیٹ اپ webhook ہو، تو ایجنٹ کے متغیرات اور کال کا سیاق پُر کرنے کے لیے یہی بلاک کرنے والا تبادلہ پہلے ایجنٹ کے URL پر ہوتا ہے۔
ٹائم آؤٹس اور دوبارہ کوششیں
فوراً جواب دیں: جب آپ فیصلہ کر رہے ہوتے ہیں تو کالر لائن پر انتظار کر رہا ہوتا ہے۔
فون کال (telephony.incoming) کے لیے:
- پہلی کوشش میں 10 سیکنڈ تک لگ سکتے ہیں۔
- اگر اس کا وقت ختم ہو جائے، کنکشن نہ بن سکے، یا
5xx،408یا429جواب ملے تو ThunderPhone ایک بار مزید کوشش کرتا ہے۔ دوبارہ کوشش کو پورے تبادلے کے لیے 13 سیکنڈ کے بجٹ میں سے جو وقت باقی ہو وہ ملتا ہے: وقت ختم ہونے والی پہلی کوشش کے بعد تقریباً 3 سیکنڈ، اور تیز ناکامی کے بعد تقریباً پورے 13 سیکنڈ۔ اگر 2 سیکنڈ سے کم وقت باقی ہو تو دوبارہ کوشش نہیں کی جاتی۔ - کوئی بھی دیگر
4xxجواب، سائز کی حد سے بڑا جواب، یا ایسا2xxجس کا باڈی درست کنفیگریشن نہ ہو، حتمی ہوتا ہے اور اس پر دوبارہ کوشش نہیں کی جاتی۔ - دونوں کوششیں ایک ہی باڈی، ایک ہی
X-ThunderPhone-Signature، اور ایک ہیX-ThunderPhone-Idempotency-Keyہیڈر (telephony-incoming-<call_id>) بھیجتی ہیں، تاکہ ضمنی اثرات رکھنے والا ہینڈلر دوبارہ کوشش کو شناخت کر سکے۔
اگر قابلِ استعمال کنفیگریشن موصول نہ ہو تو کالر کو خاموش لائن پر رکھنے کے بجائے کال فوراً ختم کر دی جاتی ہے۔ یہ کال ہسٹری میں end_reason
inbound_config_webhook_failed کے ساتھ ایک ناکام، بغیر بل والی کال کے طور پر ظاہر ہوتی ہے، اور معمول کا
telephony.complete ایونٹ بھیجا جاتا ہے۔ ڈیش بورڈ میں کال کا
صفحہ، اور GET /v1/calls/{call_id} میں config_webhook_failure، بتاتے ہیں کہ آپ کے ویب ہک نے
کیا کیا: {kind, attempts, http_status, host, source}، جہاں kind یہ ہوتا ہے: http_error،
timeout، connection، dns، tls، response_too_large،
blocked_url، other، invalid_json، non_object_json یا
invalid_config؛ host آپ کے ویب ہک کا ہوسٹ نام ہوتا ہے، اور source
number (یہ ویب ہک) یا agent_setup (کسی ایجنٹ کا کال سیٹ اپ ویب ہک) ہوتا ہے۔
invalid_config کے لیے، reason بتاتا ہے کہ جواب کیوں استعمال نہیں کیا جا سکا اور
fields متعلقہ فیلڈز کے نام دیتا ہے: no_agent (نہ agent_id اور نہ
prompt؛ fields ان کیز کی فہرست دیتا ہے جنہیں نظر انداز کیا گیا، مثلاً غلط ہجے والا
agentId)، agent_not_found، agent_id_not_integer، unexpected_fields
(agent_id کے ساتھ variables، context، timezone اور language کے علاوہ
کیز)، invalid_variables، invalid_context، invalid_language،
unsupported_language، invalid_config_fields یا agent_settings_invalid۔
بصورتِ دیگر reason null ہوتا ہے اور fields خالی ہوتا ہے۔ واحد
استثنا وہ ہے جب کالر آپ کی کسی آؤٹ باؤنڈ کال کا جواب واپس دے اور
تبادلہ خود ناکام ہو گیا ہو: کال بیکس دیکھیں۔
ویجٹ سیشن (web.incoming) کو 10 سیکنڈ تک کی صرف ایک کوشش ملتی ہے۔ اگر وہ ناکام ہو جائے تو سیشن کی درخواست 502 یا 422 کے ساتھ ناکام ہو جاتی ہے۔
درخواست پے لوڈ
فون کالز کے لیے (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| فیلڈ | قسم | تفصیل |
|---|---|---|
call_id | صحیح عدد | کال ID — اس کال کے تمام ایونٹس میں مستقل |
from_number | اسٹرنگ | E.164 کالر نمبر |
to_number | اسٹرنگ | E.164 منزل نمبر (آپ کے ThunderPhone نمبروں میں سے ایک) |
returning_call | آبجیکٹ | صرف اس صورت میں موجود ہوتا ہے جب اس نمبر نے گزشتہ 30 دنوں میں کالر کو کال کی ہو۔ واپس کالز دیکھیں |
sip_headers | آبجیکٹ | صرف اس صورت میں موجود ہوتا ہے جب کال X-* یا User-to-User SIP ہیڈرز کے ساتھ دستی SIP کنکشن پر موصول ہوئی ہو: چھوٹے حروف میں ہیڈر کا نام → قدر۔ SIP ہیڈرز دیکھیں |
ویب ویجٹ سیشنز (web.incoming) کے لیے data فون نمبروں کے بجائے
ایمبیڈنگ صفحے کی شناخت کرتا ہے:
{
"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 | متن | ویجیٹ نے فی سیشن صفحہ سیاق بھیجا ہو تو موجود ہوتا ہے |
اووررائیڈ فیلڈز (language, voice, website_context، اور کوئی بھی
براؤزر variables) صرف اسی وقت آتے ہیں جب پبلش ایبل کلید انہیں اپنے
براؤزر اووررائیڈز میں اجازت دیتی ہے۔ ایسا سیشن درخواست جس میں کوئی ایسا اووررائیڈ ہو جس کی کلید اجازت نہیں دیتی، اس ویب ہک کے کال ہونے سے پہلے مسترد کر دی جاتی ہے۔
جواب کا اسکیما
اس کال کے لیے ایجنٹ کی کنفیگریشن بیان کرنے والا JSON آبجیکٹ واپس کریں۔
prompt اور voice لازمی ہیں؛ باقی سب اختیاری ہیں۔
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| فیلڈ | قسم | ضروری | تفصیل |
|---|---|---|---|
prompt | اسٹرنگ | ہاں | ایجنٹ کو چلانے والا سسٹم prompt |
voice | اسٹرنگ | ہاں | GET /v1/voices سے وائس id، مثلاً john۔ voice_name کو عرف کے طور پر قبول کیا جاتا ہے۔ نامعلوم وائسز توثیق میں ناکام ہوتی ہیں اور کال مسترد کر دی جاتی ہے |
product | اسٹرنگ | نہیں | bolt بھیجیں۔ طے شدہ spark ہے، جو ایک پرانی قدر ہے اور اب بھی 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 | نہیں | صرف تازہ ترین باری کے بجائے کالر آڈیو کی آخری چند باریاں شامل کریں، جس سے معمولی تاخیر اور لاگت کے اضافے کے ساتھ تصحیحات اور ہجوں یا نمبروں پر مبنی ڈیٹا جمع کرنا بہتر ہوتا ہے۔ آنے والے سیشنز کے لیے طے شدہ طور پر فعال اور جانے والی فون کالز کے لیے غیر فعال ہے؛ null طے شدہ ترتیب برقرار رکھتا ہے |
storm_feedback_mode | اسٹرنگ | نہیں | none، acknowledgement (طے شدہ)، یا tick: جب audio_tier، plus یا max ہو تو سست جواب تیار ہونے کے دوران کالر کیا سنتا ہے |
language | اسٹرنگ | نہیں | primary_language کا مختصر نام۔ agent_id کے ساتھ بھی اجازت ہے، جہاں یہ وہ زبان ہے جس میں یہ کال شروع ہوتی ہے اور ایجنٹ کی متعلقہ آواز میں بولی جاتی ہے؛ ہر کال کے لیے زبان مقرر کریں دیکھیں |
primary_language | اسٹرنگ | نہیں | زبان کا کوڈ، معمول کے مطابق بنایا گیا (طے شدہ en)۔ جن کوڈز کو حل نہ کیا جا سکے وہ کال مسترد کر دیتے ہیں |
has_additional_languages | بولین | نہیں | طے شدہ false ہے |
additional_languages | اسٹرنگز کی فہرست | نہیں | اضافی زبانیں جن میں ایجنٹ تبدیل ہو سکتا ہے |
native_voice_switching | بولین | نہیں | طے شدہ false ہے۔ جب کال کسی دوسری زبان میں تبدیل ہو، تو ترتیب شدہ آواز برقرار رکھنے کے بجائے اس زبان کی مقامی آواز سے تبدیل کریں، جو جنس کے لحاظ سے مماثل ہو |
language_switching | اسٹرنگ | null | نہیں | ask_first (طے شدہ) یا follow_caller؛ null، ask_first کے برابر ہے۔ کثیر لسانی ایجنٹ کے اپنی کسی دوسری زبان بولنے والے دوسرے شخص کو سنبھالنے کا طریقہ۔ ask_first اس وقت فوراً تبدیل ہو جاتا ہے جب وہ زبان مانگیں یا اس میں پورا جملہ کہیں، اور مختصر بات، جیسے «ہاں»، کے بعد پوچھتا ہے کہ آیا اسی زبان میں جاری رکھنا ہے۔ follow_caller ان کی بولی ہوئی کسی بھی ترتیب شدہ زبان میں تبدیل ہو جاتا ہے، چاہے صرف ایک لفظ ہو۔ صرف اس وقت لاگو ہوتا ہے جب additional_languages مقرر ہو |
audio_tier | اسٹرنگ | null | نہیں | صرف product: "bolt"۔ سماعت: ایجنٹ کالر کو کتنی احتیاط سے سنتا ہے۔ standard (طے شدہ؛ "" اور null ایک ہی معنی رکھتے ہیں) زیادہ تر کالز کے لیے موزوں ہے (PHI پراسیس کرنے والی کالز صرف BAA کے تحت آنے والے فراہم کنندگان استعمال کرتی ہیں)۔ lite سب سے سستا ہے اور زیادہ بار غلط سنتا ہے۔ plus مشکل باریوں میں زیادہ غور سے سنتا ہے، جن میں تقریباً 1 سے 2 سیکنڈ زیادہ لگتے ہیں۔ max مشکل ترین آڈیو اور نایاب زبانوں کے لیے ہے؛ ہر جواب میں 3 سے 4 سیکنڈ لگتے ہیں، اور کال pro ذہانت چلاتی ہے (intelligence نظرانداز ہوتا ہے)۔ max عام طور پر دستیاب نہیں ہے: جس تنظیم کے لیے اسے فعال نہیں کیا گیا، اس کے لیے کال plus اور آپ کی بتائی ہوئی intelligence چلاتی ہے (اس کے ساتھ جانے والی کال کی درخواست 400 کے ساتھ مسترد ہو جاتی ہے)۔ پرانی قدریں lean (Lite)، hearing (Plus) اور deep_hearing (Max) اب بھی قبول کی جاتی ہیں۔ دیگر پروڈکٹس اسے نظرانداز کرتے ہیں |
endpointing | اسٹرنگ | null | نہیں | faster (200 ms)، fast (300 ms)، normal (500 ms، طے شدہ) یا patient (800 ms)؛ null، normal کے برابر ہے۔ کالر کے رکنے کے بعد ماڈل سے جواب مانگنے سے پہلے Bolt v2 ایجنٹ کتنا انتظار کرتا ہے۔ کم انتظار جلد جواب دے سکتا ہے، مگر ایسی مزید درخواستیں بھیجتا ہے جنہیں کالر کے اگلے الفاظ پرانا بنا دیتے ہیں، جس سے ماڈل کی لاگت بڑھتی ہے۔ دیگر پروڈکٹس اسے نظرانداز کرتے ہیں |
eagerness | اسٹرنگ | null | نہیں | متروک: 19 اکتوبر 2026 تک endpointing کا نام، جسے اب بھی پڑھا جاتا ہے۔ endpointing مقرر ہونے پر نظرانداز ہوتا ہے |
intelligence | اسٹرنگ | null | نہیں | core یا pro (طے شدہ)؛ null، pro کے برابر ہے۔ Bolt v2 پائپ لائن پر موجود bolt ایجنٹ اپنی ہدایات پر کتنی قابلِ اعتماد طریقے سے عمل کرتا ہے۔ core میں پہلے لفظ تک تقریباً 700 ms لگتے ہیں، یہ سب سے سستا اور کچھ کم قابلِ اعتماد ہے (PHI کے طور پر سمجھی جانے والی کالز میں تقریباً 900 ms اور کم قابلِ اعتماد)؛ pro میں تقریباً 900 ms لگتے ہیں؛ Core کے وہ جوابات جو صرف کوئی ٹول کال کرتے، Pro کو دے دیے جاتے ہیں۔ پرانی قدریں lite (Core) اور standard (Pro) اب بھی قبول کی جاتی ہیں، اور متروک plus اور max، pro پر چلتے ہیں۔ جب audio_tier، max ہو تو نظرانداز ہوتا ہے۔ دیگر پروڈکٹس اسے نظرانداز کرتے ہیں |
faster_replies | بولین | null | نہیں | رفتار میں اضافہ۔ طے شدہ true ہے۔ Bolt v2 پائپ لائن پر موجود bolt ایجنٹ کے لیے، جواب معمولی اضافی لاگت کے ساتھ کچھ جلد شروع ہوتے ہیں۔ false اسے غیر فعال کر دیتا ہے۔ دیگر پروڈکٹس اسے نظرانداز کرتے ہیں |
background_track | اسٹرنگ | null | نہیں | محیطی آڈیو id یا null |
acknowledgement_prompt_mode | اسٹرنگ | نہیں | auto (طے شدہ) یا manual (پرانی -with-ack پروڈکٹ قدریں) |
acknowledgement_prompt | اسٹرنگ | نہیں | جب acknowledgement_prompt_mode="manual" ہو تو استعمال ہوتا ہے |
silence_interval_seconds | انٹیجر | null | نہیں | 5 سے 120۔ جانچ سے پہلے کالر کی خاموشی کے سیکنڈز |
silence_max_checkins | انٹیجر | null | نہیں | 1 سے 10 |
silence_checkins_enabled | بولین | نہیں | طے شدہ true ہے |
silence_final_action | اسٹرنگ | نہیں | آخری جانچ کے بعد: hang_up (طے شدہ) یا silence_transfer_destination کو transfer |
silence_transfer_destination | اسٹرنگ | نہیں | اس کنفیگ کی transfer_destinations میں موجود اندراج کا نام؛ transfer کے ساتھ ضروری ہے۔ transfer_destinations کے بغیر منتقلی نہیں کی جا سکتی اور ایجنٹ کال ختم کر دیتا ہے |
silence_final_message | اسٹرنگ | نہیں | 300 یا اس سے کم حروف، جیسا لکھا ہو ویسا پڑھا جاتا ہے؛ "" (طے شدہ) طے شدہ سطر استعمال کرتا ہے |
connect_tone_enabled | بولین | نہیں | طے شدہ false ہے |
pronunciation_dicts | بولین | null | نہیں | طے شدہ false ہے؛ null، false کے برابر ہے۔ جب true ہو، تو کال کی Cartesia گفتگو کال کی زبان کے لیے ThunderPhone کی تلفظ لغت استعمال کرتی ہے، جہاں دستیاب ہو۔ فون اور ویجٹ کالز کے لیے کام کرتا ہے۔ صرف ThunderPhone کی اپنی Cartesia آوازوں پر لاگو ہوتا ہے، آپ کی اپنی Cartesia API کلید والی آوازوں پر نہیں۔ agent_id کے ساتھ استعمال نہیں ہوتا، جہاں محفوظ شدہ ایجنٹ کی ترتیبات لاگو ہوتی ہیں |
words | فہرست | null | نہیں | ایجنٹ مخصوص الفاظ کیسے ادا کرتا ہے، support کے بغیر ایجنٹ کے words جیسے ہی اندراجات۔ language کے بغیر اندراج اس کنفیگ کی زبان اختیار کرتا ہے۔ null اور [] کا مطلب کوئی نہیں ہے۔ agent_id کے ساتھ استعمال نہیں ہوتا، جہاں محفوظ شدہ ایجنٹ کے الفاظ لاگو ہوتے ہیں |
voicemail_action | اسٹرنگ | نہیں | prompt (طے شدہ)، hangup، یا message |
voicemail_message | اسٹرنگ | نہیں | جب voicemail_action="message" ہو تو استعمال ہوتا ہے |
agent_name | اسٹرنگ | نہیں | ڈیش بورڈز اور ویجٹ میں دکھایا جانے والا نام |
org_name | اسٹرنگ | نہیں | ایجنٹ کی شخصیت کے لیے تنظیم کا دکھایا جانے والا نام |
tools | فہرست | نہیں | اِن لائن فنکشن-ٹول اسکیماز (فنکشن ٹولز دیکھیں) |
transfer_destinations | آبجیکٹس کی فہرست | null | نہیں | زیادہ سے زیادہ 50 {name, number} اندراجات جن کو یہ کال منتقل کی جا سکتی ہے، اور جن کی توثیق ایجنٹ کے منتقلی نمبرز کی طرح کی جاتی ہے۔ ایجنٹ نام کے ذریعے اور صرف انہی کو منتقل کرتا ہے؛ [] کا مطلب کوئی منتقلی نہیں۔ ایجنٹ کو اپنی منتخب کردہ نمبر پر منتقل کرنے دینے کے لیے اسے چھوڑ دیں یا null بھیجیں |
timezone | اسٹرنگ | نہیں | اس کال کے لیے IANA ٹائم زون، جیسے America/Chicago۔ ایجنٹ اپنی ٹائم زون سے پہلے، اسی میں تاریخ اور وقت بتاتا ہے۔ agent_id کے ساتھ بھی اجازت ہے۔ جو قدریں IANA زونز نہیں ہیں انہیں نظرانداز کیا جاتا ہے۔ ہر کال کے لیے ٹائم زون مقرر کریں دیکھیں |
context | اسٹرنگ | null | نہیں | اس کال کے لیے آزاد شکل کا متن، جیسے آپ کے سسٹم کی جمع کردہ نوٹس، زیادہ سے زیادہ 20,000 حروف تک۔ اسے prompt کے بعد ایک حدبند بلاک میں شامل کیا جاتا ہے اور ٹیمپلیٹ کے طور پر رینڈر نہیں کیا جاتا۔ agent_id کے ساتھ بھی اجازت ہے۔ ایسی قدر جو اسٹرنگ نہ ہو، یا اس سے لمبی ہو، کال مسترد کر دیتی ہے۔ کال متغیرات اور سیاق دیکھیں |
call_id | انٹیجر | نہیں | درخواست کے کال id کی اختیاری بازگشت؛ نظرانداز کی جاتی ہے |
چونکہ prompt اور voice ضروری ہیں، اس لیے {} یا ایسی کوئی بھی response واپس کرنے سے جو validation میں ناکام ہو، کال مسترد ہو جاتی ہے: فون کال ٹائم آؤٹس اور دوبارہ کوششوں میں بیان کردہ طریقے کے مطابق ختم ہو جاتی ہے، اور widget session کی درخواست 422 کے ساتھ ناکام ہو جاتی ہے۔ یہ واپس کال کرنے والوں پر بھی لاگو ہوتا ہے: آپ کا webhook جو بھی JSON object واپس کرے، وہی اس کا جواب ہوتا ہے، اور {} کال مسترد کرنے کا طریقہ ہے۔
ایجنٹ کال سیٹ اپ ویب ہک
ایک ایجنٹ کا اپنا کال سیٹ اپ ویب ہک ہو سکتا ہے: اس کی سیٹنگز میں کال سیٹ اپ ویب ہک
فیلڈ، یا API میں call_setup_webhook_url۔
ایجنٹ کو کسی نمبر کے لیے مقرر کریں، اور اس نمبر پر ایجنٹ کے جواب دینے والی ہر آنے والی کال سے پہلے،
ThunderPhone اس کال کے ویری ایبلز اور کانٹیکسٹ کے لیے ویب ہک سے پوچھتا ہے۔ نمبر اپنا ایجنٹ برقرار رکھتا ہے،
اس لیے فون نمبرز کا صفحہ اور ایجنٹ کا صفحہ دکھاتے ہیں کہ اس کا جواب کون سا ایجنٹ دیتا ہے۔
یہ ایجنٹ کی دیگر سیٹنگز کی طرح ایک سیٹنگ ہے: مسودے کے طور پر رکھی جاتی ہے، تعیناتی پر شائع ہوتی ہے،
اور ورژن ہسٹری میں محفوظ رہتی ہے۔ ایک نمبر
پرانے ورژن کے لیے پن کیا گیا
ہو تو اس ورژن کے URL سے پوچھتا ہے۔ درخواستوں پر ایجنٹ کے اپنے
call_setup_webhook_signing_secret سے دستخط ہوتے ہیں (تنظیم کے ویب ہک سیکرٹ سے نہیں)، اور ان میں وہی
X-ThunderPhone-Signature ہیڈر، ٹائم آؤٹس، دوبارہ کوشش اور idempotency کلید ہوتی ہے جو اوپر
بیان ہوئی ہے۔ سیکرٹ صرف لکھنے کے لیے ہے: ایسا سیکرٹ مقرر کریں جسے آپ کا endpoint جانچتا ہو
(ایجنٹ کی سیٹنگز میں، یا PATCH /v1/agents/{id} کے ذریعے)؛ کوئی read اسے کبھی واپس نہیں کرتا، اور
call_setup_webhook_signing_secret_set بتاتا ہے کہ آیا کوئی سیکرٹ مقرر ہے۔
درخواست اوپر والے telephony.incoming payload کے ساتھ اس ایجنٹ کو بھی شامل کرتی ہے
جس کے لیے معلومات بھری جا رہی ہیں:
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567",
"variables": null,
"agent": {
"id": 12,
"name": "Front desk",
"version": 7,
"version_pinned": false
}
}
}| فیلڈ | قسم | وضاحت |
|---|---|---|
agent.id | integer | نمبر کے لیے مقرر کردہ ایجنٹ |
agent.name | string | اس کا نام |
agent.version | integer | null | جواب دینے والے ورژن کا نمبر: نمبر کا پن کیا گیا ورژن، یا بصورت دیگر ایجنٹ کا تازہ ترین شائع شدہ ورژن (null اگر کوئی نہ ہو) |
agent.version_pinned | boolean | آیا نمبر اس ورژن کے لیے پن کیا گیا ہے |
کال کے لیے درکار معلومات کے ساتھ جواب دیں۔ ان میں سے کوئی بھی نمبر کے ورژن پر مقرر کردہ ایجنٹ کی معلومات بھرتا ہے:
{"variables": {...}}،{"context": "..."}، یا دونوں- یہی، مگر
"agent_id"کو مقرر کردہ ایجنٹ کی id پر سیٹ کر کے {}: ایجنٹ کسی معلومات کے بغیر جواب دیتا ہے
timezone اور language بھی agent_id کے ساتھ
استعمال کیے جا سکتے ہیں۔ ویری ایبلز ایجنٹ کے {{placeholders}} بھرتے ہیں؛ کانٹیکسٹ prompt کے بعد شامل ہوتا ہے۔
یا کال کا فیصلہ خود کریں۔ کسی دوسرے ایجنٹ کا agent_id، یا prompt کے ساتھ مکمل
کنفیگریشن، مقرر کردہ ایجنٹ (اور اس کے پن کیے گئے ورژن) کے بجائے صرف اس کال کا جواب دیتی ہے۔
کال کی تفصیلات میں ہر صورت کو call_setup_webhook میں assigned_agent،
other_agent یا inline_config کا لیبل دیا جاتا ہے۔ ایسا جواب جو استعمال نہیں ہو سکتا
(نامعلوم agent_id، variables کے ساتھ دیگر کلیدیں، یا ایسی کنفیگریشن جو توثیق میں ناکام ہو)
کال کو نمبر کے ویب ہک کی طرح ختم کر دیتا ہے۔
جب ویب ہک کا جواب دینا لازمی ہو۔ ایجنٹ کو اپنا ویب ہک ضرور درکار ہوتا ہے جب اس کی
سیٹنگز میں کوئی ایسا {{variable}} استعمال ہو جس کا کوئی طے شدہ قدر نہ ہو: اس کا prompt یا دوبارہ استعمال
ہونے والی ہدایات، مرحلے کی ہدایات یا سطور، تصدیقی prompt، وائس میل پیغام، رضامندی کا اعلان، یا
{{variable}} منتقلی نمبر۔ ایجنٹ کا call_setup_webhook_variables انہیں فہرست کرتا ہے۔
- اسے ویب ہک درکار ہے: جب ویب ہک کا ٹائم آؤٹ ہو جائے، اس تک رسائی نہ ہو سکے، یا وہ خرابی یا ایسی باڈی کے ساتھ جواب دے جو JSON آبجیکٹ نہ ہو،
کال شروع نہیں ہوتی، چاہے کال میں ان ویری ایبلز میں سے کسی ایک کی قدر پہلے سے موجود ہو۔
اسے ختم کر دیا جاتا ہے اور ٹائم آؤٹس اور دوبارہ کوششوں میں بیان کردہ طریقے کے عین مطابق ریکارڈ کیا جاتا ہے
(
end_reasoninbound_config_webhook_failed، بل کے بغیر)۔ - اسے کسی چیز کی ضرورت نہیں (کوئی ویری ایبل نہیں، یا ہر ایک کی کوئی طے شدہ قدر ہے جیسے
{{first_name|there}}): ویب ہک پھر بھی چلتا ہے، لیکن ناکام ہونے پر ایجنٹ اس کے بغیر جواب دیتا ہے، اور کال کی تفصیلات میںwebhook_failedکے ساتھ خرابی کی وجہ دکھائی جاتی ہے۔
صرف کال کا سیاق webhook کو لازمی نہیں بناتا: ایجنٹ کی ترتیبات میں کوئی چیز یہ نہیں کہتی کہ اسے سیاق درکار ہے۔ اگر آپ کے webhook کے جواب کے بغیر کال شروع نہیں ہونی چاہیے تو ڈیفالٹ کے بغیر ایک متغیر استعمال کریں۔
تفویض اور ڈیپلائے کرنا۔ جس ایجنٹ کو اپنے webhook کی ضرورت ہو، اسے webhook کے بغیر کسی نمبر کو تفویض نہیں کیا جا سکتا: متغیرات کے نام والے پیغام کے ساتھ تفویض مسترد کر دی جاتی ہے۔ یہی جانچ نمبر کے ورژن تبدیل ہونے پر بھی چلتی ہے، بشمول کسی پن کیے گئے نمبر کے واپس Latest پر منتقل ہونے کے۔ جب ایجنٹ اپنی شائع شدہ ترتیبات کے ساتھ کسی نمبر کا جواب دے رہا ہو، تو ایسا ڈیپلائے جو webhook کے بغیر ایسا متغیر شامل کرے (یا webhook ہٹا دے) اسی طرح مسترد کر دیا جاتا ہے۔ ڈرافٹ محفوظ کرنے کی ہمیشہ اجازت ہوتی ہے، اور مسئلہ حل ہونے تک ایجنٹ کے warnings میں call_setup_webhook_needed موجود رہتا ہے۔
ایجنٹ کا webhook صرف ان نمبروں پر آنے والی فون کالز کے لیے چلتا ہے جن پر اسے تفویض کیا گیا ہو۔ باہر جانے والی کالز، ویب ویجیٹ سیشنز، SIP پتے، سمولیشنز اور ڈیش بورڈ کی ٹیسٹ گفتگوئیں اسے کال نہیں کرتیں؛ وہ پہلے کی طرح اپنی درخواست سے متغیرات لیتی ہیں۔
محفوظ شدہ نمونوں کے ساتھ جانچ۔ یہ جانچنے کے لیے کہ آپ کا ایجنٹ کسی
مخصوص جواب کے ساتھ کیا کرتا ہے (دوبارہ کال کرنے والا، کوئی ریکارڈ نہ ملنا، ہسپانوی بولنے والا)،
اس جواب کو ایجنٹ پر بطور نمونہ محفوظ کریں: اس کے variables، context
اور اختیاری طور پر language، جو آپ ٹائپ کریں یا کسی گزشتہ کال سے کاپی کریں۔ اسے
اس وقت منتخب کریں جب آپ ڈیش بورڈ میں ٹیسٹ گفتگو، اپنے فون پر ٹیسٹ کال،
یا ایجنٹ کے خلاف سمولیشن شروع کریں، اور کال ایسے چلے گی جیسے آپ کے webhook
نے اسی کے ساتھ جواب دیا ہو۔ نمونے ایجنٹ کے ہر ورژن کے ساتھ مشترک ہوتے ہیں۔
کسی نمونے میں ترمیم کرنے سے اس کے سابقہ ورژن برقرار رہتے ہیں: جب ایجنٹ کی کسی تبدیلی کے لیے
ایسا variable درکار ہو جو نمونہ سیٹ نہیں کرتا، تو اسے نمونے میں شامل کریں، اور ایجنٹ کے
پرانے ورژن نمونے کو اسی حالت میں استعمال کرتے رہیں گے جس میں وہ تھا۔ فون نمبر پر
کال کرنے والی سمولیشنز اس کے بجائے آپ کا حقیقی webhook چلاتی ہیں۔
بغیر تفویض شدہ ایجنٹ والے نمبر اوپر بیان کے عین مطابق نمبر یا تنظیم کے webhook کو استعمال کرتے رہتے ہیں۔
واپسی کالز
لوگ اکثر اس نمبر پر واپس کال کرتے ہیں جس سے انہیں کال موصول ہوئی تھی، مثلاً آپ کے وائس ایجنٹ کے وائس میل چھوڑنے کے بعد۔ جب کسی ایسے شخص کی فون کال آتی ہے جسے اسی نمبر نے گزشتہ 30 دنوں میں کال کی ہو، ThunderPhone ایسی تازہ ترین آؤٹ باؤنڈ کال تلاش کرتا ہے (جس نے ان کے فون پر گھنٹی بجائی تھی) اور اسے تین طریقوں سے استعمال کرتا ہے:
-
درخواست میں
returning_call۔ اوپر دی گئی بلاکنگ درخواست اور اینڈ پوائنٹ اطلاع، دونوں اسے شامل کرتے ہیں، تاکہ آپ کا ہینڈلر کال کرنے والے کو روٹ کر سکے:{ "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567", "returning_call": { "call_id": 987650001, "agent_id": 13, "started_at": "2026-10-21T19:05:12.402Z", "outcome": "voicemail" } } }فیلڈ قسم تفصیل call_idinteger پہلے کی آؤٹ باؤنڈ کال agent_idinteger | null وہ ایجنٹ جس نے کال کی؛ ان لائن کنفیگ کے ساتھ کی گئی کال یا جس کا ایجنٹ حذف کر دیا گیا ہو، اس کے لیے nullstarted_atstring کال کب شروع ہوئی تھی (ISO 8601، UTC) outcomestring no_answer(گھنٹی بجتی رہی، مصروف تھا یا کال مسترد کر دی گئی)،voicemail(وائس میل نے جواب دیا، یا کسی نے ایجنٹ سے بات نہیں کی)،conversation(کسی نے ایجنٹ سے بات کی) یاanswered(کال اٹھائی گئی؛ کس نے اٹھائی، یہ ابھی معلوم نہیں) -
ایجنٹ کے لیے پس منظر۔ جو بھی ایجنٹ جواب دیتا ہے، اسے اپنے prompt کے آخر میں ایک مختصر نوٹ ملتا ہے: پچھلی کال کب کی گئی تھی، کس ایجنٹ نے کی تھی، اور اس کا نتیجہ کیا تھا۔ ایجنٹ کو ہدایت دی جاتی ہے کہ اسے بلند آواز سے نہ پڑھے، اور چونکہ کالر ID جعلی ہو سکتی ہے، اس کال کے بارے میں اتنی معلومات بھی شیئر نہ کرے کہ نمبر پر پہلے کال کی گئی تھی۔
-
ایک متبادل ایجنٹ۔ جب نمبر پر کوئی اِن باؤنڈ ایجنٹ نہ ہو اور کوئی کنفیگ موصول نہ ہو کیونکہ webhook URL موجود نہیں یا آپ کے webhook نے کوئی جواب نہیں دیا (اس کا وقت ختم ہو گیا، اس تک رسائی ممکن نہ تھی، یا اس نے دونوں کوششوں پر
5xx،408یا429کا جواب دیا)، تو کال ختم ہونے کے بجائے اس ایجنٹ کو جاتی ہے جس نے پچھلی کال کی تھی، بشرطیکہ وہ ایجنٹ اب بھی آپ کی تنظیم میں موجود ہو۔ یہ اس ایجنٹ کی تعینات کردہ سیٹنگز کے ساتھ چلتی ہے۔ آپ کے webhook کا کوئی بھی جواب پھر بھی فیصلہ کرتا ہے: دوسرا4xx، ایسا باڈی جو JSON آبجیکٹ نہ ہو،{}، یا تصدیق میں ناکام ہونے والا کنفیگ، پہلے کی طرح کال ختم کر دیتا ہے۔ نمبر پر موجود اِن باؤنڈ ایجنٹ ہمیشہ جواب دیتا ہے۔
پچھلی کال کی تفصیلات شیئر کرنا۔ کالر ID جعلی ہو سکتی ہے، اس لیے بطور ڈیفالٹ
پچھلی کال کے مواد میں سے کچھ بھی نئی کال تک نہیں پہنچتا۔ تنظیم کا ایڈمن
Organization → General → Callbacks کے تحت پچھلی کال کی تفصیلات شیئر کریں
کو فعال کر سکتا ہے (یا
callback_context_details_enabled
سیٹ کر سکتا ہے)۔ اسے فعال کرنے پر، ایجنٹ کے نوٹ میں پچھلی کال کا خلاصہ بھی شامل
ہوتا ہے، اور اس ایجنٹ کو روٹ کی گئی کال جس نے پچھلی کال کی تھی، اس کال کے
variables (مثلاً رابطے کے نام) کے ساتھ چلتی ہے۔ اسے صرف اس صورت میں فعال کریں
جب یہ تفصیلات اس نمبر سے کال کرنے والے ہر شخص کے ساتھ شیئر کرنا محفوظ ہو۔ اسے فعال
کرنے کے باوجود، ایسی کال جس میں محفوظ شدہ صحت کی معلومات شامل ہو سکتی ہیں، اپنا
خلاصہ یا variables ایسی کال کو کبھی منتقل نہیں کرتی جسے PHI پراسیس کرنے کے لیے
متعین نہ کیا گیا ہو۔
کال کی تفصیلات میں۔ پہلے کی کال سے مماثل آنے والی کال میں GET /v1/calls/{call_id} میں ایک callback آبجیکٹ ہوتا ہے:
اوپر دیا گیا returning_call، routed_as_callback (آیا فال بیک نے اس کا جواب دیا)، اور config_webhook_failure (جب آپ کے webhook نے کوئی جواب نہیں دیا اور فال بیک نے کال سنبھال لی تو {kind, attempts, http_status, host}، ورنہ null)؛ اس طرح webhook کی بندش کال کا جواب دیے جانے کے باوجود نظر آتی رہتی ہے۔
جواب کے سائز کی حد
مثال ہینڈلر
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 {}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({});
},
);فنکشن ٹولز کے ساتھ جواب
ٹولز منسلک کریں تاکہ AI گفتگو کے دوران آپ کی APIs کو کال کر سکے:
{
"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"
}
}
}
]
}سیٹنگز کا فوری خلاصہ
product: "bolt" بھیجیں اور ان فیلڈز کے ذریعے کال کو ترتیب دیں۔ پرانی
product ویلیوز (spark اور storm-* ویلیوز) اب بھی قبول کی جاتی ہیں۔
| فیلڈ | ویلیوز | اس کا تبادلہ |
|---|---|---|
intelligence | core, pro (ڈیفالٹ) | Core کم قیمت ہے اور جلد جواب دینا شروع کرتا ہے؛ Pro طویل پرامپٹس کی زیادہ قابلِ اعتماد طریقے سے پیروی کرتا ہے |
audio_tier | lite, standard (ڈیفالٹ), plus, max | اعلیٰ درجے بہتر سنتے ہیں اور زیادہ قیمت رکھتے ہیں؛ Plus بعض ٹرنز میں 1–2 s کا اضافہ کرتا ہے، ہر Max جواب میں 3–4 s لگتے ہیں (Max عمومی طور پر دستیاب نہیں ہے) |
endpointing | faster, fast, normal (ڈیفالٹ), patient | کم انتظار جلد جواب دیتے ہیں اور زیادہ قیمت رکھتے ہیں |
faster_replies | true (ڈیفالٹ), false | رفتار میں اضافہ: تھوڑی زیادہ قیمت کے بدلے جواب کچھ جلد آتے ہیں |