Open in
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 کے لیے ابتدائی کوڈ لکھ سکتا ہے۔