---
title: "फंक्शन टूल्स"
description: "तुमच्या AI एजंटना संभाषणादरम्यान बाह्य API कॉल करणारी फंक्शन टूल्स द्या — ग्राहक डेटा मिळवा, अपॉइंटमेंट बुक करा, नोंदी अपडेट करा — टाइप केलेल्या पॅरामीटर्ससह."
---
फंक्शन टूल्स तुमच्या AI एजंटना फोन कॉलदरम्यान बाह्य API वापरण्याची परवानगी देतात. ग्राहक डेटा शोधण्यासाठी, उपलब्धता तपासण्यासाठी, भेटी बुक करण्यासाठी किंवा तुमचे बॅकएंड समर्थित असलेली कोणतीही कृती करण्यासाठी त्यांचा वापर करा.
## हे कसे कार्य करते
1. तुम्ही स्कीमासह टूल्स परिभाषित करता (टूल कोणते आर्ग्युमेंट स्वीकारते)
2. तुम्ही `endpoint` कॉन्फिगरेशन देता (ThunderPhone तुमच्या API ला कुठे कॉल करते) — किंवा तुमच्या ऑर्ग वेबहुकवर टूल कॉल प्राप्त करण्यासाठी ते वगळा
3. कॉलदरम्यान, संभाषणाच्या आधारावर टूल कधी वापरायचे हे AI ठरवते
4. ThunderPhone टूल आर्ग्युमेंटसह तुमच्या एंडपॉइंटला कॉल करते
5. संभाषण सुरू ठेवण्यासाठी तुमचा API प्रतिसाद AI कडे परत पाठवला जातो
| क्षमता | ते कुठे चालते | सेटअप |
| --- | --- | --- |
| [अंगभूत टूल्स](/mr/guides/built-in-tools) | ThunderPhone | prompt सूचना; काही टूल्सना एजंट सेटिंग देखील आवश्यक असते |
| [अॅप कनेक्शन](/mr/guides/connect-apps) | ThunderPhone आणि कनेक्ट केलेला प्रदाता | खाते कनेक्ट करा आणि मंजूर कृती जोडा |
| [API कनेक्शन](/mr/guides/api-connections) आणि फंक्शन टूल्स | तुमचे HTTP API | एंडपॉइंट आणि स्कीमा परिभाषित करा किंवा वेबहुकद्वारे फंक्शन कॉल प्राप्त करा |
| [MCP सर्व्हर](/mr/guides/mcp-servers) | रिमोट MCP सर्व्हर | सर्व्हर जोडा, त्याची टूल्स शोधा आणि ते एजंटला जोडा |
---
## टूल स्कीमा
प्रत्येक टूल ही रचना अनुसरते:
```json
{
"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
}
```
### टूल कॉन्फिगरेशन
| फील्ड | प्रकार | आवश्यक | वर्णन |
|-------|------|----------|-------------|
| `timeout` | संख्या | नाही | सेकंदांमधील कमाल अंमलबजावणी वेळ (डीफॉल्ट: `20`, कमाल: `180`) |
### फंक्शन परिभाषा
| फील्ड | प्रकार | आवश्यक | वर्णन |
|-------|------|----------|-------------|
| `name` | स्ट्रिंग | होय | टूलसाठी अद्वितीय ओळखकर्ता |
| `description` | स्ट्रिंग | होय | हे टूल कधी वापरायचे ते AI ला स्पष्ट करते |
| `parameters` | ऑब्जेक्ट | होय | टूल आर्ग्युमेंटसाठी JSON स्कीमा |
### एंडपॉइंट कॉन्फिगरेशन
| फील्ड | प्रकार | आवश्यक | वर्णन |
|-------|------|----------|-------------|
| `url` | स्ट्रिंग | होय | तुमच्या API एंडपॉइंटची URL |
| `method` | स्ट्रिंग | नाही | HTTP पद्धत (डीफॉल्ट: `POST`) |
| `headers` | ऑब्जेक्ट | नाही | समाविष्ट करण्यासाठी सानुकूल हेडर्स |
`endpoint` कॉन्फिगरेशन AI मॉडेलला पाठवले जात **नाही**—ते फक्त टूल कॉल कार्यान्वित करण्यासाठी ThunderPhone द्वारे वापरले जाते.
---
## दोन इनव्होकेशन मार्ग
तुमच्या सर्व्हरला कोणती विनंती मिळते हे टूलकडे
`endpoint` आहे की नाही यावर अवलंबून असते:
| | `endpoint` **असलेले** टूल | `endpoint` **नसलेले** टूल |
|---|---|---|
| विनंती कुठे जाते | थेट `endpoint.url` कडे | तुमच्या ऑर्गच्या [लेगसी वेबहुक URL](/api-reference/organizations#legacy-single-url-webhook) कडे |
| बॉडी | **फक्त टूल आर्ग्युमेंट्स** | `telephony.tool` / `web.tool` एन्व्हलप |
| हेडर्स | तुमचे `endpoint.headers` + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` |
| साइनिंग की | ऑर्ग वेबहुक सीक्रेट | ऑर्ग वेबहुक सीक्रेट |
दोन्ही मार्ग **ब्लॉकिंग** आहेत — AI निकालासाठी वाक्याच्या मध्यात
प्रतीक्षा करत असते. डीफॉल्ट टाइमआउट **20 सेकंद** आहे; जास्त वेळ
अंमलबजावणीसाठी टूलचा टॉप-लेव्हल `timeout` सेट करा, प्लॅटफॉर्मच्या **180 सेकंद**
कमाल मर्यादेपर्यंत. हँडलर जलद ठेवा. मिश्र वापरही शक्य आहे:
ज्या कॉलच्या ऑर्गकडे वेबहुक URL आहे, त्यावर `endpoint` असलेल्या टूल्सना
थेट कॉल केला जातो आणि उर्वरित वेबहुककडे परत जातात.
## थेट endpoint कॉल्स
जेव्हा AI `endpoint` असलेले टूल वापरते, तेव्हा ThunderPhone तुमच्या URL ला
विनंती पाठवते:
### विनंती हेडर्स
```http
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` ला प्राधान्य मिळते.
सिग्नेचरला [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook)
मधील संस्था-स्तरीय webhook सीक्रेटने की केले जाते.
तुमच्या संस्थेने लेगसी webhook कधीही कॉन्फिगर केले नसल्यास, कोणतेही
सीक्रेट नसते आणि टूल कॉल्समध्ये **फक्त** `X-ThunderPhone-Call-ID` असते —
सिग्नेचर नसल्यास हार्ड-फेल होणारा हँडलर ते नाकारेल.
सीक्रेट मिळवण्यासाठी लेगसी webhook कॉन्फिगर करा किंवा तुमचे स्वतःचे
शेअर्ड सीक्रेट `endpoint.headers` मध्ये ठेवा.
### विनंती बॉडी
`POST` / `PUT` / `PATCH` साठी, बॉडीमध्ये **फक्त** टूलचे
आर्ग्युमेंट्स असतात (कोणतेही रॅपर नसते), कॅनॉनिकली सिरिअलाइझ केलेले (सॉर्ट केलेल्या कीज,
कॉम्पॅक्ट सेपरेटर्स):
```json
{"date":"2025-01-02","service":"consultation"}
```
`GET` / `DELETE` साठी, आर्ग्युमेंट्स **क्वेरी पॅरामीटर्स** म्हणून पाठवले
जातात आणि बॉडी रिकामी असते — त्यानंतर सिग्नेचर रिकाम्या बाइट स्ट्रिंगवर
कॅल्क्युलेट केले जाते. [webhook सिग्नेचर्स सत्यापित करा](/mr/guides/verify-webhook-signatures) पहा.
### प्रतिसाद
टूलच्या निकालासह JSON प्रतिसाद परत करा:
```json
{
"available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
"timezone": "America/Los_Angeles"
}
```
संभाषण सुरू ठेवण्यासाठी प्रतिसाद फॉरमॅट करून AI ला दिला जातो. JSON नसलेले
प्रतिसाद `{"data": ""}` मध्ये रॅप केले जातात; टाइमआउट्स आणि कनेक्शन
अयशस्वी होणे AI ला त्रुटी म्हणून कळवले जाते, त्यामुळे एजंट थांबून राहण्याऐवजी
माफी मागून पुढे जाऊ शकतो.
## Webhook-मोड डिस्पॅच
`endpoint` **नसलेली** टूल्स तुमच्या संस्थेच्या लेगसी webhook URL वर साइन केलेली
`telephony.tool` (फोन कॉल्स) किंवा `web.tool` (वेब कॉल्स) विनंती म्हणून डिस्पॅच
केली जातात. एक्झिक्यूशननंतर webhook endpoints वर पाठवल्या जाणाऱ्या
[ऑडिट सूचनांपेक्षा](/mr/webhooks/events) वेगळे म्हणजे, ही विनंती **हेच**
एक्झिक्यूशन आहे — तुमचा HTTP प्रतिसाद हाच टूलचा निकाल असतो.
```json
{
"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 सीक्रेटने साइन केले जाते.
सदस्यत्व घेतलेल्या [webhook endpoints](/mr/webhooks/endpoints) ना प्रत्येक टूल
एक्झिक्यूट झाल्यानंतर (ते कोणत्याही मार्गाने चालवले असले तरी) टूलच्या
प्रतिसादासह नॉन-ब्लॉकिंग `telephony.tool` / `web.tool` **सूचना
नंतर** देखील मिळते — ऑडिट ट्रेल्ससाठी उपयुक्त. [इव्हेंट्स कॅटलॉग](/mr/webhooks/events)
पहा.
---
## स्वाक्षरी पडताळणी
थेट टूल कॉलना वेबहुकप्रमाणेच स्वाक्षरी केली जाते:
- अचूक विनंती-बॉडी बाइट्सवर HMAC-SHA256 (कॅनॉनिकल JSON —
क्रमबद्ध की, अतिरिक्त व्हाइटस्पेस नाही)
- तुमच्या संस्थेच्या वेबहुक सीक्रेटने की केलेले
- `GET` / `DELETE` टूल रिकाम्या बाइट स्ट्रिंगवर स्वाक्षरी करतात
```python Python
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}
```
```javascript Node.js
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 });
});
```
रिकाम्या-बॉडीच्या प्रकरणासह आणि सीक्रेट नसल्यावरील सूचनेसह संपूर्ण रेसिपी [वेबहुक स्वाक्षऱ्या पडताळा](/mr/guides/verify-webhook-signatures) मध्ये आहेत.
---
## उदाहरण: संपूर्ण बुकिंग फ्लो
संपूर्ण अपॉइंटमेंट बुकिंग सिस्टमसाठी टूलचा संच येथे आहे:
```json
{
"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" }
}
}
]
}
```
---
## सर्वोत्तम पद्धती
`description` फील्ड AI ला टूल **केव्हा** वापरायचे हे समजण्यास मदत करते. ते काय करते आणि ते केव्हा योग्य आहे याबद्दल स्पष्ट माहिती द्या.
AI ला समजतील असे त्रुटी संदेश परत करा: सामान्य 500 त्रुटींऐवजी `{"error": "No slots available for that date"}`.
संभाषण पुढे सुरू ठेवण्यासाठी AI ला जेवढी माहिती आवश्यक आहे तेवढीच परत करा. मोठे पेलोड प्रतिसादाचा वेळ वाढवतात.
फील्ड खरोखर आवश्यक असतील तेव्हाच त्यांना `required` म्हणून चिन्हांकित करा. टूल कॉल करण्यापूर्वी AI वापरकर्त्याकडून आवश्यक माहिती विचारेल.
---
## संबंधित
एंडपॉइंट परिभाषित न करता प्लॅटफॉर्मद्वारे व्यवस्थापित कॉल कृतींसाठी prompt द्या.
HubSpot, Salesforce, Slack, Google
Calendar, Google Sheets आणि Cal.com साठी प्लॅटफॉर्मद्वारे व्यवस्थापित टूल्स — एंडपॉइंटची आवश्यकता नाही.
MCP सर्व्हर जोडा आणि एजंटला त्याची टूल्स कॉल करू द्या.
एजंटना जोडता येतील अशी पुनर्वापरयोग्य REST एकत्रीकरणे.
वेबहुक आणि टूल कॉलसाठी एक सत्यापन हेल्पर.