फंक्शन टूल्स

फंक्शन टूल्स तुमच्या 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"
    }
  }
}

फंक्शनची व्याख्या

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

वापराचे दोन मार्ग

तुमच्या सर्व्हरला कोणती विनंती मिळते हे टूलकडे endpoint आहे की नाही यावर अवलंबून असते:

दोन्ही मार्ग ब्लॉकिंग आहेत — निकालासाठी AI वाक्याच्या मधोमध थांबलेली असते — आणि टाइमआउट 20 s आहे. हँडलर्स जलद ठेवा. मिश्र वापरही शक्य आहे: ज्या कॉलच्या संस्थेकडे वेबहुक 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 — सध्याचा कॉल आयडी

तुमचे endpoint.headers ते ओव्हरराइड करत नसल्यास Content-Type: application/json सेट केले जाते — सानुकूल 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 मध्ये प्रतिसाद द्या — थेट एंडपॉइंट कॉल्सप्रमाणेच प्रतिसाद करार लागू होतो. इतर प्रत्येक वेबहुकप्रमाणेच ही विनंती रॉ बॉडीवर संस्थेच्या वेबहुक सीक्रेटने साइन केलेली असते.

स्वाक्षरी पडताळणी

थेट टूल कॉलवर webhooks प्रमाणेच स्वाक्षरी केली जाते:

• अचूक request-body bytes वर HMAC-SHA256 (canonical JSON — क्रमबद्ध की, अतिरिक्त whitespace नाही)
• तुमच्या संस्थेच्या webhook secret चा वापर करून
• GET / DELETE टूल रिकाम्या byte string वर स्वाक्षरी करतात

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

रिकामा body असलेले प्रकरण आणि secret नसल्यासंबंधीची सूचना यांसह संपूर्ण कृती webhook स्वाक्षऱ्या पडताळा मध्ये आहेत.

उदाहरण: संपूर्ण बुकिंग फ्लो

पूर्ण अपॉइंटमेंट बुकिंग सिस्टीमसाठी टूल्सचा हा संच आहे:

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

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

संबंधित