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

Developer cookbook

Slack یا چیٹ ایپ سے کالز چلائیں

اپنا Slack، Teams یا ویب چیٹ بوٹ بنائیں جو عوامی API استعمال کرتے ہوئے کالز شروع کرے، انہیں براہِ راست فالو کرے، ایجنٹ کی رہنمائی کرے اور اس کے سوالات کے جواب دے۔

آپ اپنی ٹیم کے پہلے سے استعمال ہونے والی چیٹ ایپ سے ایک ایجنٹ کو چلا سکتے ہیں۔ ایک پیغام کال شروع کرتا ہے۔ کال تھریڈ میں براہِ راست جاری رہتی ہے۔ تھریڈ میں دیا گیا جواب ایجنٹ کی رہنمائی کرتا ہے۔ جب ایجنٹ کو کسی فیصلے کی ضرورت ہوتی ہے، تو وہ آپ سے وہیں پوچھتا ہے اور آپ کے جواب کا انتظار کرتا ہے۔

ThunderPhone آپ کے لیے یہ بوٹ ہوسٹ نہیں کرتا۔ آپ (یا آپ کا کوڈنگ ایجنٹ) ایک چھوٹا سرور بناتے ہیں جو آپ کی چیٹ ایپ کو عوامی API سے جوڑتا ہے۔ یہ صفحہ اجزاء دکھاتا ہے۔ یہ Slack، Microsoft Teams، Discord یا نجی ویب چیٹ صفحے کے لیے یکساں ہیں؛ مثالوں میں Slack استعمال کیا گیا ہے۔

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

آپ چیٹ میں یہ کرتے ہیںآپ کا بوٹ یہ کال کرتا ہےکیا ہوتا ہے
"Call Comcast and get the outage ETA" بھیجیںپیغام کو context کے طور پر استعمال کرتے ہوئے POST /v1/callایجنٹ نمبر ملاتا ہے۔ آپ کا بوٹ کال کے لیے ایک تھریڈ کھولتا ہے
تھریڈ دیکھیںtelephony.turn ویب ہکس وصول کرتا ہےایجنٹ یا دوسرا شخص جو بھی سطر کہتا ہے، وہ تھریڈ میں ظاہر ہوتی ہے
کال کے دوران تھریڈ میں جواب دیںPOST /v1/calls/{call_id}/whisperایجنٹ کو آپ کا نوٹ نجی طور پر ملتا ہے اور وہ اس پر عمل کرتا ہے۔ دوسرا شخص اسے کبھی نہیں سنتا
ایجنٹ کے سوال کا جواب دیںآپ کا ٹول اینڈ پوائنٹ آپ کا جواب واپس کرتا ہے، یا بعد میں اسے POST /v1/calls/{call_id}/tool-results کے ذریعے فراہم کرتا ہےایجنٹ اس کے ساتھ کال جاری رکھتا ہے؛ ہولڈ موڈ میں دوسرا شخص اس دوران ہولڈ میوزک سنتا ہے
نتیجہ پڑھیںtelephony.complete وصول کرتا ہےآپ کا بوٹ خلاصہ اور نتیجہ پوسٹ کرتا ہے

آپ کا بوٹ ایک میپنگ رکھتا ہے: کون سا چیٹ تھریڈ کس call_id سے تعلق رکھتا ہے۔

شروع کرنے سے پہلے

  • ایک API کلید، جو آپ کے سرور پر رکھی جائے اور کبھی براؤزر یا چیٹ میں نہ ہو۔ اسے تنظیم کی ترتیبات → کلیدیں کے تحت بنائیں (دیکھیں کلیدیں)۔
  • ایک آؤٹ باؤنڈ فعال نمبر اور ایک ایجنٹ کالز کے لیے۔ پیغام ہر کال کا context بن جاتا ہے، اس لیے ایک عمومی ایجنٹ ہر کام سنبھالتا ہے۔
  • ایک سرور جو ویب ہکس وصول کر سکتا ہو، جیسے Railway، Fly.io، Render یا آپ کا اپنا ہوسٹ۔
  • ایک ویب ہک اینڈ پوائنٹ جو اس سرور کی طرف اشارہ کرتا ہو اور telephony.turn اور telephony.complete کو سبسکرائب کیا گیا ہو۔ ٹرن ایونٹس صرف ان اینڈ پوائنٹس کو بھیجے جاتے ہیں جو انہیں فہرست میں رکھتے ہیں۔ دیکھیں ویب ہکس۔ ٹرن ایونٹس کے لیے ایجنٹ کی کال ریکارڈنگ فعال ہونی چاہیے، اور کال کے اختتام کا summary ایجنٹ کی کال کا خلاصہ بنائیں ترتیب کا تقاضا کرتا ہے؛ ان کے بغیر وہ فیلڈز خالی رہتے ہیں۔
  • آپ کی اپنی چیٹ ایپ۔ Slack کے لیے، اپنے ورک اسپیس میں api.slack.com/apps پر ایک ایپ بنائیں۔

