फंक्शन टूल्स

तुमच्या AI एजंटना संभाषणादरम्यान बाह्य API कॉल करणारी फंक्शन टूल्स द्या — ग्राहक डेटा मिळवा, अपॉइंटमेंट बुक करा, नोंदी अपडेट करा — टाइप केलेल्या पॅरामीटर्ससह.

फंक्शन टूल्स तुमच्या 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 असलेल्या टूल्सना थेट कॉल केला जातो आणि उर्वरित वेबहुककडे परत जातात.

थेट 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, तुमच्या संस्थेच्या webhook सीक्रेटने की केलेला
• X-ThunderPhone-Call-ID — सध्याचा कॉल ID

तुमचे endpoint.headers ते ओव्हरराइड करत नसल्यास Content-Type: application/json सेट केले जाते — कस्टम Content-Type ला प्राधान्य मिळते.

विनंती बॉडी#

POST / PUT / PATCH साठी, बॉडीमध्ये फक्त टूलचे आर्ग्युमेंट्स असतात (कोणतेही रॅपर नसते), कॅनॉनिकली सिरिअलाइझ केलेले (सॉर्ट केलेल्या कीज, कॉम्पॅक्ट सेपरेटर्स):

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

GET / DELETE साठी, आर्ग्युमेंट्स क्वेरी पॅरामीटर्स म्हणून पाठवले जातात आणि बॉडी रिकामी असते — त्यानंतर सिग्नेचर रिकाम्या बाइट स्ट्रिंगवर कॅल्क्युलेट केले जाते. webhook सिग्नेचर्स सत्यापित करा पहा.

प्रतिसाद#

टूलच्या निकालासह JSON प्रतिसाद परत करा:

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

संभाषण सुरू ठेवण्यासाठी प्रतिसाद फॉरमॅट करून AI ला दिला जातो. JSON नसलेले प्रतिसाद {"data": "<text>"} मध्ये रॅप केले जातात; टाइमआउट्स आणि कनेक्शन अयशस्वी होणे AI ला त्रुटी म्हणून कळवले जाते, त्यामुळे एजंट थांबून राहण्याऐवजी माफी मागून पुढे जाऊ शकतो.

Webhook-मोड डिस्पॅच#

endpoint नसलेली टूल्स तुमच्या संस्थेच्या लेगसी webhook URL वर साइन केलेली telephony.tool (फोन कॉल्स) किंवा web.tool (वेब कॉल्स) विनंती म्हणून डिस्पॅच केली जातात. एक्झिक्यूशननंतर webhook 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 कॉल्सप्रमाणेच प्रतिसाद करार लागू होतो. इतर प्रत्येक webhook प्रमाणेच, विनंतीला रॉ बॉडीवर संस्थेच्या 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" }
      }
    }
  ]
}

सर्वोत्तम पद्धती#

संबंधित#