---
title: "ٹول انٹیگریشن (API) بنائیں"
description: "اپنے ایجنٹ کو گفتگو کے دوران آپ کی APIs کال کرنے دیں — ڈیٹابیس تلاش کریں، ٹکٹ بنائیں، آرڈر تلاش کریں۔"
---
ایک **ٹول انٹیگریشن** ایک دوبارہ استعمال ہونے والا HTTP اینڈ پوائنٹ ہے جسے ایک ایجنٹ
کال کے دوران استعمال کر سکتا ہے۔ آپ ThunderPhone کو ٹول کی JSON-schema وضاحت
اور ایک اینڈ پوائنٹ URL دیتے ہیں؛ ایجنٹ گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ اسے کب
کال کرنا ہے، اور ThunderPhone اپنے سرورز سے بیرونی HTTP درخواست کرتا ہے اور جواب
ایجنٹ کو واپس کرتا ہے۔
اس API کے بغیر ڈیش بورڈ ٹول کی زیادہ تر ضروریات پوری کرتا ہے: **کنکشنز
→ ایپس** چند OAuth کلکس میں Slack، HubSpot، Salesforce، Google Calendar،
Google Sheets، اور Cal.com کو منسلک کرتا ہے؛ **کنکشنز →
APIs** کسی بھی HTTP API کو ایجنٹ ایکشن میں تبدیل کرتا ہے (ایک cURL کمانڈ
پیسٹ کریں اور ایک AI وزرڈ ٹول کا مسودہ تیار کرتا ہے، جس میں بلٹ اِن
درخواست آزمائیں شامل ہے)؛ اور **کنکشنز → MCP** MCP سرورز شامل کرتا ہے۔
[کنکشنز](/ur/guides/concepts) دیکھیں۔ یہ گائیڈ APIs کے انٹرفیس کے
تحت موجود بنیادی API کے بارے میں ہے۔
یہ گائیڈ ابتدا سے انتہا تک موسم معلوم کرنے والا ٹول بنانے کا طریقہ بتاتی ہے۔
## ٹول کی ساخت
دو حصے:
1. **اسکیما** — ایک OpenAI طرز کی فنکشن ڈیفینیشن
(`{type: "function", function: {name, description, parameters}}`)
جو LLM کو بتاتی ہے کہ ٹول کیا کرتا ہے اور اسے کون سے آرگیومنٹس درکار ہیں۔
2. **اینڈ پوائنٹ** — وہ URL جسے ThunderPhone کے سرورز اس وقت کال کرتے ہیں جب
LLM ٹول استعمال کرنے کا فیصلہ کرتا ہے۔ درخواست JSON POST ہوتی ہے، جس کے
باڈی میں LLM کے منتخب کردہ آرگیومنٹس ہوتے ہیں۔
## 1. اسٹوریج کی حکمت عملی منتخب کریں
ایجنٹ کی `tools` ارے میں ایک یک بار استعمال ہونے والا ٹول شامل کریں۔ آسان ہے، مگر
دوبارہ استعمال نہیں ہو سکتا۔
ٹول کو دوبارہ استعمال ہونے والی [انٹیگریشن](/api-reference/integrations)
کے طور پر محفوظ کریں اور اسے متعدد ایجنٹس سے منسلک کریں۔ ایک سے زیادہ بار
استعمال ہونے والی ہر چیز کے لیے تجویز کردہ ہے۔
یہ گائیڈ محفوظ شدہ انٹیگریشن کا طریقہ استعمال کرتی ہے۔
## 2. انٹیگریشن بنائیں
```bash
curl -X POST https://api.thunderphone.com/v1/integrations \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"display_name": "Weather API",
"spec": {
"type": "function",
"function": {
"name": "get_weather",
"description": "Return the current weather for a zip code.",
"parameters": {
"type": "object",
"properties": {
"zip": { "type": "string", "description": "5-digit US ZIP code" }
},
"required": ["zip"]
}
}
},
"endpoint_url": "https://api.example.com/weather",
"endpoint_method": "GET",
"headers": [
{ "key": "X-Api-Key", "value": "your-provider-key" }
]
}'
```
واپس آنے والی `id` محفوظ کریں (ایک UUID)۔
ٹول اور ہر پیرامیٹر کی `description` پر سنجیدگی سے محنت کریں۔ LLM رن ٹائم پر
ان اسٹرنگز کو استعمال کرکے فیصلہ کرتا ہے کہ ٹول کو کال کرنا ہے یا نہیں اور کیسے
کرنا ہے۔ مبہم وضاحتیں → مبہم ٹول کالز۔
## 3. اینڈ پوائنٹ کو سینڈ باکس میں آزمائیں
انٹیگریشن کو کسی ایجنٹ سے منسلک کرنے سے پہلے، کنیکٹیویٹی کی تصدیق کے لیے
ThunderPhone کے سرورز سے ایک دستخط شدہ درخواست بھیجیں:
```bash
curl -X POST https://api.thunderphone.com/v1/integrations/test-request \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"url": "https://api.example.com/weather?zip=94110",
"method": "GET",
"headers": { "X-Api-Key": "your-provider-key" }
}'
```
```json Response
{
"ok": true,
"status": 200,
"elapsed_ms": 187,
"response_headers": { "content-type": "application/json" },
"response_preview": "{\"temperature_f\": 64, ...}"
}
```
یہ ٹیسٹ ThunderPhone کے SSRF حفاظتی بندوبست کو بھی مضبوط کرتا ہے — localhost یا
نجی IP رینجز کی درخواستیں `400 code=url_not_allowed` واپس کرتی ہیں۔
## 4. انٹیگریشن کو ایجنٹ سے لنک کریں
ایجنٹ بناتے یا اپ ڈیٹ کرتے وقت `integration_ids` کے ذریعے منسلک کریں:
```bash
curl -X PATCH https://api.thunderphone.com/v1/agents/12 \
-H "Authorization: Bearer sk_live_YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"integration_ids": ["f9b5a1a4-..."]
}'
```
آپ ایک ایجنٹ سے متعدد انٹیگریشنز لنک کر سکتے ہیں۔ ایجنٹ کا prompt
انہیں نام کے ذریعے حوالہ دے سکتا ہے — "جب کالر حالات کے بارے میں پوچھے تو
`get_weather` استعمال کریں" — یا schema کی تفصیلات سے انہیں
ضمنی طور پر دریافت کر سکتا ہے۔
## 5. اینڈ پوائنٹ نافذ کریں
جب ایجنٹ ٹول کو استعمال کرتا ہے، ThunderPhone آپ کے
`endpoint_url` پر دستخط شدہ POST بھیجتا ہے:
```
POST /weather HTTP/1.1
Host: api.example.com
X-Api-Key: your-provider-key
X-ThunderPhone-Signature:
X-ThunderPhone-Call-ID: 987654321
Content-Type: application/json
{"zip": "94110"}
```
آپ کا سرور JSON کے ساتھ جواب دیتا ہے، جو LLM کو واپس بھیج دیا جاتا ہے:
```json
{"temperature_f": 64, "condition": "Partly cloudy", "wind_mph": 8}
```
LLM اس جواب کو قبول کرتا ہے اور کالر کو انسانی انداز میں خلاصہ سناتا ہے۔
دستخط آپ کے webhook اینڈ پوائنٹ والے اسی `secret` کو استعمال کرتے ہوئے خام
ریکویسٹ باڈی پر تیار کیا جاتا ہے۔ **اس کی تصدیق کریں** — ٹول اینڈ پوائنٹس
انٹرنیٹ پر قابل رسائی ہوتے ہیں اور webhooks جیسے ہی جعل سازی کے خدشات سے
مشروط ہوتے ہیں۔ دیکھیں
[webhook دستخطوں کی تصدیق کریں](/ur/guides/verify-webhook-signatures)۔
## 6. لوپ کی جانچ کریں
ایجنٹ کے خلاف ایک [مائیک سیشن](/api-reference/mic-sessions) چلائیں
اور وہ سوال پوچھیں جسے آپ کا ٹول ہینڈل کرتا ہے ("94110 میں موسم
کیسا ہے؟")۔ کال کا transcript مکمل رفت و آمد دکھاتا ہے:
```json
{
"call_id": 987654321,
"transcripts": [
{ "role": "user",
"content": "What's the weather in 94110?" },
{ "role": "tool_call",
"content": "{\"tool_call\": \"get_weather\", \"arguments\": {\"zip\": \"94110\"}}" },
{ "role": "tool_response",
"content": "{\"tool_name\": \"get_weather\", \"response\": {\"temperature_f\": 64, \"condition\": \"Partly cloudy\"}}" },
{ "role": "agent",
"content": "It's 64 degrees and partly cloudy." }
]
}
```
آپ اسے
[`GET /v1/calls/{call_id}/transcript`](/api-reference/calls#get-transcript) کے ذریعے حاصل کر سکتے ہیں؛
خام ایونٹ اسٹریم، جس میں ہر اندراج کا وقت اور آڈیو آفسیٹس شامل ہیں،
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history) پر موجود ہے۔
## عام مسائل
LLM ٹول کی تفصیل کی بنیاد پر فیصلہ کرتا ہے۔ اگر کالر کا
سوال تفصیل سے مطابقت نہیں رکھتا، تو ماڈل ٹول کو استعمال نہیں کرے گا۔
تفصیل کو زیادہ واضح بنائیں، عام مترادفات اور جملہ بندی شامل کریں، یا
ایجنٹ کے prompt میں اس کا واضح ذکر کریں ("جب کالر موسم کے بارے میں پوچھے،
تو `get_weather` استعمال کریں۔")۔
6 kB سے بڑے جوابات transcript پیش منظر میں مختصر کر دیے جاتے ہیں۔ صرف
وہی فیلڈز واپس کریں جن کی LLM کو ضرورت ہے — اپنی پوری قطار نہیں۔
ٹول اینڈ پوائنٹس کا طے شدہ ٹائم آؤٹ 10 سیکنڈ ہے۔ اگر آپ کو زیادہ وقت درکار ہو،
تو اسے غیر ہم وقت انداز میں ہینڈل کریں: `{"status": "pending", "request_id": "..."}`
واپس کریں اور نتیجہ الگ ٹول کال کے ذریعے ظاہر کریں۔
ہر انٹیگریشن `PATCH` ایک نیا revision بناتا ہے۔ یہ دیکھنے کے لیے کہ کس نے
کیا تبدیل کیا،
[`GET /v1/integrations/{id}/versions`](/api-reference/integrations#version-history)
کا جائزہ لیں۔ اگر آپ کسی ٹول کا schema خراب کر دیتے ہیں، تو آپ پرانے snapshot
کو دوبارہ PATCH کر کے دستی طور پر واپس جا سکتے ہیں۔
---
## اگلے مراحل
CRUD، ٹرانسفر، ورژن ہسٹری۔
مکمل JSON اسکیما گرامر اور سائن شدہ اینڈپوائنٹ معاہدہ۔
ٹول اینڈپوائنٹس پر ویب ہک دستخط کے پیٹرن کا اطلاق کریں۔
ٹول کال کے مکمل راؤنڈ ٹرپ کا جائزہ لیں۔