1. پیغام سے کال شروع کریں

جب آپ کے بوٹ کو کوئی پیغام موصول ہو (براہ راست پیغام یا @مینشن)، تو فوراً Slack کی درخواست کی تصدیق کریں (Slack ایسی ہر درخواست دوبارہ بھیجتا ہے جس کی 3 سیکنڈ کے اندر تصدیق نہ ہو) اور باقی کام پس منظر میں کریں۔ تصدیق کریں کہ بھیجنے والے کو کال کرنے کی اجازت ہے، پھر پیغام کو context کے طور پر استعمال کرتے ہوئے کال شروع کریں:

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":   "+18005550100",
    "agent_id":    12,
    "context":     "Matthew asked: get the outage ETA for account 4471. Wait on hold if needed.",
    "idempotency_key": "slack-D012AB3CD-1731000000.000100"
  }'

واپس آنے والا call_id Slack تھریڈ کے ساتھ محفوظ کریں (channel اور پیغام کا ts) اور تھریڈ میں جواب دیں ("کال کی جا رہی ہے…")۔ idempotency_key کو چینل اور پیغام کے ts سے بنائیں (ts صرف اپنے چینل کے اندر منفرد ہوتا ہے)، تاکہ Slack ایونٹ دوبارہ آنے پر دوسری کال نہ لگے۔ اگر درخواست میں نمبر کے بجائے کسی شخص کا نام ہو، تو آپ کا بوٹ پہلے نمبر تلاش کرتا ہے۔ ThunderPhone صرف وہی to_number ڈائل کرتا ہے جو آپ بھیجتے ہیں۔

2. تھریڈ میں کال کی پیروی کریں

ہر telephony.turn ویب ہک میں call_id، بولنے والا (role: ایجنٹ کے لیے assistant، دوسرے شخص کے لیے user)، text اور ٹرن کی position شامل ہوتی ہے۔ call_id کے ذریعے تھریڈ تلاش کریں اور لائن پوسٹ کریں۔

  • اس پر عمل کرنے سے پہلے ہر ویب ہک کی تصدیق کریں۔ دیکھیں ویب ہک دستخطوں کی تصدیق کریں۔
  • اینویلپ کے event_id پر نقل ختم کریں اور position کے مطابق ترتیب دیں۔ ڈیلیوری کم از کم ایک بار ہوتی ہے، اور ٹرن غلط ترتیب میں آ سکتے ہیں۔
  • اگر مصروف کال تھریڈ کو بھر دے تو لائنوں کو بیچ میں پوسٹ کریں؛ ہر لائن کے لیے ایک پیغام کے بجائے ہر چند سیکنڈ بعد پوسٹ کرنا زیادہ بہتر پڑھا جاتا ہے۔

جب telephony.complete آئے، تو کال کیسے ختم ہوئی (status اور end_reason)، summary، اور کوئی بھی نکالا گیا ڈیٹا پوسٹ کریں، پھر تھریڈ بند کر دیں۔ فیلڈز کے لیے کال مکمل دیکھیں۔

3. تھریڈ سے کال کو ہدایت دیں

جب کوئی شخص جاری کال کے تھریڈ میں جواب دے، تو جواب کو سرگوشی کے طور پر بھیجیں، سوائے اس صورت کے کہ ایجنٹ کسی سوال کے جواب کا انتظار کر رہا ہو (مرحلہ 4)، جس میں جواب ہی اس سوال کا جواب ہوتا ہے:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/whisper \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text": "Ask whether they can waive the late fee."}'

ایجنٹ اسے نجی طور پر سنتا ہے اور اپنے اگلے ٹرن میں شامل کر لیتا ہے؛ دوسرا شخص خود سرگوشی کبھی نہیں سنتا۔ سرگوشی 1 سے 1000 حروف پر مشتمل ہوتی ہے۔ 409 کا مطلب ہے کہ کال اب جاری نہیں ہے: تھریڈ کو بتائیں کہ کال ختم ہو چکی ہے۔

