--- title: "فنکشن ٹولز" description: "اپنے AI ایجنٹس کو فنکشن ٹولز دیں جو گفتگو کے دوران بیرونی APIs کو کال کریں — کسٹمر ڈیٹا حاصل کریں، اپائنٹمنٹس بک کریں، ریکارڈز اپ ڈیٹ کریں — ٹائپ شدہ پیرامیٹرز کے ساتھ۔" --- فنکشن ٹولز آپ کے AI ایجنٹس کو فون کالز کے دوران بیرونی APIs استعمال کرنے کی اجازت دیتے ہیں۔ انہیں کسٹمر کا ڈیٹا تلاش کرنے، دستیابی چیک کرنے، اپائنٹمنٹس بُک کرنے، یا آپ کے بیک اینڈ کی معاونت یافتہ کوئی بھی کارروائی انجام دینے کے لیے استعمال کریں۔ ## یہ کیسے کام کرتا ہے 1. آپ ایک schema کے ساتھ ٹولز کی تعریف کرتے ہیں (ٹول کن arguments کو قبول کرتا ہے) 2. آپ `endpoint` کنفیگریشن فراہم کرتے ہیں (جہاں ThunderPhone آپ کی API کو کال کرتا ہے) — یا اپنی org webhook پر ٹول کالز وصول کرنے کے لیے اسے شامل نہ کریں 3. کال کے دوران، AI گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ ٹول کب استعمال کرنا ہے 4. ThunderPhone ٹول arguments کے ساتھ آپ کے endpoint کو کال کرتا ہے 5. گفتگو جاری رکھنے کے لیے آپ کا API جواب AI کو واپس فراہم کیا جاتا ہے | صلاحیت | کہاں چلتی ہے | سیٹ اپ | | --- | --- | --- | | [بلٹ اِن ٹولز](/ur/guides/built-in-tools) | ThunderPhone | prompt ہدایات؛ کچھ ٹولز کو ایجنٹ کی سیٹنگ بھی درکار ہوتی ہے | | [ایپ کنکشنز](/ur/guides/connect-apps) | ThunderPhone اور منسلک فراہم کنندہ | اکاؤنٹ منسلک کریں اور منظور شدہ کارروائیاں شامل کریں | | [API کنکشنز](/ur/guides/api-connections) اور فنکشن ٹولز | آپ کی HTTP API | endpoint اور schema کی تعریف کریں، یا webhook کے ذریعے فنکشن کالز وصول کریں | | [MCP سرورز](/ur/guides/mcp-servers) | ایک ریموٹ MCP سرور | سرور شامل کریں، اس کے ٹولز دریافت کریں، اور اسے ایجنٹ کے ساتھ منسلک کریں | --- ## ٹول Schema ہر ٹول اس ساخت کی پیروی کرتا ہے: ```json { "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`) | ### فنکشن کی تعریف | فیلڈ | قسم | ضروری | وضاحت | |-------|------|----------|-------------| | `name` | سٹرنگ | ہاں | ٹول کے لیے منفرد شناخت کنندہ | | `description` | سٹرنگ | ہاں | AI کو بتاتا ہے کہ یہ ٹول کب استعمال کرنا ہے | | `parameters` | آبجیکٹ | ہاں | ٹول arguments کے لیے JSON Schema | ### Endpoint کنفیگریشن | فیلڈ | قسم | ضروری | وضاحت | |-------|------|----------|-------------| | `url` | سٹرنگ | ہاں | آپ کا API endpoint URL | | `method` | سٹرنگ | نہیں | HTTP طریقہ (ڈیفالٹ: `POST`) | | `headers` | آبجیکٹ | نہیں | شامل کرنے کے لیے حسب ضرورت headers | `endpoint` کنفیگریشن AI ماڈل کو **نہیں** بھیجی جاتی—یہ صرف ThunderPhone کی جانب سے ٹول کال انجام دینے کے لیے استعمال ہوتی ہے۔ --- ## استعمال کے دو راستے آپ کے سرور کو کون سی درخواست موصول ہوتی ہے، یہ اس بات پر منحصر ہے کہ ٹول کے پاس `endpoint` موجود ہے یا نہیں: | | `endpoint` **کے ساتھ** ٹول | `endpoint` **کے بغیر** ٹول | |---|---|---| | درخواست کہاں جاتی ہے | براہ راست `endpoint.url` پر | آپ کی org کے [legacy webhook URL](/api-reference/organizations#legacy-single-url-webhook) پر | | باڈی | **صرف ٹول arguments** | `telephony.tool` / `web.tool` envelope | | Headers | آپ کے `endpoint.headers`، `X-ThunderPhone-Call-ID` اور `X-ThunderPhone-Signature` | `Content-Type` اور `X-ThunderPhone-Signature` | | Signing key | org webhook secret | org webhook secret | دونوں راستے **بلاکنگ** ہیں — AI نتیجے کے لیے جملے کے درمیان انتظار کر رہا ہوتا ہے۔ ڈیفالٹ timeout **20 سیکنڈ** ہے؛ زیادہ طویل عمل درآمد کی اجازت دینے کے لیے ٹول کا اوپری سطح کا `timeout` سیٹ کریں، پلیٹ فارم کی **180 سیکنڈ** کی زیادہ سے زیادہ حد تک۔ handlers کو تیز رکھیں۔ دونوں کا امتزاج درست ہے: ایسی کال پر جس کی org کے پاس webhook URL ہو، `endpoint` والے ٹولز کو براہ راست کال کیا جاتا ہے اور باقی webhook پر واپس چلے جاتے ہیں۔ ## براہِ راست endpoint کالز جب AI کسی ایسے ٹول کو استعمال کرتا ہے جس میں `endpoint` ہو، تو ThunderPhone آپ کے URL پر ایک درخواست بھیجتا ہے: ### درخواست کے ہیڈرز ```http POST /appointments/search HTTP/1.1 Host: api.example.com Content-Type: application/json X-ThunderPhone-Signature: abc123... X-ThunderPhone-Call-ID: 987654321 X-Api-Key: your-api-key ``` آپ کے `endpoint.headers` کے حسبِ ضرورت ہیڈرز ہمیشہ جوں کے توں شامل کیے جاتے ہیں، اور اس کے ساتھ ThunderPhone کے نام والے دو ہیڈرز بھی شامل ہوتے ہیں: - `X-ThunderPhone-Signature` — درخواست کے عین body بائٹس کا HMAC-SHA256، جس کے لیے آپ کا **org webhook secret** کلید کے طور پر استعمال ہوتا ہے - `X-ThunderPhone-Call-ID` — موجودہ کال ID `Content-Type: application/json` سیٹ کیا جاتا ہے، جب تک کہ آپ کے `endpoint.headers` اسے اووررائیڈ نہ کر دیں — حسبِ ضرورت `Content-Type` کو ترجیح حاصل ہوتی ہے۔ دستخط کے لیے org سطح کا webhook secret استعمال ہوتا ہے جو [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) سے حاصل ہوتا ہے۔ اگر آپ کے org نے کبھی legacy webhook کنفیگر نہیں کیا، تو کوئی secret موجود نہیں ہوتا اور ٹول کالز میں **صرف** `X-ThunderPhone-Call-ID` شامل ہوتا ہے — ایسا handler جو دستخط نہ ہونے پر فوری ناکام ہو جائے، انہیں مسترد کر دے گا۔ secret حاصل کرنے کے لیے legacy webhook کنفیگر کریں، یا اپنا مشترکہ secret `endpoint.headers` میں شامل کریں۔ ### درخواست کی باڈی `POST` / `PUT` / `PATCH` کے لیے، body میں **صرف** ٹول کے arguments ہوتے ہیں (کوئی wrapper نہیں)، اور انہیں canonical انداز میں serialize کیا جاتا ہے (ترتیب شدہ keys، مختصر separators): ```json {"date":"2025-01-02","service":"consultation"} ``` `GET` / `DELETE` کے لیے، arguments **query parameters** کے طور پر بھیجے جاتے ہیں اور body خالی ہوتی ہے — اس صورت میں دستخط خالی byte string پر تیار کیا جاتا ہے۔ دیکھیں [webhook دستخط کی تصدیق کریں](/ur/guides/verify-webhook-signatures)۔ ### جواب ٹول کے نتیجے کے ساتھ JSON جواب واپس کریں: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` جواب کو فارمیٹ کر کے AI کو گفتگو جاری رکھنے کے لیے فراہم کیا جاتا ہے۔ غیر JSON جوابات کو `{"data": ""}` کی صورت میں wrap کیا جاتا ہے؛ timeout اور connection کی ناکامیوں کو AI کو errors کے طور پر رپورٹ کیا جاتا ہے، تاکہ ایجنٹ معذرت کر کے گفتگو آگے بڑھا سکے، رکے نہیں۔ ## Webhook موڈ dispatch وہ ٹولز جن میں `endpoint` **نہیں** ہوتا، آپ کے org کے legacy webhook URL پر دستخط شدہ `telephony.tool` (فون کالز) یا `web.tool` (web کالز) درخواست کے طور پر dispatch کیے جاتے ہیں۔ [آڈٹ اطلاعات](/ur/webhooks/events) کے برعکس، جو execution کے بعد webhook endpoints پر پہنچائی جاتی ہیں، یہ درخواست **خود** execution ہے — آپ کا HTTP جواب ہی ٹول کا نتیجہ ہوتا ہے۔ ```json { "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 کے طور پر واپس کریں — یہی response contract براہِ راست endpoint کالز کے لیے بھی ہے۔ درخواست پر org webhook secret کے ذریعے raw body کے اوپر دستخط کیے جاتے ہیں، بالکل ہر دوسرے webhook کی طرح۔ سبسکرائب کیے گئے [webhook endpoints](/ur/webhooks/endpoints) کو اضافی طور پر ہر ٹول کے execute ہونے کے **بعد** ایک non-blocking `telephony.tool` / `web.tool` اطلاع موصول ہوتی ہے (اس سے قطع نظر کہ اسے کس راستے سے چلایا گیا)، جس میں ٹول کا جواب بھی شامل ہوتا ہے — آڈٹ ٹریلز کے لیے مفید۔ دیکھیں [واقعات کا کیٹلاگ](/ur/webhooks/events)۔ --- ## دستخط کی تصدیق براہِ راست ٹول کالز پر ویب ہُکس کی طرح ہی دستخط کیے جاتے ہیں: - عین درخواست باڈی بائٹس پر HMAC-SHA256 (کینونیکل JSON — ترتیب دی گئی کلیدیں، اضافی وائٹ اسپیس کے بغیر) - آپ کے تنظیم کے ویب ہُک سیکرٹ کے ذریعے کلید شدہ - `GET` / `DELETE` ٹولز خالی بائٹ اسٹرنگ پر دستخط کرتے ہیں ```python Python import hmac import hashlib def verify_tool_call(body: bytes, signature: str, secret: str) -> bool: expected = hmac.new(secret.encode(), body, hashlib.sha256).hexdigest() return hmac.compare_digest(expected, signature) @app.post("/appointments/search") async def search_appointments(request: Request): body = await request.body() signature = request.headers.get("X-ThunderPhone-Signature", "") if not verify_tool_call(body, signature, WEBHOOK_SECRET): 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} ``` ```javascript Node.js app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => { const signature = req.headers['x-thunderphone-signature'] || ''; const expected = crypto .createHmac('sha256', WEBHOOK_SECRET) .update(req.body) .digest('hex'); if (!signature || signature.length !== expected.length || !crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature))) { 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 }); }); ``` مکمل نسخے — بشمول خالی باڈی کی صورت اور سیکرٹ نہ ہونے سے متعلق تنبیہ — [ویب ہُک دستخط کی تصدیق کریں](/ur/guides/verify-webhook-signatures) میں موجود ہیں۔ --- ## مثال: مکمل بکنگ فلو یہ مکمل اپائنٹمنٹ بکنگ سسٹم کے لیے ٹولز کا ایک مجموعہ ہے: ```json { "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" } } } ] } ``` --- ## بہترین طریقہ کار `description` فیلڈ AI کو یہ سمجھنے میں مدد دیتی ہے کہ ٹول **کب** استعمال کرنا ہے۔ یہ کیا کرتا ہے اور کب مناسب ہے، اس بارے میں مخصوص رہیں۔ ایسے خرابی کے پیغامات واپس کریں جنہیں AI سمجھ سکے: عمومی 500 خرابیوں کے بجائے `{"error": "No slots available for that date"}`۔ گفتگو جاری رکھنے کے لیے AI کو صرف وہی واپس کریں جس کی اسے ضرورت ہو۔ بڑے payloads جواب کے وقت کو سست کر دیتے ہیں۔ فیلڈز کو صرف اسی وقت `required` نشان زد کریں جب واقعی ضروری ہو۔ ٹول کال کرنے سے پہلے AI صارف سے لازمی معلومات طلب کرے گا۔ --- ## متعلقہ endpoint متعین کیے بغیر پلیٹ فارم کے زیرِ انتظام کال ایکشنز کے لیے prompt دیں۔ HubSpot، Salesforce، Slack، Google Calendar، Google Sheets، اور Cal.com کے لیے پلیٹ فارم کے زیرِ انتظام ٹولز — endpoint درکار نہیں۔ MCP سرور منسلک کریں اور ایجنٹ کو اس کے ٹولز کال کرنے دیں۔ دوبارہ استعمال کے قابل REST انضمامات جنہیں آپ ایجنٹس کے ساتھ منسلک کر سکتے ہیں۔ webhooks اور ٹول کالز کے لیے ایک تصدیقی helper۔