Open in
فنکشن ٹولز
اپنے AI ایجنٹس کو فنکشن ٹولز دیں جو گفتگو کے دوران بیرونی APIs کو کال کریں — کسٹمر ڈیٹا حاصل کریں، اپائنٹمنٹس بک کریں، ریکارڈز اپ ڈیٹ کریں — ٹائپ شدہ پیرامیٹرز کے ساتھ۔
فنکشن ٹولز آپ کے AI ایجنٹس کو فون کالز کے دوران بیرونی APIs استعمال کرنے کی اجازت دیتے ہیں۔ انہیں کسٹمر کا ڈیٹا تلاش کرنے، دستیابی چیک کرنے، اپائنٹمنٹس بُک کرنے، یا آپ کے بیک اینڈ کی معاونت یافتہ کوئی بھی کارروائی انجام دینے کے لیے استعمال کریں۔
یہ کیسے کام کرتا ہے
- آپ ایک schema کے ساتھ ٹولز کی تعریف کرتے ہیں (ٹول کن arguments کو قبول کرتا ہے)
- آپ
endpointکنفیگریشن فراہم کرتے ہیں (جہاں ThunderPhone آپ کی API کو کال کرتا ہے) — یا اپنی org webhook پر ٹول کالز وصول کرنے کے لیے اسے شامل نہ کریں - کال کے دوران، AI گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ ٹول کب استعمال کرنا ہے
- ThunderPhone ٹول arguments کے ساتھ آپ کے endpoint کو کال کرتا ہے
- گفتگو جاری رکھنے کے لیے آپ کا API جواب AI کو واپس فراہم کیا جاتا ہے
| صلاحیت | کہاں چلتی ہے | سیٹ اپ |
|---|---|---|
| بلٹ اِن ٹولز | ThunderPhone | prompt ہدایات؛ کچھ ٹولز کو ایجنٹ کی سیٹنگ بھی درکار ہوتی ہے |
| ایپ کنکشنز | ThunderPhone اور منسلک فراہم کنندہ | اکاؤنٹ منسلک کریں اور منظور شدہ کارروائیاں شامل کریں |
| API کنکشنز اور فنکشن ٹولز | آپ کی HTTP API | endpoint اور schema کی تعریف کریں، یا webhook کے ذریعے فنکشن کالز وصول کریں |
| MCP سرورز | ایک ریموٹ MCP سرور | سرور شامل کریں، اس کے ٹولز دریافت کریں، اور اسے ایجنٹ کے ساتھ منسلک کریں |
ٹول Schema
ہر ٹول اس ساخت کی پیروی کرتا ہے:
{
"type": "function",
"function": {
"name": "search_appointments",
"description": "Find available appointment slots for a given date",
"parameters": {
"type": "object",
"properties": {
"date": {
"type": "string",
"description": "Date in YYYY-MM-DD format"
},
"service": {
"type": "string",
"description": "Type of service (e.g., 'consultation', 'follow-up')"
}
},
"required": ["date"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/search",
"method": "POST",
"headers": {
"X-Api-Key": "your-api-key"
}
},
"timeout": 120
}ٹول کنفیگریشن
| فیلڈ | قسم | ضروری | تفصیل |
|---|---|---|---|
timeout | عدد | نہیں | سیکنڈز میں زیادہ سے زیادہ عمل درآمد کا وقت (ڈیفالٹ: 20، زیادہ سے زیادہ: 180، یا wait_mode: "hold" کے ساتھ 600) |
wait_mode | اسٹرنگ | نہیں | ٹول چلنے کے دوران کالر کیا سنتا ہے: updates (ڈیفالٹ)، مختصر زبانی اپ ڈیٹس؛ یا hold، ہولڈ موسیقی۔ طویل انتظار: ہولڈ موڈ اور بعد میں جواب دیں دیکھیں۔ |
call_start | آبجیکٹ | نہیں | ہر فون کال کے آغاز پر، خیرمقدم سے پہلے، ٹول خودکار طور پر بھی چلائیں۔ کال کے آغاز پر ٹول چلائیں دیکھیں۔ |
فنکشن کی تعریف
| فیلڈ | قسم | لازمی | وضاحت |
|---|---|---|---|
name | سٹرنگ | ہاں | ٹول کا شناخت کنندہ، ایک کال کے ٹولز میں منفرد۔ مختلف ایجنٹس کے پاس ایک ہی نام کا اپنا ٹول ہو سکتا ہے |
description | سٹرنگ | ہاں | AI کو بتاتا ہے کہ یہ ٹول کب استعمال کرنا ہے |
parameters | آبجیکٹ | ہاں | ٹول کے آرگیومنٹس کے لیے JSON Schema |
Endpoint کنفیگریشن
| فیلڈ | قسم | ضروری | وضاحت |
|---|---|---|---|
url | سٹرنگ | ہاں | آپ کا API endpoint URL |
method | سٹرنگ | نہیں | HTTP طریقہ (ڈیفالٹ: POST) |
headers | آبجیکٹ | نہیں | شامل کرنے کے لیے حسب ضرورت headers |
استعمال کے دو راستے
آپ کے سرور کو کون سی درخواست موصول ہوتی ہے، یہ اس بات پر منحصر ہے کہ ٹول کے پاس
endpoint موجود ہے یا نہیں:
endpoint کے ساتھ ٹول | endpoint کے بغیر ٹول | |
|---|---|---|
| درخواست کہاں جاتی ہے | براہِ راست endpoint.url پر | آپ کی تنظیم کا پرانا ویب ہک URL |
| باڈی | منتخب کردہ درخواست فارمیٹ (بطور ڈیفالٹ صرف آرگیومنٹس) | telephony.tool / web.tool لفافہ |
| ہیڈرز | آپ کے endpoint.headers اور X-ThunderPhone-Call-ID اور X-ThunderPhone-Signature-V2 اور X-ThunderPhone-Signature، نیز فون کالز پر کال کے نمبرز | Content-Type اور X-ThunderPhone-Signature-V2 اور X-ThunderPhone-Signature |
| دستخطی کلید | تنظیم کا ویب ہک سیکرٹ | تنظیم کا ویب ہک سیکرٹ |
دونوں راستے بلاکنگ ہیں — AI نتیجے کے لیے جملے کے درمیان انتظار کرتا ہے۔ ڈیفالٹ ٹائم آؤٹ 20 s ہے؛ طویل عمل درآمد کی اجازت دینے کے لیے ٹول کا ٹاپ لیول
timeout مقرر کریں، جو پلیٹ فارم کی زیادہ سے زیادہ 180 s حد تک ہو سکتا ہے۔ ہینڈلرز کو تیز رکھیں۔ کسی شخص یا سست جاب کے انتظار کے لیے
ہولڈ موڈ استعمال کریں۔ امتزاج بھی ممکن ہے:
ایسی کال میں جس کی تنظیم کے پاس ویب ہک URL ہو، endpoint والے ٹولز کو براہِ راست کال کیا جاتا ہے اور باقی ویب ہک پر واپس چلے جاتے ہیں۔
براہِ راست endpoint کالز
جب AI کسی ایسے ٹول کو استعمال کرتا ہے جس میں endpoint ہو، تو ThunderPhone
آپ کے URL پر ایک درخواست بھیجتا ہے:
درخواست کے ہیڈرز
POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-keyآپ کے endpoint.headers سے حسب ضرورت ہیڈرز ہمیشہ
بعینہ شامل کیے جاتے ہیں، نیز ThunderPhone-نامی اسپیس والے یہ ہیڈرز:
X-ThunderPhone-Signature-V2— طریقہ، path، query اور body پر ٹائم اسٹیمپ شدہ HMAC-SHA256، جو آپ کے org webhook secret سے کلید بند ہوتا ہے۔ اسے تصدیق کریں اور 5 منٹ سے پرانی درخواستوں کو مسترد کریں؛ ملاحظہ کریں webhook signatures کی تصدیق کریںX-ThunderPhone-Signature— عین request-body bytes کا پرانا HMAC-SHA256، اسی کلید کے ساتھ، جو موجودہ تصدیق کاروں کے لیے اب بھی بھیجا جاتا ہےX-ThunderPhone-Call-ID— موجودہ کال IDX-ThunderPhone-From-NumberاورX-ThunderPhone-To-Number— کال کے E.164 فارمیٹ میں From اور To نمبر۔ ان کا مطلبtelephony.completeمیں موجودfrom_numberاورto_numberجیسا ہی ہے: آؤٹ باؤنڈ کال میں From آپ کے ایجنٹ کا نمبر ہوتا ہے اور To اس شخص کا نمبر ہوتا ہے جسے کال کی گئی ہے۔ جب caller ID چھپائی گئی ہو یا فون نمبر نہ ہو تو نمبر شامل نہیں کیا جاتاX-ThunderPhone-Call-Direction—inboundیاoutbound، تاکہ آپ معلوم کر سکیں کہ کون سا نمبر صارف کا ہے
کال نمبر والے headers صرف فون کالز میں بھیجے جاتے ہیں۔ ویب، widget، realtime اور browser Talk ٹیسٹس میں فون نمبر نہیں ہوتا، اس لیے یہ شامل نہیں کیے جاتے۔ ایجنٹ ایڈیٹر سے کی گئی ٹیسٹ کالز اور AI simulations میں نقلی کالر کا نمبر شامل ہوتا ہے۔ signatures headers کا احاطہ نہیں کرتے: V2 ٹائم اسٹیمپ، طریقہ، path، query اور body پر دستخط کرتا ہے۔ اگر آپ کو نمبروں پر دستخط درکار ہوں تو انہیں body سے پڑھیں: retell request format میں تینوں شامل ہوتے ہیں، اور vapi میں صارف کا نمبر شامل ہوتا ہے۔
Content-Type: application/json سیٹ کیا جاتا ہے، جب تک کہ آپ کے endpoint.headers
اسے اووررائیڈ نہ کر دیں — حسبِ ضرورت Content-Type کو ترجیح حاصل ہوتی ہے۔
درخواست کی ساخت
ہر API کنکشن میں request_format کی ترتیب ہوتی ہے۔ جب درآمد شدہ ٹول کو
اس پلیٹ فارم کے لیے بنے ہوئے اینڈپوائنٹ کو کال کرتے رہنا ہو تو vapi یا
retell منتخب کریں۔ نئے اور موجودہ کنکشنز کے لیے طے شدہ قدر standard ہے۔
POST / PUT / PATCH کے لیے، ThunderPhone منتخب کردہ
لفافے کو معیاری انداز میں سیریلائز کرتا ہے (ترتیب شدہ کلیدیں، مختصر جداکار)۔ دونوں دستخط
عین انہی بائٹس کا احاطہ کرتے ہیں۔
Standard
standard کسی ریپر کے بغیر صرف ٹول آرگیومنٹس بھیجتا ہے۔ یہ ڈیفالٹ ہے
اور ThunderPhone کی اصل ریکویسٹ باڈی کو بائٹ بہ بائٹ برقرار رکھتا ہے:
{"date":"2025-01-02","service":"consultation"}Vapi
vapi Vapi کا tool-calls server message
Vapi کی دستاویز کردہ ساخت میں بھیجتا ہے۔ call.id ThunderPhone کال ID ہے۔
فون کالز میں، call.customer.number دوسرے فریق کا نمبر ہوتا ہے، بالکل
Vapi کے call object کی طرح: inbound کال میں کالر، اور outbound کال میں
جس شخص کو کال کی گئی ہو۔ جب یہ نمبر پوشیدہ ہو یا فون نمبر نہ ہو تو اسے
شامل نہیں کیا جاتا۔ tool-call id ہر invocation کے لیے منفرد ہوتا ہے اور
endpoint کے نتیجے سے مطابقت کے لیے دوبارہ استعمال ہوتا ہے۔ کال toolCallList اور
toolWithToolCallList، دونوں میں ظاہر ہوتی ہے، جہاں function.arguments ایک JSON object ہوتا ہے:
{
"message": {
"type": "tool-calls",
"timestamp": 1725000000123,
"call": { "id": "987654321" },
"toolCallList": [
{
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
],
"toolWithToolCallList": [
{
"type": "function",
"function": { "name": "search_appointments" },
"toolCall": {
"id": "call_00112233445566778899aabbccddeeff",
"type": "function",
"function": {
"name": "search_appointments",
"arguments": { "date": "2025-01-02", "service": "consultation" }
}
}
}
]
}
}Vapi کے مخصوص فیلڈز، جیسے assistant، artifact اور مکمل call آبجیکٹ،
نہیں بھیجے جاتے۔
مطابق ٹول کال ID کے ساتھ Vapi کا جوابی لفافہ واپس کریں:
{
"results": [
{
"toolCallId": "call_00112233445566778899aabbccddeeff",
"result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
}
]
}ThunderPhone، AI کو غیر ملفوف result اسٹرنگ دیتا ہے۔ ان اینڈپوائنٹس کے ساتھ مطابقت کے لیے
جو پہلے ہی JSON قدر لوٹاتے ہیں، یہ JSON قدر بھی قبول کرتا ہے۔ result کی جگہ موجود
error، AI کو ٹول کی خرابی کے طور پر واپس کیا جاتا ہے۔ اگر اینڈپوائنٹ خراب ساخت یا غیر مطابق Vapi لفافہ لوٹائے تو ThunderPhone
انتباہ لاگ کرتا ہے اور کال ناکام کرنے کے بجائے اپنی معیاری جوابی تجزیہ کاری پر واپس آتا ہے۔
Retell
retell، Retell کسٹم
فنکشن کے لیے دستاویزی درخواست بھیجتا ہے:
{
"name": "search_appointments",
"call": {
"call_id": "987654321",
"from_number": "+14155550199",
"to_number": "+14155550100",
"direction": "inbound"
},
"args": { "date": "2025-01-02", "service": "consultation" }
}فون کالز میں، call آبجیکٹ call_id، from_number،
to_number اور direction (inbound یا outbound) رکھتا ہے، جو
وہ فیلڈ نام ہیں جو Retell کا فون کال آبجیکٹ استعمال کرتا ہے۔ یہ کال نمبر
ہیڈرز سے مطابقت رکھتے ہیں، اور ہیڈرز کے برعکس دونوں دستخطوں میں شامل ہوتے ہیں۔
جو نمبر مخفی ہو یا فون نمبر نہ ہو، اسے شامل نہیں کیا جاتا۔ ویب، ویجیٹ،
ریئل ٹائم اور براؤزر Talk ٹیسٹس میں اس میں صرف call_id ہوتا ہے۔ ThunderPhone
Retell کے مخصوص فیلڈز شامل نہیں کرتا جو وہ ڈسپیچ کے وقت درست طور پر فراہم نہیں کر سکتا، جیسے
agent_id، transcript، transcript_object، metadata، یا متحرک
ویری ایبلز۔ Retell کسی بھی ریسپانس باڈی کو قبول کرتا ہے؛ ThunderPhone اسے
معیاری ریسپانس ہینڈلنگ کے ذریعے آگے منتقل کرتا ہے۔
GET / DELETE کے لیے، آرگیومنٹس کوئری پیرامیٹرز کے طور پر بھیجے جاتے ہیں
اور request_format سے قطع نظر باڈی خالی ہوتی ہے۔ V2 دستخط
بھیجی گئی کوئری اسٹرنگ کا احاطہ کرتا ہے؛ پرانا دستخط خالی بائٹ اسٹرنگ پر شمار کیا جاتا ہے۔ ملاحظہ کریں
ویب ہک دستخطوں کی توثیق کریں۔
جواب
ٹول کے نتیجے کے ساتھ JSON جواب واپس کریں:
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}جواب کو فارمیٹ کر کے AI کو گفتگو جاری رکھنے کے لیے فراہم کیا جاتا ہے۔
غیر JSON جوابات کو {"data": "<text>"} کی صورت میں wrap کیا جاتا ہے؛
timeout اور connection کی ناکامیوں کو AI کو errors کے طور پر رپورٹ کیا جاتا ہے، تاکہ
ایجنٹ معذرت کر کے گفتگو آگے بڑھا سکے، رکے نہیں۔
Webhook موڈ dispatch
وہ ٹولز جن میں endpoint نہیں ہوتا، آپ کے org کے legacy
webhook URL پر دستخط شدہ telephony.tool (فون کالز) یا web.tool
(web کالز) درخواست کے طور پر dispatch کیے جاتے ہیں۔ آڈٹ اطلاعات
کے برعکس، جو execution کے بعد webhook endpoints پر پہنچائی جاتی ہیں، یہ درخواست خود
execution ہے — آپ کا HTTP جواب ہی ٹول کا نتیجہ ہوتا ہے۔
{
"type": "telephony.tool",
"data": {
"call_id": 987654321,
"tool_name": "search_appointments",
"arguments": { "date": "2026-04-21" },
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}web.tool میں from_number / to_number کے بجائے origin_domain شامل ہوتا ہے۔ ٹول کے نتیجے کے ساتھ JSON میں جواب دیں — براہِ راست endpoint کالز جیسا ہی جواب کا معاہدہ۔ درخواست پر ہر دوسرے webhook کی طرح، دونوں signature headers کے ساتھ org webhook secret سے دستخط کیے جاتے ہیں۔
طویل انتظار: ہولڈ موڈ اور بعد میں جواب دینا
کچھ ٹولز کسی شخص کا انتظار کرتے ہیں: رعایت کی منظوری دینے والا مینیجر، یا Slack میں سوال کا جواب دینے والا مالک۔ ان ٹولز پر wait_mode کو "hold" پر سیٹ کریں۔
wait_mode: "updates" (ڈیفالٹ) | wait_mode: "hold" | |
|---|---|---|
| کالر کیا سنتا ہے | ٹول شروع ہونے کی لائن، پھر تقریباً 12 سیکنڈ بعد ایک مختصر "ابھی کام جاری ہے" لائن اور پھر تقریباً ہر 15 سیکنڈ بعد ایک اور | ٹول شروع ہونے کی لائن، پھر نتیجہ آنے تک ہولڈ میوزک |
timeout کی زیادہ سے زیادہ مدت | 180 سیکنڈ | 600 سیکنڈ |
| زیر التوا جوابات | نتیجے کے طور پر ایجنٹ کو بھیجے جاتے ہیں | جب تک آپ نتیجہ فراہم نہ کریں، ٹول کھلا رہتا ہے |
ہولڈ موڈ میں، ٹول شروع ہوتے وقت ایجنٹ ایک لائن کہتا ہے (اپنے الفاظ میں، یا ایجنٹ پر سیٹ کی گئی ٹول شروع ہونے کی لائن)، پھر کالر ہولڈ میوزک سنتا ہے۔ ایجنٹ کے نتیجہ بولنے سے پہلے میوزک مدھم ہو کر بند ہو جاتا ہے۔ جو ٹول ایک یا دو سیکنڈ کے اندر جواب دے، اس میں بالکل میوزک نہیں چلتا۔ جب ایجنٹ کسی فون مینو یا وائس میل باکس سے بات کر رہا ہو تو وہ اس کے بجائے بولے گئے اپ ڈیٹس استعمال کرتا ہے، کیونکہ میوزک کو جواب سمجھا جا سکتا ہے۔ اس میں وہ کال بھی شامل ہے جسے ہولڈ کے دوران مینو یا میل باکس کے طور پر شناخت کیا جائے: میوزک بند ہو جاتا ہے اور بولے گئے اپ ڈیٹس شروع ہو جاتے ہیں۔ یہی اس کال میں بھی ہوتا ہے جہاں میوزک نہیں چل سکتا۔
اگر کالر ہولڈ کے دوران بولتا ہے تو میوزک چلتا رہتا ہے اور ایجنٹ ابھی جواب نہیں دیتا۔ وہ کالر کی بات سنتا ہے اور نتیجے کے ساتھ اس کا جواب دیتا ہے۔ کال بند کرنے سے کال اور کھلا ٹول ختم ہو جاتا ہے۔
بعد میں جواب دینا
آپ کے اینڈ پوائنٹ کا اپنا جواب پھر بھی 180 سیکنڈ کے اندر آنا ضروری ہے۔ کالر کو زیادہ دیر ہولڈ پر رکھنے کے لیے، فوراً ایک زیر التوا نتیجے کے ساتھ جواب دیں:
{ "status": "pending", "request_id": "ask-4471" }request_id زیادہ سے زیادہ 200 حروف کی کوئی بھی اسٹرنگ ہے جو آپ کی طرف سے اس درخواست کی شناخت کرتی ہے۔ کالر اس وقت تک ہولڈ پر رہتا ہے جب تک آپ اس کا نتیجہ
POST /v1/calls/{call_id}/tool-results
کے ذریعے فراہم نہ کر دیں۔ call_id ٹول درخواست کا X-ThunderPhone-Call-ID ہیڈر ہے۔
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": "ask-4471",
"result": { "answer": "Yes, book Tuesday at 10." }
}'ایجنٹ result کو ٹول کے جواب کے طور پر پڑھتا ہے، بالکل اسی طرح جیسے آپ کے اینڈ پوائنٹ نے اسے واپس کیا ہو۔ اگر ٹول کے timeout سے پہلے، جس کا حساب ٹول کال ہونے کے وقت سے کیا جاتا ہے، کوئی نتیجہ نہیں آتا تو ایجنٹ کو بتایا جاتا ہے کہ کوئی جواب واپس نہیں آیا اور وہ کالر کو اگلے اقدامات پیش کرتا ہے، جیسے پیغام لینا۔
آپ جب چاہیں نتیجہ پوسٹ کر سکتے ہیں، حتیٰ کہ آپ کا زیر التوا جواب ThunderPhone تک پہنچنے سے پہلے بھی۔ 202 کا مطلب ہے کہ کال نے اسے قبول کر لیا: کسی کھلی درخواست نے اسے لے لیا، یا ٹول کی اپنی درخواست ابھی جاری ہے اور اس کا زیر التوا جواب اسے حاصل کر لے گا۔ ایسا نتیجہ جسے کوئی درخواست کبھی حاصل نہ کرے (آپ کے اینڈ پوائنٹ نے پھر اس request_id کے لیے زیر التوا کے علاوہ کچھ اور جواب دیا) حذف کر دیا جاتا ہے۔
اگر کنکشن میں ریسپانس ٹرانسفارم موجود ہو (ایسا کوڈ جو ایجنٹ کے دیکھنے سے پہلے آپ کے اینڈ پوائنٹ کے جواب کو دوبارہ لکھتا ہے)، تو ThunderPhone کے زیر التوا جواب کی جانچ کرنے سے پہلے ٹرانسفارم آپ کے اینڈ پوائنٹ کے اپنے جواب پر چلتا ہے، اس لیے اسے زیر التوا جواب میں status اور request_id برقرار رکھنے چاہییں۔ یہ آپ کے بعد میں پوسٹ کیے گئے نتیجے پر نہیں چلتا: ایجنٹ کو وہ نتیجہ اسی طرح ملتا ہے جیسے آپ اسے بھیجتے ہیں۔
فل ڈوپلیکس ایجنٹ میں ہولڈ میوزک یا اپ ڈیٹ لائنیں نہیں ہوتیں، اس لیے اس کی کالز میں ہولڈ ٹول updates ٹول کی طرح کام کرتا ہے: زیر التوا جواب ٹول کے نتیجے کے طور پر ایجنٹ تک پہنچتا ہے۔
updates موڈ میں کسی ٹول کا زیر التوا جواب کھلا نہیں رکھا جاتا: ایجنٹ اسے ٹول کے نتیجے کے طور پر وصول کرتا ہے۔
دستخط کی تصدیق
براہِ راست ٹول کالز پر ویب ہکس کی طرح دستخط کیے جاتے ہیں، جو آپ کے ادارے کے ویب ہک سیکرٹ کے ذریعے کلید بند ہوتے ہیں:
X-ThunderPhone-Signature-V2بھیجے گئے ٹائم اسٹیمپ، میتھڈ، پاتھ اور کوئری کے ساتھ ساتھ باڈی کے عین بائٹس پر دستخط کرتا ہے۔ ان درخواستوں کو مسترد کریں جن کا ٹائم اسٹیمپ آپ کی گھڑی سے 5 منٹ سے زیادہ مختلف ہو۔X-ThunderPhone-Signature(لیگیسی) صرف باڈی بائٹس پر دستخط کرتا ہے، جبکہGET/DELETEکے لیے خالی بائٹ اسٹرنگ پر دستخط کرتا ہے۔ یہ اب بھی بغیر تبدیلی کے بھیجا جاتا ہے۔
SDK ہیلپرز 5 منٹ کی مدت سمیت V2 ہیڈر کی جانچ کرتے ہیں:
import json
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
app = FastAPI()
@app.post("/appointments/search")
async def search_appointments(request: Request):
body = await request.body()
query = request.scope.get("query_string", b"").decode("latin-1")
path = request.url.path + (f"?{query}" if query else "")
if not verify_signature(
request.headers.get("X-ThunderPhone-Signature-V2"),
secret=WEBHOOK_SECRET,
method=request.method,
path=path,
body=body,
):
raise HTTPException(status_code=401)
data = json.loads(body)
date = data["date"]
# Look up availability
slots = await get_available_slots(date)
return {"available_slots": slots}import express from "express";
import { verifySignature } from "@thunderphone/sdk";
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
const ok = verifySignature({
header: req.header('X-ThunderPhone-Signature-V2'),
secret: WEBHOOK_SECRET,
method: req.method,
path: req.originalUrl,
body: req.body,
});
if (!ok) return res.status(401).send('Invalid signature');
const { date, service } = JSON.parse(req.body);
// Look up availability
const slots = getAvailableSlots(date, service);
res.json({ available_slots: slots });
});مکمل ترکیبیں — دستخط شدہ اسٹرنگ، عملی مثال، SDK کے بغیر کوڈ، GET / DELETE کا معاملہ اور سیکرٹ نہ ہونے سے متعلق تنبیہ — ویب ہک دستخطوں کی تصدیق کریں میں موجود ہیں۔
مثال: مکمل بکنگ فلو
یہ مکمل اپائنٹمنٹ بکنگ سسٹم کے لیے ٹولز کا ایک مجموعہ ہے:
{
"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": "key" }
}
},
{
"type": "function",
"function": {
"name": "book_appointment",
"description": "Book an appointment at a specific time",
"parameters": {
"type": "object",
"properties": {
"date": { "type": "string", "description": "YYYY-MM-DD" },
"time": { "type": "string", "description": "HH:MM format" },
"customer_name": { "type": "string" },
"customer_phone": { "type": "string" }
},
"required": ["date", "time", "customer_name"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/book",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
},
{
"type": "function",
"function": {
"name": "cancel_appointment",
"description": "Cancel an existing appointment",
"parameters": {
"type": "object",
"properties": {
"confirmation_number": { "type": "string" }
},
"required": ["confirmation_number"]
}
},
"endpoint": {
"url": "https://api.example.com/appointments/cancel",
"method": "POST",
"headers": { "X-Api-Key": "key" }
}
}
]
}کال کے آغاز پر ٹول چلائیں
ہر فون کال کے آغاز پر، ایجنٹ کے اپنا پہلا لفظ کہنے سے پہلے، ایک ٹول خودکار طور پر بھی چل سکتا ہے تاکہ خیرمقدمی پیغام نتیجہ استعمال کر سکے۔ عام صورت کال کرنے والے کے نمبر کے ذریعے CRM تلاش کی ہوتی ہے: "واپس خوش آمدید، آرتھی! کیا آپ اپنا معمول کا آرڈر چاہیں گی؟"
ڈیش بورڈ میں، API کنکشن کھولیں اور یہ کب چلتا ہے کو
ہر فون کال کے آغاز پر پر سیٹ کریں، پھر ہر پیرامیٹر کو ملنے والی قدر بھریں۔ API کے ذریعے، انضمام کے trigger کو
call_start اور اس کے call_start_arguments
(API کنکشنز) پر سیٹ کریں، یا کسی ان لائن ٹول میں call_start
بلاک شامل کریں:
{
"type": "function",
"function": {
"name": "get_contact_by_phone",
"description": "Look up a customer by phone number.",
"parameters": {
"type": "object",
"properties": {
"business_id": {"type": "string"},
"phone_number": {"type": "string"}
},
"required": ["business_id", "phone_number"]
}
},
"endpoint": {"url": "https://crm.example.com/contacts/lookup"},
"call_start": {
"arguments": {
"business_id": "a0a81c23",
"phone_number": "{{caller_number}}"
}
}
}چونکہ کال کے آغاز پر کوئی شخص کچھ نہیں بھرتا، اس لیے آرگیومنٹس میں ہر مطلوبہ پیرامیٹر کے لیے ایک قدر ہونی چاہیے۔ قدریں اسٹرنگز، نمبرز یا بولینز ہوتی ہیں۔ انہیں سادہ متن کے طور پر محفوظ اور واپس کیا جاتا ہے اور ایجنٹ انہیں دیکھتا ہے، اس لیے API کیز جیسے راز کنکشن کے ہیڈرز میں رکھیں، یہاں نہیں۔ اسٹرنگز یہ پلیس ہولڈرز استعمال کر سکتی ہیں:
| پلیس ہولڈر | قدر |
|---|---|
{{caller_number}} | کال پر موجود دوسرا شخص E.164 فارمیٹ میں، مثلاً +61402122887: آنے والی کال میں کال کرنے والا، جانے والی کال میں جس شخص کو کال کی گئی ہو |
{{caller_number_national}} | اسی ملک کے قومی فارمیٹ میں وہی نمبر، خالی جگہوں کے بغیر، مثلاً 0402122887 |
{{agent_number}} | ایجنٹ کا اپنا نمبر |
یہ کیسے کام کرتا ہے:
- ریکویسٹ وہی ہوتی ہے جو ایجنٹ کے اپنے ٹول کالز بھیجتے ہیں (وہی اینڈپوائنٹ، ہیڈرز، ریکویسٹ فارمیٹ اور دستخط)۔
- ٹول کال شروع ہونے پر شروع ہوتا ہے، اور کسی بھی کنیکٹ ٹون، تعارفی پیغام یا ریکارڈنگ نوٹس کے چلنے کے دوران چلتا ہے۔ خیرمقدمی پیغام اس کے لیے اس وقت سے تقریباً 3 سیکنڈ تک انتظار کرتا ہے۔ سست نتیجہ ایجنٹ کو پہنچتے ہی باقی کال کے لیے دے دیا جاتا ہے۔ جانے والی کال میں یہ کال ملائے جانے پر شروع ہوتا ہے، اس لیے ہر کوشش پر چلتا ہے، ان کوششوں سمیت جن کا کوئی جواب نہیں دیتا۔
- ایسے ایجنٹ میں جہاں کال کرنے والا پہلے بولتا ہے، انتظار کرنے کے لیے کوئی خیرمقدمی پیغام نہیں ہوتا؛ ایجنٹ کو نتیجہ پہنچتے ہی مل جاتا ہے۔
- نتیجہ پوری کال کے لیے ایجنٹ کو سیاق کے طور پر دیا جاتا ہے۔ اپنے prompt میں ایجنٹ کو بتائیں کہ اسے کیسے استعمال کرنا ہے؛ ورنہ اسے بلند آواز سے نہیں پڑھا جاتا۔
- اگر ٹول ناکام ہو جائے یا وقت ختم ہو جائے، تو ایجنٹ کال کرنے والے کو حسب معمول خوش آمدید کہتا ہے اور اس کے بارے میں کچھ نہیں کہتا۔
- ایجنٹ پھر بھی کال میں بعد میں خود ٹول کو کال کر سکتا ہے۔
- یہ فون کالز پر چلتا ہے، جن میں آپ کے فون پر ڈیش بورڈ ٹیسٹ کالز اور AI سیمولیشنز شامل ہیں، جو سیمولیٹ کیے گئے کال کرنے والے کا نمبر آپ کے اینڈپوائنٹ کو بھیجتی ہیں۔ یہ براؤزر بات کریں ٹیسٹس یا ویب ویجیٹ سیشنز میں نہیں چلتا، جن میں کال کرنے والے کا نمبر نہیں ہوتا، ان کالز میں نہیں چلتا جن کا کالر ID پوشیدہ ہو، یا اسٹیپس والے ایجنٹس پر نہیں چلتا۔
- ایک ایجنٹ بیک وقت زیادہ سے زیادہ تین کال-اسٹارٹ ٹولز چلاتا ہے۔
اپنے prompt میں نتیجے کا ذکر کریں تاکہ ایجنٹ کو معلوم ہو کہ اسے کیسے استعمال کرنا ہے، مثلاً: "اگر کال کے آغاز کی تلاش میں کال کرنے والا مل جائے، تو اسے پہلے نام سے خوش آمدید کہیں۔"
بہترین طریقہ کار
واضح وضاحتیں لکھیں
description فیلڈ AI کو یہ سمجھنے میں مدد دیتی ہے کہ ٹول کب استعمال کرنا ہے۔ یہ کیا کرتا ہے اور کب مناسب ہے، اس بارے میں مخصوص رہیں۔
خرابیوں کو خوش اسلوبی سے سنبھالیں
ایسے خرابی کے پیغامات واپس کریں جنہیں AI سمجھ سکے: عمومی 500 خرابیوں کے بجائے {"error": "No slots available for that date"}۔
جوابات مختصر رکھیں
صرف وہی واپس کریں جس کی AI کو گفتگو جاری رکھنے کے لیے ضرورت ہو۔ ٹول کا نتیجہ گفتگو میں رہتا ہے اور ہر اگلی باری میں دوبارہ پڑھا جاتا ہے، اس لیے بڑا نتیجہ باقی کال کے لیے لاگت اور تاخیر بڑھاتا ہے۔ 100,000 حروف سے زیادہ کے نتائج کو ایک پیش منظر تک محدود کر دیا جاتا ہے جسے AI نامکمل سمجھتی ہے، اور بہت طویل کال میں پرانے نتائج حذف ہو سکتے ہیں (AI ٹول کو دوبارہ کال کر سکتی ہے)۔ ایک parameter شامل کریں تاکہ AI ایک وقت میں ایک آئٹم یا زمرہ تلاش کر سکے، اور بڑے حوالہ جاتی مواد، جیسے مینیوز یا کیٹلاگز، کو نالج بیس میں رکھیں۔ ڈیش بورڈ میں ٹیسٹ ریکویسٹ بھیجیں ہر نتیجے کا سائز دکھاتا ہے اور بڑا ہونے پر خبردار کرتا ہے۔
لازمی فیلڈز دانش مندی سے استعمال کریں
فیلڈز کو صرف اسی وقت required نشان زد کریں جب واقعی ضروری ہو۔ ٹول کال کرنے سے پہلے AI صارف سے لازمی معلومات طلب کرے گا۔
متعلقہ
اینڈپوائنٹ متعین کیے بغیر پلیٹ فارم کے زیرِ انتظام کال ایکشنز کے لیے prompt لکھیں۔
HubSpot، Salesforce، Google Calendar، Google Sheets، اور Cal.com کے لیے پلیٹ فارم کے زیرِ انتظام ٹولز — کسی اینڈپوائنٹ کی ضرورت نہیں۔
ایک MCP سرور منسلک کریں اور ایجنٹ کو اس کے ٹولز کال کرنے دیں۔
دوبارہ استعمال کے قابل REST انٹیگریشنز جنہیں آپ ایجنٹس کے ساتھ منسلک کر سکتے ہیں۔
ویب ہکس اور ٹول کالز کے لیے ایک تصدیقی معاون۔