4. ایجنٹ کو آپ سے پوچھنے دیں

ایجنٹ کو ایک ٹول دیں، مثلاً ایک question پیرامیٹر کے ساتھ ask_owner، جو آپ کے سرور کو کال کرے۔ اسے API کنکشن کے طور پر بنائیں اور ایجنٹ سے لنک کریں۔ ہر ٹول درخواست اپنی X-ThunderPhone-Call-ID ہیڈر میں کال لے کر آتی ہے۔

جواب واپس حاصل کرنے کے تین طریقے ہیں۔

کال کو ہولڈ پر رکھیں (10 منٹ تک)۔ ٹول کو ہولڈ موڈ پر سیٹ کریں: spec.wait_mode "hold" اور spec.timeout کو 600 سیکنڈ تک (ٹائم آؤٹ کے بغیر ہولڈ 20 سیکنڈ جاری رہتا ہے)، API کے ذریعے (ڈیش بورڈ ایڈیٹر میں ابھی کوئی فیلڈ موجود نہیں)۔ آپ کا اینڈپوائنٹ سوال کو کال کے تھریڈ میں پوسٹ کرتا ہے اور فوراً ایک زیر التوا نتیجے کے ساتھ جواب دیتا ہے:

{"status": "pending", "request_id": "q-C012AB3CD-1731000042.000300"}

دوسرا شخص ایجنٹ سے ایک جملہ سنتا ہے، پھر ہولڈ میوزک۔ فون مینو یا وائس میل پر ایجنٹ اس کے بجائے بول کر اپ ڈیٹس دیتا ہے، اور فل ڈوپلیکس ایجنٹ ہولڈ نہیں ہوتا: اسے زیر التوا جواب بطور نتیجہ ملتا ہے۔ جب جواب تھریڈ میں آ جائے تو اسے POST /v1/calls/{call_id}/tool-results کے ذریعے پہنچائیں:

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"request_id": "q-C012AB3CD-1731000042.000300", "result": {"answer": "Yes, book Tuesday at 10."}}'

میوزک دھیرے دھیرے ختم ہو جاتا ہے اور ایجنٹ آپ کے جواب کے ساتھ آگے بڑھتا ہے۔ اگر timeout سے پہلے کوئی جواب نہ دے تو ایجنٹ کو بتایا جاتا ہے کہ کوئی جواب نہیں آیا اور وہ دوسرے شخص کو اگلے اقدامات پیش کرتا ہے۔ جب کسی کال کے لیے کوئی سوال زیر التوا ہو تو اس کے تھریڈ میں اگلا جواب اسی کا جواب ہوتا ہے: اسے ٹول نتیجے کے طور پر پہنچائیں اور اسے سرگوشی کے طور پر بھی نہ بھیجیں (سرگوشی ٹول کے واپس آنے کے بعد ہی ایجنٹ تک پہنچتی ہے)۔ دیکھیں طویل انتظار۔

درخواست میں انتظار کریں (3 منٹ تک)۔ آپ کا اینڈپوائنٹ سوال پوسٹ کرتا ہے، جواب کا انتظار کرتا ہے اور اسے واپس کرتا ہے، مثلاً {"answer": "Yes, book Tuesday at 10."}۔ API کے ذریعے ٹول کا spec.timeout سیٹ کریں، 180 سیکنڈ تک (ڈیفالٹ 20 ہے)۔ اپنے اینڈپوائنٹ کو اس سے چند سیکنڈ کم کی اپنی ڈیڈ لائن دیں (مثلاً 170 سیکنڈ)، تاکہ جب کوئی جواب نہ دے تو بھی یہ ایسی چیز واپس کرے جس پر ایجنٹ عمل کر سکے، مثلاً {"answer": null, "note": "No reply yet. Offer to take a message."}۔ وہ ٹول جو اپنے timeout تک پہنچتا ہے، ایجنٹ تک بطور خرابی پہنچتا ہے، اور آپ کے ہوسٹ کو اتنی دیر تک درخواست کھلی رکھنی ہوگی۔ انتظار کے دوران ایجنٹ دوسرے شخص کو بتاتا ہے کہ وہ چیک کر رہا ہے، تقریباً 12 سیکنڈ بعد کہتا ہے کہ وہ اب بھی کام کر رہا ہے، اور پھر تقریباً ہر 15 سیکنڈ بعد مختصر اپ ڈیٹ دیتا ہے۔ یہاں بھی ہولڈ موڈ کام کرتا ہے: spec.wait_mode کو "hold" پر سیٹ کریں، اور دوسرا شخص اپ ڈیٹس کے بجائے میوزک سنتا ہے۔

