Function Tools

फ़ंक्शन टूल्स

अपने AI एजेंट्स को फ़ंक्शन टूल्स दें जो बातचीत के बीच में बाहरी APIs को कॉल करें — कस्टमर डेटा प्राप्त करें, अपॉइंटमेंट बुक करें, रिकॉर्ड्स अपडेट करें — टाइप्ड पैरामीटर्स के साथ।

फ़ंक्शन टूल आपके AI फोन एजेंटों को फ़ोन कॉल के दौरान बाहरी API इनवोक करने देते हैं। इनका उपयोग ग्राहक डेटा देखने, उपलब्धता जांचने, अपॉइंटमेंट बुक करने या आपके बैकएंड द्वारा समर्थित कोई भी कार्रवाई करने के लिए करें।

यह कैसे काम करता है#

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"
    }
  },
  "timeout": 120
}

टूल कॉन्फ़िगरेशन#

फ़ंक्शन परिभाषा#

एंडपॉइंट कॉन्फ़िगरेशन#

इनवोकेशन के दो पथ#

आपके सर्वर को कौन सा रिक्वेस्ट मिलता है, यह इस पर निर्भर करता है कि टूल में endpoint है या नहीं:

दोनों पथ ब्लॉकिंग हैं — AI रिज़ल्ट के लिए वाक्य के बीच में प्रतीक्षा कर रहा है। डिफ़ॉल्ट टाइमआउट 20 सेकंड है; लंबा एक्ज़ीक्यूशन अनुमत करने के लिए टूल का टॉप-लेवल timeout सेट करें, अधिकतम 180 सेकंड प्लेटफ़ॉर्म सीमा तक। हैंडलर तेज़ रखें। दोनों का मिश्रण ठीक है: जिस कॉल के संगठन में वेबहुक URL है, उस पर 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 (वेब कॉल) रिक्वेस्ट के रूप में डिस्पैच होते हैं। एक्जीक्यूशन के बाद वेबहुक एंडपॉइंट्स पर डिलीवर होने वाली ऑडिट नोटिफिकेशन्स के विपरीत, यह रिक्वेस्ट ही एक्जीक्यूशन है — आपका 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 के रूप में रिस्पॉन्ड करें — प्रत्यक्ष एंडपॉइंट कॉल के समान रिस्पॉन्स कॉन्ट्रैक्ट। हर दूसरे वेबहुक की तरह, रिक्वेस्ट को रॉ बॉडी पर संगठन वेबहुक सीक्रेट से साइन किया जाता है।

सिग्नेचर सत्यापन#

डायरेक्ट टूल कॉल को वेबहुक की तरह ही साइन किया जाता है:

• सटीक रिक्वेस्ट-बॉडी बाइट्स पर 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" }
      }
    }
  ]
}

सर्वोत्तम प्रथाएँ#

संबंधित#