فنکشن ٹولز

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

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

1. آپ ایک اسکیما کے ساتھ ٹولز کی وضاحت کرتے ہیں (ٹول کن آرگومنٹس کو قبول کرتا ہے)
2. آپ ایک endpoint کنفیگریشن فراہم کرتے ہیں (جہاں ThunderPhone آپ کے API کو کال کرتا ہے) — یا اپنے آرگ ویب ہک پر ٹول کالز موصول کرنے کے لیے اسے خالی چھوڑ دیتے ہیں
3. کال کے دوران، AI گفتگو کی بنیاد پر فیصلہ کرتا ہے کہ ٹول کب استعمال کرنا ہے
4. ThunderPhone ٹول آرگومنٹس کے ساتھ آپ کے اینڈ پوائنٹ کو کال کرتا ہے
5. گفتگو جاری رکھنے کے لیے آپ کے API کا جواب AI کو واپس فراہم کیا جاتا ہے

ٹول اسکیما

ہر ٹول اس ساخت کی پیروی کرتا ہے:

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

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

اینڈ پوائنٹ کنفیگریشن

کال کرنے کے دو طریقے

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

دونوں طریقے بلاکنگ ہیں — AI نتیجے کے لیے جملے کے درمیان انتظار کر رہا ہوتا ہے — اور ان کا ٹائم آؤٹ 20 سیکنڈ ہے۔ ہینڈلرز کو تیز رکھیں۔ دونوں کا امتزاج بھی درست ہے: ایسی کال میں جس کے آرگ کے پاس ویب ہک URL ہو، endpoint والے ٹولز کو براہ راست کال کیا جاتا ہے اور باقی ویب ہک پر واپس چلے جاتے ہیں۔

براہِ راست 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 — عین درخواست باڈی کے بائٹس کا HMAC-SHA256، جس کی کلید آپ کی ادارے کی ویب ہک خفیہ کلید ہے
• X-ThunderPhone-Call-ID — موجودہ کال ID

Content-Type: application/json مقرر ہوتا ہے، جب تک آپ کے endpoint.headers اسے اووررائیڈ نہ کریں — حسبِ ضرورت Content-Type کو ترجیح حاصل ہوتی ہے۔

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

POST / PUT / PATCH کے لیے، باڈی میں صرف ٹول کے آرگیومنٹس ہوتے ہیں (کوئی ریپر نہیں)، جو معیاری انداز میں سیریلائز کیے جاتے ہیں (ترتیب شدہ کلیدیں، مختصر جداکار):

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

GET / DELETE کے لیے، آرگیومنٹس کوئری پیرامیٹرز کے طور پر بھیجے جاتے ہیں اور باڈی خالی ہوتی ہے — اس صورت میں دستخط خالی بائٹ اسٹرنگ پر حساب کیا جاتا ہے۔ ملاحظہ کریں ویب ہک دستخطوں کی تصدیق کریں۔

جواب

ٹول کے نتیجے کے ساتھ ایک JSON جواب واپس کریں:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

جواب کو فارمیٹ کر کے گفتگو جاری رکھنے کے لیے AI کو فراہم کیا جاتا ہے۔ غیر JSON جوابات کو {"data": "<text>"} کے طور پر ریپ کیا جاتا ہے؛ ٹائم آؤٹس اور کنکشن کی ناکامیاں AI کو غلطیوں کے طور پر رپورٹ کی جاتی ہیں، تاکہ ایجنٹ معذرت کر کے رکے بغیر آگے بڑھ سکے۔

ویب ہک موڈ ڈسپیچ

ایسے ٹولز جن میں endpoint نہ ہو، انہیں آپ کے ادارے کے لیگیسی ویب ہک URL پر دستخط شدہ telephony.tool (فون کالز) یا web.tool (ویب کالز) درخواست کے طور پر ڈسپیچ کیا جاتا ہے۔ عمل درآمد کے بعد ویب ہک endpoints پر پہنچنے والی آڈٹ اطلاعات کے برعکس، یہ درخواست ہی عمل درآمد ہے — آپ کا 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 کالز والا جواب معاہدہ ہے۔ ہر دوسرے ویب ہک کی طرح، درخواست کی خام باڈی پر ادارے کی ویب ہک خفیہ کلید کے ذریعے دستخط کیے جاتے ہیں۔

دستخط کی توثیق

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

• عین درخواست-باڈی بائٹس پر HMAC-SHA256 (کینونیکل JSON — ترتیب شدہ کیز، اضافی خالی جگہ کے بغیر)
• آپ کے org ویب ہک سیکرٹ کے ذریعے کلیدبند
• 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" }
      }
    }
  ]
}

بہترین طریقے

متعلقہ