سرگوشی کے ذریعے جواب دیں۔ آپ کا اینڈپوائنٹ سوال پوسٹ کرتا ہے اور فوراً واپس آتا ہے، مثلاً {"status": "asked", "note": "Matthew has been asked; his answer will come as guidance."}۔ جب جواب آ جائے تو اسے سرگوشی کے طور پر بھیجیں (مرحلہ 3)، اور ایجنٹ فوراً اس کا جواب دیتا ہے۔ اسے ان جوابات کے لیے استعمال کریں جن میں 10 منٹ سے زیادہ وقت لگ سکتا ہے۔ کال ہولڈ پر نہیں ہوتی: آپ کے پرامپٹ کو ایجنٹ کو بتانا چاہیے کہ اس دوران کیا کرنا ہے، مثلاً دوسرے شخص کو مصروف رکھنا یا اسے واپس کال کرنے کی پیشکش کرنا۔

ہر صورت میں، ایجنٹ کے پرامپٹ میں بتائیں کہ ٹول کب استعمال کرنا ہے اور انتظار کے دوران دوسرے شخص کو کیا کہنا ہے:

When you need Matthew's decision, use ask_owner with a short question.
Tell the person you're checking with Matthew and it may take a minute.
If there's no answer, offer to take a message or have Matthew call back.

منصوبہ بندی کے لیے حدود

  • آپ کے endpoint کو ٹول کے timeout کے اندر، زیادہ سے زیادہ 180 سیکنڈز میں جواب دینا چاہیے۔ ہولڈ موڈ میں موجود ٹول زیرِ التوا نتیجے کے ساتھ کال کو زیادہ سے زیادہ 600 سیکنڈز تک ہولڈ پر رکھ سکتا ہے۔
  • جب کوئی ٹول انتظار کرتا ہے، ایجنٹ دوسرے شخص کو جواب نہیں دیتا۔ ہولڈ موڈ میں وہ موسیقی سنتے ہیں؛ بصورتِ دیگر، مختصر بولے گئے اپ ڈیٹس۔
  • سرگوشی زیادہ سے زیادہ 1000 حروف کی ہو سکتی ہے۔
  • telephony.turn کی ترسیل کم از کم ایک بار ہوتی ہے اور ممکن ہے ترتیب سے ہٹ کر ہو۔

سکیورٹی چیک لسٹ

  • API کلید اپنے سرور پر رکھیں۔
  • webhooks اور ٹول کی درخواستوں پر ThunderPhone کے دستخطوں کی، اور Slack کی درخواستوں پر Slack کے signing secret کی تصدیق کریں۔ ThunderPhone کے دونوں دستخط مختلف secrets استعمال کرتے ہیں: webhook کی ترسیلات webhook endpoint کا اپنا secret استعمال کرتی ہیں، جبکہ ٹول کی درخواستیں آپ کی تنظیم کا webhook secret استعمال کرتی ہیں جو GET /v1/webhook سے حاصل ہوتا ہے۔
  • طے کریں کہ کالز کون شروع کر سکتا ہے: کال کرنے سے پہلے Slack صارف ID چیک کریں۔
  • آؤٹ باؤنڈ کالز پر وہی قواعد لاگو ہوتے ہیں جو کسی بھی دوسری کال پر ہوتے ہیں۔ آؤٹ باؤنڈ کالنگ کے قوانین دیکھیں۔

اسے کوڈنگ ایجنٹ کے ساتھ بنائیں

اپنے کوڈنگ ایجنٹ کو docs MCP server اور اس صفحے کی طرف رہنمائی دیں، اور اس سے کہیں کہ "میرے ThunderPhone ایجنٹ کے لیے ایک Slack bot بنائیں جو اس گائیڈ کی پیروی کرے"۔ ThunderPhone ایپ میں معاون Zeus، ایجنٹ والی سمت ترتیب دے سکتا ہے (webhook endpoint، ٹول، اور prompt کی سطریں) اور چیٹ میں bot کے لیے ابتدائی کوڈ لکھ سکتا ہے۔