Open in
آؤٹ باؤنڈ کالز کریں (API)
اپنے کوڈ سے AI سے چلنے والی آؤٹ باؤنڈ کال شروع کریں — سروے، فالو اَپ، یا تصدیقی فلو۔
آؤٹ باؤنڈ کالنگ آپ کو ThunderPhone کو منزل کا نمبر اور ایجنٹ کنفیگریشن دینے اور AI سے آپ کی جانب سے کال کروانے دیتی ہے۔ عام استعمال کے کیسز:
- اپائنٹمنٹ کی تصدیقات
- سروے کے لیے دوبارہ کالز
- مسڈ کال کے بعد "دوسری کوشش" کے فالو اَپس
- ڈسپیچ طرز کی اطلاعات
پیشگی تقاضے
- آؤٹ باؤنڈ کے لیے فعال نمبر منتخب کریں
اپنے کسی نمبر کو VoIP کنکشن کے ذریعے استعمال کریں، یا فون نمبرز صفحے سے اپنے ThunderPhone نمبرز کو آؤٹ باؤنڈ کالز کے لیے استعمال کرنے کی اجازت طلب کریں۔ ThunderPhone نمبرز ابتدا میں صرف اِن باؤنڈ ہوتے ہیں۔ ThunderPhone ہر درخواست کا دستی طور پر جائزہ لیتا ہے؛ منظوری کے بعد، وہ نمبرز منظور شدہ یومیہ حد تک کالز کر سکتے ہیں (جو 00:00 UTC پر ری سیٹ ہوتی ہے) اور مہمات چلا سکتے ہیں، اور آپ زیادہ حد کی درخواست کر سکتے ہیں۔ صارف کے VoIP نمبرز پر کوئی یومیہ حد نہیں ہوتی، اس لیے ہم انہیں آؤٹ باؤنڈ کالنگ کے لیے تجویز کرتے ہیں۔ ملاحظہ کریں اپنے نمبرز استعمال کریں۔
- ایک ایجنٹ بنائیں
آؤٹ باؤنڈ نوعیت کا prompt عموماً ایجنٹ کے اپنے تعارف اور مقصد بتانے سے شروع ہوتا ہے — "ہیلو، Acme کی طرف سے کال کر رہا ہوں تاکہ کل 3 بجے کے لیے آپ کی اپائنٹمنٹ کی تصدیق کر سکوں…"
outbound_speak_orderکوagent_firstپر مقرر کریں (یہ ڈیفالٹ ہے)۔ - مثبت بیلنس برقرار رکھیں
اگر بیلنس
$0.00سے کم یا برابر ہو تو آؤٹ باؤنڈ کالز402 Payment Requiredواپس کرتی ہیں۔ ڈیش بورڈ میں تنظیم → بلنگ کی ترتیبات کے تحت ٹاپ اپ کریں یا خودکار ری لوڈ فعال کریں۔ آپ کیsk_live_کلیدGET /v1/billingکے ذریعے بیلنس چیک کر سکتی ہے، لیکن ٹاپ اپ یا خودکار ری لوڈ تبدیل نہیں کر سکتی۔
محفوظ شدہ ایجنٹ کے ساتھ کال کریں
سب سے آسان طریقہ — ایجنٹ کو id کے ذریعے حوالہ دیں:
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12
}'جواب:
{ "call_id": 987654321, "status": "initiated" }اِن لائن کنفیگ کے ساتھ کال کریں
اگر آپ کو ایک بار استعمال ہونے والا ایسا prompt چاہیے جسے ایجنٹ کے طور پر محفوظ کرنا مناسب نہ ہو،
تو اس کے بجائے config پاس کریں۔ اس کی ساخت
call.incoming ویب ہک کے
جوابی اسکیما سے مطابقت رکھتی ہے:
curl -X POST https://api.thunderphone.com/v1/call \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"from_number": "+15551234567",
"to_number": "+14155552671",
"config": {
"prompt": "You are confirming Jane Doe appointment for 3pm tomorrow…",
"voice": "john",
"product": "spark"
}
}'آخری خاموشی چیک اِن کے بعد ہونے والے عمل کو کنٹرول کریں
آپ وہی خاموشی کے آخری عمل کی ترتیبات ان لائن config میں بھی دے سکتے ہیں جو محفوظ کردہ ایجنٹس استعمال کرتے ہیں:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"silence_final_action": "hang_up"
}
}آخری خاموشی چیک اِن کے بعد کیا ہو، اسے منتخب کرنے کے لیے silence_final_action استعمال کریں۔ آپ silence_final_message بھی دے سکتے ہیں، اور جب آخری عمل منتقلی ہو تو silence_transfer_destination بھی۔
ان لائن config میں الفاظ کی فہرست شامل کریں
ان لائن آؤٹ باؤنڈ کالز میں محفوظ کردہ ایجنٹس جیسی ہی words فہرست شامل ہو سکتی ہے۔
اسے اس وقت استعمال کریں جب آپ ایجنٹ کو پہلے محفوظ کیے بغیر کال کو حسب ضرورت تلفظ یا سننے کے قواعد کے مطابق چلانا چاہتے ہوں۔
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"config": {
"prompt": "[REDACTED_LITERAL]",
"voice": "john",
"product": "spark",
"words": []
}
}کال کی پیروی کریں
queued_at وقت کے ساتھ جواب کا مطلب ہے کہ ThunderPhone کی آؤٹ باؤنڈ گنجائش
استعمال میں ہے: گنجائش دستیاب ہونے پر کال 10 منٹ کے اندر ڈائل ہوگی، اور اگر گنجائش دستیاب نہ ہو تو
end_reason outbound_queue_timeout کے ساتھ ختم ہوگی۔ آپ کو دوبارہ کوشش کرنے کی ضرورت نہیں۔ قطار میں موجود کالز دیکھیں۔
اسی دوران،
telephony.complete webhook کو سبسکرائب کریں —
یہ معلوم کرنے کا تیز ترین طریقہ ہے کہ کال ختم ہو گئی ہے۔ آپ لائیو
پیش رفت کی اپ ڈیٹس، جیسے ڈائلنگ، جواب دی گئی کال، وائس میل، اور ہولڈ میں تبدیلیوں کے لیے
call.status_changed کو بھی سبسکرائب کر سکتے ہیں۔
اگر آپ اِن باؤنڈ webhooks قبول نہیں کر سکتے، تو ہر چند سیکنڈ بعد GET /v1/calls/{call_id} کو
پول کریں؛ کال ختم ہونے پر ریکارڈ میں end_reason، duration_seconds،
اور ریکارڈنگ کا URL شامل ہوتا ہے۔
اگر آپ کا ایجنٹ کال کے بعد ساختی ڈیٹا اخذ کرنے کے لیے ترتیب دیا گیا ہے، تو حتمی عمل مکمل ہونے کے بعد وہ ڈیٹا الگ سے فراہم کیا جاتا ہے۔
محفوظ شدہ ایجنٹ کو فی کال متغیرات دیں
محفوظ شدہ ایجنٹ prompt متن میں {{name}} یا {{name|there}} جیسے پلیس ہولڈرز استعمال کر سکتے ہیں۔
جب آپ agent_id کے ساتھ آؤٹ باؤنڈ کال کرتے ہیں، تو اس کال کی قدروں کے ساتھ
variables بھیجیں:
{
"from_number": "+[REDACTED_PHONE]",
"to_number": "+[REDACTED_PHONE]",
"agent_id": 12,
"variables": {
"name": "Jordan"
}
}پلیس ہولڈر کے نام کو کلید بنا کر اسٹرنگ قدریں استعمال کریں۔ یہ متغیرات
محفوظ شدہ ایجنٹس پر لاگو ہوتے ہیں؛ اس گائیڈ کی اِن لائن config مثال انہیں استعمال نہیں کرتی۔
ناکامی کی قابلِ توجہ صورتیں
| خرابی | حل |
|---|---|
402 Payment Required | بیلنس ٹاپ اپ کریں یا خودکار ری لوڈ فعال کریں |
400 with code: destination_not_allowed | ThunderPhone اس نمبر پر کال نہیں کرتا: غلط نمبر، ایمرجنسی نمبر، پریمیم ریٹ نمبر، مختصر کوڈز، پابندی عائد ممالک، یا US کی وہ ریاست جسے آپ کی تنظیم نے آؤٹ باؤنڈ کالنگ کے لیے بلاک کیا ہے۔ ThunderPhone نمبروں سے عام US اور کینیڈین نمبرز کی اجازت ہے، اور کچھ بین الاقوامی منزلوں کی بھی اجازت ہے جن کا بل منزل کی شرح کے مطابق کیا جاتا ہے۔ reason بتاتا ہے کہ کون سا؛ بلاک کی گئی منزلیں دیکھیں |
ThunderPhone نمبر کے لیے retryable: false کے ساتھ 409 | code کی ہدایت پر عمل کریں: فون نمبرز صفحے پر آؤٹ باؤنڈ کالنگ کی درخواست کریں، زیر التوا جائزے کا انتظار کریں، یا کوئی دوسرا اہل نمبر استعمال کریں |
code: platform_outbound_daily_limit_reached کے ساتھ 429 | تنظیم آج ThunderPhone نمبروں سے آؤٹ باؤنڈ کالز کی حد استعمال کر چکی ہے۔ resets_at (00:00 UTC) تک انتظار کریں، فون نمبرز صفحے پر زیادہ حد کی درخواست کریں، یا اپنی VoIP کنکشن کے نمبر سے کال کریں |
code: concurrent_call_limit_reached کے ساتھ 429 | تنظیم میں اتنی کالز جاری ہیں جتنی اس کی بیک وقت کال کی حد ہے (ڈیفالٹ طور پر 20، جس میں آنے والی، جانے والی، ویب اور ٹیسٹ کالز شامل ہیں)۔ Retry-After ہیڈر میں درج سیکنڈز کے بعد یا کال ختم ہونے پر دوبارہ کوشش کریں؛ حد بڑھانے کے لیے support@thunderphone.com پر ای میل کریں |
code: outbound_queue_full کے ساتھ 429 | تنظیم کی 50 قطار میں موجود کالز منتظر ہیں۔ Retry-After ہیڈر میں درج سیکنڈز کے بعد دوبارہ کوشش کریں |
code: same_number_too_soon کے ساتھ 429 | آپ نے اسی to_number پر 10 سیکنڈ سے کم وقت پہلے کال کی تھی۔ Retry-After ہیڈر میں درج سیکنڈز کے بعد دوبارہ کوشش کریں |
صارف کے VoIP نمبر کے لیے retryable: false کے ساتھ 409 | code میں درج حالت درست کریں؛ تصدیق کی ناکامیوں کے لیے POST /v1/phone-numbers/{id}/verify-voip چلائیں |
409 آئیڈیمپو ٹینسی تنازع | کلید کو صرف اصل معمول پر لائی گئی درخواست کے ساتھ دوبارہ استعمال کریں، یا نئی کلید بھیجیں |
404 from_number is not registered to this organization | تصدیق کریں کہ from_number آپ کی تنظیم میں کسی فعال فون نمبر سے مطابقت رکھتا ہے۔ جو نمبر پہلے ہی ترتیب دیے جانے کے عمل میں ہو، ناکام ہو، منسوخ کیے جانے کے عمل میں ہو، یا منسوخ ہو چکا ہو، وہ بھی یہی جواب واپس کرتا ہے |
صرف detail فیلڈ کے ساتھ 500 | کوئی آؤٹ باؤنڈ ٹرنک کنفیگر نہیں ہے۔ سپورٹ سے رابطہ کریں؛ یہ نمبر کی حالت کا ایسا مسئلہ نہیں جسے آپ درست کر سکیں |
502 Bad Gateway | عارضی SIP / LiveKit ناکامی؛ دوبارہ کوشش کرنا محفوظ ہے |
مستحکم اہلیت کوڈز کی مکمل فہرست اور 409 کے دونوں جوابی ڈھانچوں کے لیے
آؤٹ باؤنڈ کالز حوالہ دیکھیں۔
اگر درخواست قبول ہونے کے بعد لیکن کال کیے جانے سے پہلے کوئی فعال نمبر نااہل ہو جائے،
تو حتمی جانچ دوبارہ کوشش نہ کیے جانے والا 409 پے لوڈ لوٹاتی ہے۔
ہولڈ وقت کو کنٹرول کرنا
بیرون ملک کالز جو کال وصول کرنے والے کے جواب دینے میں سست ہونے کی وجہ سے طویل ہو جائیں
(IVR ٹریز، قطاریں)، انہیں کال پر max_hold_seconds کے ذریعے یا اسے محفوظ شدہ ایجنٹ پر سیٹ کر کے محدود کیا جا سکتا ہے:
{
"from_number": "+15551234567",
"to_number": "+14155552671",
"agent_id": 12,
"max_hold_seconds": 120
}اگر گزشتہ N سیکنڈز میں کوئی انسانی آڈیو موصول نہ ہوئی ہو تو ایجنٹ کال ختم کر دیتا ہے۔ ڈیفالٹ 900 سیکنڈز (15 منٹ) ہے۔
اگر آپ محفوظ شدہ ایجنٹ اور بیرون ملک کال کی درخواست، دونوں پر max_hold_seconds سیٹ کرتے ہیں، تو اس کال کے لیے فی کال والی قدر استعمال کی جاتی ہے۔