--- title: "ફંક્શન ટૂલ્સ" description: "તમારા AI એજન્ટોને એવા ફંક્શન ટૂલ્સ આપો જે વાતચીત દરમિયાન બાહ્ય API ને કૉલ કરે — ગ્રાહક ડેટા મેળવે, એપોઇન્ટમેન્ટ બુક કરે, રેકોર્ડ અપડેટ કરે — પ્રકાર-નિર્ધારિત પેરામીટરો સાથે." --- ફંક્શન ટૂલ્સ તમારા AI એજન્ટ્સને ફોન કૉલ્સ દરમિયાન બાહ્ય APIs ઇન્વોક કરવાની મંજૂરી આપે છે. ગ્રાહક ડેટા શોધવા, ઉપલબ્ધતા તપાસવા, એપૉઇન્ટમેન્ટ બુક કરવા અથવા તમારું બેકએન્ડ સપોર્ટ કરતું કોઈપણ કાર્ય કરવા માટે તેનો ઉપયોગ કરો. ## તે કેવી રીતે કાર્ય કરે છે 1. તમે સ્કીમા સાથે ટૂલ્સ વ્યાખ્યાયિત કરો છો (ટૂલ કયા આર્ગ્યુમેન્ટ્સ સ્વીકારે છે) 2. તમે `endpoint` કૉન્ફિગરેશન પ્રદાન કરો છો (ThunderPhone તમારા API ને ક્યાં કૉલ કરે છે) — અથવા તમારા સંસ્થાના વેબહૂક પર ટૂલ કૉલ્સ મેળવવા માટે તેને છોડો 3. કૉલ દરમિયાન, AI વાતચીતના આધારે ટૂલ ક્યારે વાપરવું તે નક્કી કરે છે 4. ThunderPhone ટૂલ આર્ગ્યુમેન્ટ્સ સાથે તમારા એન્ડપૉઇન્ટને કૉલ કરે છે 5. વાતચીત ચાલુ રાખવા માટે તમારો API પ્રતિસાદ પાછો AI ને આપવામાં આવે છે | ક્ષમતા | તે ક્યાં ચાલે છે | સેટઅપ | | --- | --- | --- | | [બિલ્ટ-ઇન ટૂલ્સ](/gu/guides/built-in-tools) | ThunderPhone | Prompt સૂચનાઓ; કેટલીક ટૂલ્સને એજન્ટ સેટિંગ પણ જરૂરી હોય છે | | [એપ કનેક્શન્સ](/gu/guides/connect-apps) | ThunderPhone અને કનેક્ટેડ પ્રદાતા | એકાઉન્ટ કનેક્ટ કરો અને મંજૂર કરેલી ક્રિયાઓ જોડો | | [API કનેક્શન્સ](/gu/guides/api-connections) અને ફંક્શન ટૂલ્સ | તમારું HTTP API | એન્ડપૉઇન્ટ અને સ્કીમા વ્યાખ્યાયિત કરો અથવા વેબહૂક દ્વારા ફંક્શન કૉલ્સ મેળવો | | [MCP સર્વર્સ](/gu/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 s** છે; વધુ લાંબા એક્ઝિક્યુશનને મંજૂરી આપવા માટે ટૂલનું ટોચના સ્તરનું `timeout` સેટ કરો, જે પ્લેટફૉર્મની **180 s** મહત્તમ મર્યાદા સુધી હોઈ શકે છે. હેન્ડલર્સ ઝડપી રાખો. મિશ્રણ સ્વીકાર્ય છે: જે કૉલની સંસ્થામાં વેબહૂક URL હોય તેમાં `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 - `X-ThunderPhone-Call-ID` — વર્તમાન કૉલ ID તમારા `endpoint.headers` તેને ઓવરરાઇડ ન કરે ત્યાં સુધી `Content-Type: application/json` સેટ થાય છે — કસ્ટમ `Content-Type` ને પ્રાથમિકતા મળે છે. સિગ્નેચર માટે સંસ્થા-સ્તરના વેબહૂક સિક્રેટનો ઉપયોગ થાય છે, જે [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook) માંથી મળે છે. જો તમારી સંસ્થાએ ક્યારેય લેગસી વેબહૂક કૉન્ફિગર કર્યું ન હોય, તો કોઈ સિક્રેટ હોતું નથી અને ટૂલ કૉલ્સમાં **માત્ર** `X-ThunderPhone-Call-ID` હોય છે — ગેરહાજર સિગ્નેચર પર હાર્ડ-ફેલ થતો હેન્ડલર તેમને નકારી કાઢશે. સિક્રેટ મેળવવા માટે લેગસી વેબહૂક કૉન્ફિગર કરો અથવા તમારું પોતાનું શેર કરેલ સિક્રેટ `endpoint.headers` માં મૂકો. ### વિનંતી બૉડી `POST` / `PUT` / `PATCH` માટે, બૉડીમાં **માત્ર** ટૂલ આર્ગ્યુમેન્ટ્સ હોય છે (કોઈ રૅપર વગર), જે કેનોનિકલી સિરિયલાઇઝ કરેલા હોય છે (સૉર્ટ કરેલી કીઝ, કોમ્પેક્ટ સેપરેટર્સ): ```json {"date":"2025-01-02","service":"consultation"} ``` `GET` / `DELETE` માટે, આર્ગ્યુમેન્ટ્સ **ક્વેરી પેરામીટર્સ** તરીકે મોકલવામાં આવે છે અને બૉડી ખાલી હોય છે — ત્યારબાદ સિગ્નેચર ખાલી બાઇટ સ્ટ્રિંગ પર ગણવામાં આવે છે. જુઓ [વેબહૂક સિગ્નેચર્સ ચકાસો](/gu/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 ને ભૂલો તરીકે રિપોર્ટ થાય છે, જેથી એજન્ટ અટકી જવાને બદલે માફી માંગી અને આગળ વધી શકે. ## વેબહૂક-મોડ ડિસ્પૅચ `endpoint` **વિના**ના ટૂલ્સ તમારી સંસ્થાના લેગસી વેબહૂક URL પર સાઇન કરેલી `telephony.tool` (ફોન કૉલ્સ) અથવા `web.tool` (વેબ કૉલ્સ) વિનંતી તરીકે ડિસ્પૅચ થાય છે. એક્ઝિક્યુશન પછી વેબહૂક એન્ડપૉઇન્ટ્સ પર પહોંચાડવામાં આવતી [ઑડિટ સૂચનાઓ](/gu/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 તરીકે પ્રતિસાદ આપો — સીધા એન્ડપૉઇન્ટ કૉલ્સ જેવો જ પ્રતિસાદ કરાર. દરેક અન્ય વેબહૂકની જેમ વિનંતી પર રૉ બૉડી વડે સંસ્થાના વેબહૂક સિક્રેટથી સહી કરવામાં આવે છે. સબ્સ્ક્રાઇબ કરેલા [વેબહૂક એન્ડપૉઇન્ટ્સ](/gu/webhooks/endpoints) ને વધારામાં દરેક ટૂલ એક્ઝિક્યુટ થયા **પછી** બિન-અવરોધક `telephony.tool` / `web.tool` **સૂચના** મળે છે (જે પાથથી તે ચલાવવામાં આવ્યું હોય તે), જેમાં ટૂલનો પ્રતિસાદ પણ સામેલ હોય છે — ઑડિટ ટ્રેઇલ્સ માટે ઉપયોગી. જુઓ [ઇવેન્ટ્સ કૅટલૉગ](/gu/webhooks/events). --- ## સહીની ચકાસણી સીધા ટૂલ કૉલ્સ વેબહુક્સની જેમ જ સહી કરવામાં આવે છે: - ચોક્કસ request-body બાઇટ્સ પર HMAC-SHA256 (કેનોનિકલ JSON — સૉર્ટ કરેલી કીઝ, વધારાની ખાલી જગ્યા વિના) - તમારા org webhook secret સાથે કીડ - `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 }); }); ``` ખાલી-body કેસ અને secret ન હોવાની ચેતવણી સહિતની સંપૂર્ણ રેસીપી [Webhook સહી ચકાસો](/gu/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 ઇન્ટિગ્રેશન્સ જે તમે એજન્ટ્સ સાથે જોડી શકો છો. વેબહૂક્સ અને ટૂલ કૉલ્સ માટે એક ચકાસણી સહાયક.