ThunderPhone v3 اب لائیو ہے۔سیلف سرو، قیمت 2¢ فی منٹ سے شروع۔اعلان پڑھیں

Webhooks

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.idintegerنمبر کے لیے مقرر کردہ ایجنٹ
agent.namestringاس کا نام
agent.versioninteger | nullجواب دینے والے ورژن کا نمبر: نمبر کا پن کیا گیا ورژن، یا بصورت دیگر ایجنٹ کا تازہ ترین شائع شدہ ورژن (null اگر کوئی نہ ہو)
agent.version_pinnedbooleanآیا نمبر اس ورژن کے لیے پن کیا گیا ہے

کال کے لیے درکار معلومات کے ساتھ جواب دیں۔ ان میں سے کوئی بھی نمبر کے ورژن پر مقرر کردہ ایجنٹ کی معلومات بھرتا ہے:

  • {"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_reason inbound_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 ایسی تازہ ترین آؤٹ باؤنڈ کال تلاش کرتا ہے (جس نے ان کے فون پر گھنٹی بجائی تھی) اور اسے تین طریقوں سے استعمال کرتا ہے:

  1. درخواست میں 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وہ ایجنٹ جس نے کال کی؛ ان لائن کنفیگ کے ساتھ کی گئی کال یا جس کا ایجنٹ حذف کر دیا گیا ہو، اس کے لیے null
    started_atstringکال کب شروع ہوئی تھی (ISO 8601، UTC)
    outcomestringno_answer (گھنٹی بجتی رہی، مصروف تھا یا کال مسترد کر دی گئی)، voicemail (وائس میل نے جواب دیا، یا کسی نے ایجنٹ سے بات نہیں کی)، conversation (کسی نے ایجنٹ سے بات کی) یا answered (کال اٹھائی گئی؛ کس نے اٹھائی، یہ ابھی معلوم نہیں)
  2. ایجنٹ کے لیے پس منظر۔ جو بھی ایجنٹ جواب دیتا ہے، اسے اپنے prompt کے آخر میں ایک مختصر نوٹ ملتا ہے: پچھلی کال کب کی گئی تھی، کس ایجنٹ نے کی تھی، اور اس کا نتیجہ کیا تھا۔ ایجنٹ کو ہدایت دی جاتی ہے کہ اسے بلند آواز سے نہ پڑھے، اور چونکہ کالر ID جعلی ہو سکتی ہے، اس کال کے بارے میں اتنی معلومات بھی شیئر نہ کرے کہ نمبر پر پہلے کال کی گئی تھی۔

  3. ایک متبادل ایجنٹ۔ جب نمبر پر کوئی اِن باؤنڈ ایجنٹ نہ ہو اور کوئی کنفیگ موصول نہ ہو کیونکہ 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 کی بندش کال کا جواب دیے جانے کے باوجود نظر آتی رہتی ہے۔


جواب کے سائز کی حد


مثال ہینڈلر

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 {}
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({});
  },
);

فنکشن ٹولز کے ساتھ جواب

ٹولز منسلک کریں تاکہ 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-* ویلیوز) اب بھی قبول کی جاتی ہیں۔

فیلڈویلیوزاس کا تبادلہ
intelligencecore, pro (ڈیفالٹ)Core کم قیمت ہے اور جلد جواب دینا شروع کرتا ہے؛ Pro طویل پرامپٹس کی زیادہ قابلِ اعتماد طریقے سے پیروی کرتا ہے
audio_tierlite, standard (ڈیفالٹ), plus, maxاعلیٰ درجے بہتر سنتے ہیں اور زیادہ قیمت رکھتے ہیں؛ Plus بعض ٹرنز میں 1–2 s کا اضافہ کرتا ہے، ہر Max جواب میں 3–4 s لگتے ہیں (Max عمومی طور پر دستیاب نہیں ہے)
endpointingfaster, fast, normal (ڈیفالٹ), patientکم انتظار جلد جواب دیتے ہیں اور زیادہ قیمت رکھتے ہیں
faster_repliestrue (ڈیفالٹ), falseرفتار میں اضافہ: تھوڑی زیادہ قیمت کے بدلے جواب کچھ جلد آتے ہیں

متعلقہ