فنکشن ٹولز

اپنے AI ایجنٹس کو فنکشن ٹولز دیں جو گفتگو کے دوران بیرونی APIs کو کال کریں — کسٹمر ڈیٹا حاصل کریں، اپائنٹمنٹس بک کریں، ریکارڈز اپ ڈیٹ کریں — ٹائپ شدہ پیرامیٹرز کے ساتھ۔

فنکشن ٹولز آپ کے AI ایجنٹس کو فون کالز کے دوران بیرونی APIs استعمال کرنے کی اجازت دیتے ہیں۔ انہیں کسٹمر کا ڈیٹا تلاش کرنے، دستیابی چیک کرنے، اپائنٹمنٹس بُک کرنے، یا آپ کے بیک اینڈ کی معاونت یافتہ کوئی بھی کارروائی انجام دینے کے لیے استعمال کریں۔

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

1. آپ ایک schema کے ساتھ ٹولز کی تعریف کرتے ہیں (ٹول کن arguments کو قبول کرتا ہے)
2. آپ endpoint کنفیگریشن فراہم کرتے ہیں (جہاں ThunderPhone آپ کی API کو کال کرتا ہے) — یا اپنی org webhook پر ٹول کالز وصول کرنے کے لیے اسے شامل نہ کریں
3. کال کے دوران، AI گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ ٹول کب استعمال کرنا ہے
4. ThunderPhone ٹول arguments کے ساتھ آپ کے endpoint کو کال کرتا ہے
5. گفتگو جاری رکھنے کے لیے آپ کا API جواب AI کو واپس فراہم کیا جاتا ہے

ٹول 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
}

ٹول کنفیگریشن#

فنکشن کی تعریف#

Endpoint کنفیگریشن#

استعمال کے دو راستے#

آپ کے سرور کو کون سی درخواست موصول ہوتی ہے، یہ اس بات پر منحصر ہے کہ ٹول کے پاس endpoint موجود ہے یا نہیں:

دونوں راستے بلاکنگ ہیں — AI نتیجے کے لیے جملے کے درمیان انتظار کر رہا ہوتا ہے۔ ڈیفالٹ timeout 20 سیکنڈ ہے؛ زیادہ طویل عمل درآمد کی اجازت دینے کے لیے ٹول کا اوپری سطح کا timeout سیٹ کریں، پلیٹ فارم کی 180 سیکنڈ کی زیادہ سے زیادہ حد تک۔ handlers کو تیز رکھیں۔ دونوں کا امتزاج درست ہے: ایسی کال پر جس کی org کے پاس webhook URL ہو، endpoint والے ٹولز کو براہ راست کال کیا جاتا ہے اور باقی webhook پر واپس چلے جاتے ہیں۔

براہِ راست endpoint کالز#

جب AI کسی ایسے ٹول کو استعمال کرتا ہے جس میں endpoint ہو، تو ThunderPhone آپ کے URL پر ایک درخواست بھیجتا ہے:

درخواست کے ہیڈرز#

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 کو ترجیح حاصل ہوتی ہے۔

درخواست کی باڈی#

POST / PUT / PATCH کے لیے، body میں صرف ٹول کے arguments ہوتے ہیں (کوئی wrapper نہیں)، اور انہیں canonical انداز میں serialize کیا جاتا ہے (ترتیب شدہ keys، مختصر separators):

{"date":"2025-01-02","service":"consultation"}

GET / DELETE کے لیے، arguments query parameters کے طور پر بھیجے جاتے ہیں اور body خالی ہوتی ہے — اس صورت میں دستخط خالی byte string پر تیار کیا جاتا ہے۔ دیکھیں webhook دستخط کی تصدیق کریں۔

جواب#

ٹول کے نتیجے کے ساتھ 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 کے طور پر واپس کریں — یہی response contract براہِ راست endpoint کالز کے لیے بھی ہے۔ درخواست پر org webhook secret کے ذریعے raw body کے اوپر دستخط کیے جاتے ہیں، بالکل ہر دوسرے webhook کی طرح۔

دستخط کی تصدیق#

براہِ راست ٹول کالز پر ویب ہُکس کی طرح ہی دستخط کیے جاتے ہیں:

• عین درخواست باڈی بائٹس پر HMAC-SHA256 (کینونیکل JSON — ترتیب دی گئی کلیدیں، اضافی وائٹ اسپیس کے بغیر)
• آپ کے تنظیم کے ویب ہُک سیکرٹ کے ذریعے کلید شدہ
• GET / DELETE ٹولز خالی بائٹ اسٹرنگ پر دستخط کرتے ہیں

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}

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 });
});

مکمل نسخے — بشمول خالی باڈی کی صورت اور سیکرٹ نہ ہونے سے متعلق تنبیہ — ویب ہُک دستخط کی تصدیق کریں میں موجود ہیں۔

مثال: مکمل بکنگ فلو#

یہ مکمل اپائنٹمنٹ بکنگ سسٹم کے لیے ٹولز کا ایک مجموعہ ہے:

{
  "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" }
      }
    }
  ]
}

بہترین طریقہ کار#

متعلقہ#