--- title: "Zana za Function" description: "Wape ejenti zako za AI zana za function zinazopiga API za nje katikati ya mazungumzo — kupata data za wateja, kuweka miadi, kusasisha rekodi — zikiwa na vigezo vilivyoainishwa kwa aina." --- Zana za vitendaji huruhusu ejenti zako za AI kuita API za nje wakati wa simu. Zitumie kutafuta data ya mteja, kuangalia upatikanaji, kuweka miadi, au kutekeleza hatua yoyote inayotumika kwenye backend yako. ## Jinsi Inavyofanya Kazi 1. Unafafanua zana kwa schema (hoja ambazo zana inakubali) 2. Unatoa usanidi wa `endpoint` (mahali ThunderPhone inapoita API yako) — au uiachie ili upokee miito ya zana kwenye webhook ya org yako 3. Wakati wa simu, AI huamua wakati wa kutumia zana kulingana na mazungumzo 4. ThunderPhone huita endpoint yako kwa hoja za zana 5. Jibu la API yako hurudishwa kwa AI ili kuendeleza mazungumzo | Uwezo | Mahali inapotekelezwa | Usanidi | | --- | --- | --- | | [Zana zilizojengewa ndani](/sw/guides/built-in-tools) | ThunderPhone | Maagizo ya prompt; baadhi ya zana pia zinahitaji mpangilio wa ejenti | | [Miunganisho ya app](/sw/guides/connect-apps) | ThunderPhone na mtoa huduma aliyeunganishwa | Unganisha akaunti na uambatishe hatua zilizoidhinishwa | | [Miunganisho ya API](/sw/guides/api-connections) na zana za vitendaji | API yako ya HTTP | Fafanua endpoint na schema, au pokea miito ya vitendaji kupitia webhook | | [Seva za MCP](/sw/guides/mcp-servers) | Seva ya MCP ya mbali | Ongeza seva, gundua zana zake, na uiambatishe kwa ejenti | --- ## Schema ya Zana Kila zana hufuata muundo huu: ```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 } ``` ### Usanidi wa Zana | Sehemu | Aina | Inahitajika | Maelezo | |-------|------|----------|-------------| | `timeout` | nambari | Hapana | Muda wa juu wa utekelezaji kwa sekunde (chaguo-msingi: `20`, kiwango cha juu: `180`) | ### Ufafanuzi wa Kitendaji | Sehemu | Aina | Inahitajika | Maelezo | |-------|------|----------|-------------| | `name` | mfuatano | Ndiyo | Kitambulisho cha kipekee cha zana | | `description` | mfuatano | Ndiyo | Huieleza AI wakati wa kutumia zana hii | | `parameters` | kitu | Ndiyo | JSON Schema ya hoja za zana | ### Usanidi wa Endpoint | Sehemu | Aina | Inahitajika | Maelezo | |-------|------|----------|-------------| | `url` | mfuatano | Ndiyo | URL ya endpoint ya API yako | | `method` | mfuatano | Hapana | Mbinu ya HTTP (chaguo-msingi: `POST`) | | `headers` | kitu | Hapana | Header maalum za kujumuisha | Usanidi wa `endpoint` **hautumwi** kwa modeli ya AI—unatumiwa tu na ThunderPhone kutekeleza mwito wa zana. --- ## Njia mbili za kuita Ombi ambalo seva yako inapokea hutegemea ikiwa zana ina `endpoint`: | | Zana **yenye** `endpoint` | Zana **isiyo na** `endpoint` | |---|---|---| | Ombi linakoenda | Moja kwa moja kwa `endpoint.url` | [URL ya webhook ya urithi](/api-reference/organizations#legacy-single-url-webhook) ya org yako | | Mwili | **Hoja za zana pekee** | Bahasha ya `telephony.tool` / `web.tool` | | Header | `endpoint.headers` yako + `X-ThunderPhone-Call-ID` + `X-ThunderPhone-Signature` | `Content-Type` + `X-ThunderPhone-Signature` | | Ufunguo wa kutia sahihi | Siri ya webhook ya org | Siri ya webhook ya org | Njia zote mbili **huzuia** — AI inasubiri katikati ya sentensi kupata matokeo. Muda chaguo-msingi wa kuisha ni **20 s**; weka `timeout` ya kiwango cha juu ya zana ili kuruhusu utekelezaji mrefu zaidi, hadi kiwango cha juu cha mfumo cha **180 s**. Weka handler ziwe za haraka. Mchanganyiko unaruhusiwa: kwenye simu ambayo org yake ina URL ya webhook, zana zilizo na `endpoint` huitwa moja kwa moja na nyingine hurudi kwenye webhook. ## Miito ya moja kwa moja ya endpoint Wakati AI inapoita zana yenye `endpoint`, ThunderPhone hutuma ombi kwenye URL yako: ### Vichwa vya Ombi ```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 ``` Vichwa maalum kutoka kwenye `endpoint.headers` yako hujumuishwa kila wakati kama yalivyo, pamoja na vichwa viwili vilivyo na nafasi ya majina ya ThunderPhone: - `X-ThunderPhone-Signature` — HMAC-SHA256 ya baiti kamili za mwili wa ombi, inayotumia **siri ya webhook ya shirika lako** kama ufunguo - `X-ThunderPhone-Call-ID` — Kitambulisho cha simu ya sasa `Content-Type: application/json` huwekwa isipokuwa `endpoint.headers` yako iibadilishe — `Content-Type` maalum hupewa kipaumbele. Sahihi hutumia siri ya webhook ya kiwango cha shirika kutoka [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook). Ikiwa shirika lako halijawahi kusanidi webhook ya zamani, hakuna siri na miito ya zana hubeba **pekee** `X-ThunderPhone-Call-ID` — kishughulikiaji kinachoshindwa moja kwa moja kwa sababu sahihi haipo kingezikataa. Ama sanidi webhook ya zamani ili kupata siri, au weka siri yako mwenyewe iliyoshirikiwa kwenye `endpoint.headers`. ### Mwili wa Ombi Kwa `POST` / `PUT` / `PATCH`, mwili una **pekee** hoja za zana (bila kifuniko), zilizoserialishwa kwa mpangilio thabiti (funguo zilizopangwa, vitenganishi finyu): ```json {"date":"2025-01-02","service":"consultation"} ``` Kwa `GET` / `DELETE`, hoja hutumwa kama **vigezo vya hoja** na mwili huwa tupu — sahihi huhesabiwa juu ya mfuatano tupu wa baiti. Tazama [Thibitisha sahihi za webhook](/sw/guides/verify-webhook-signatures). ### Jibu Rudisha jibu la JSON lenye matokeo ya zana: ```json { "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"], "timezone": "America/Los_Angeles" } ``` Jibu hupangwa na kupewa AI ili kuendeleza mazungumzo. Majibu yasiyo ya JSON hufunikwa kama `{"data": ""}`; muda kuisha na hitilafu za muunganisho huripotiwa kwa AI kama hitilafu, hivyo ejenti inaweza kuomba msamaha na kuendelea badala ya kusita. ## Uelekezaji wa hali ya webhook Zana **zisizo na** `endpoint` huelekezwa kwenye URL ya webhook ya zamani ya shirika lako kama ombi lililotiwa sahihi la `telephony.tool` (simu) au `web.tool` (miito ya wavuti). Tofauti na [arifa za ukaguzi](/sw/webhooks/events) zinazowasilishwa kwenye endpoint za webhook baada ya utekelezaji, ombi hili **ndilo** utekelezaji — jibu lako la HTTP ndilo matokeo ya zana. ```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` hubeba `origin_domain` badala ya `from_number` / `to_number`. Jibu kwa matokeo ya zana kama JSON — mkataba sawa wa jibu kama miito ya moja kwa moja ya endpoint. Ombi hutiwa sahihi kwa siri ya webhook ya shirika juu ya mwili ghafi, kama webhook nyingine yoyote. [Endpoint za webhook](/sw/webhooks/endpoints) zilizosajiliwa pia hupokea `telephony.tool` / `web.tool` isiyozuia **arifa baada ya** kila zana kutekelezwa (njia yoyote iliyoiendesha), ikijumuisha jibu la zana — ni muhimu kwa rekodi za ukaguzi. Tazama [orodha ya matukio](/sw/webhooks/events). --- ## Uthibitishaji wa Sahihi Miito ya moja kwa moja ya zana husainiwa kwa njia ileile kama webhook: - HMAC-SHA256 juu ya baiti halisi za ombi (JSON sanifu — funguo zilizopangwa, bila nafasi za ziada) - Kwa kutumia siri ya webhook ya shirika lako kama ufunguo - Zana za `GET` / `DELETE` husaini mfuatano wa baiti tupu ```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 }); }); ``` Maelekezo kamili — ikiwemo hali ya mwili tupu na tahadhari ya kutokuwa na siri — yapo katika [Thibitisha sahihi za webhook](/sw/guides/verify-webhook-signatures). --- ## Mfano: Mtiririko Kamili wa Kuhifadhi Miadi Hii ni seti ya zana za mfumo kamili wa kuhifadhi miadi: ```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" } } } ] } ``` --- ## Mbinu Bora Sehemu ya `description` husaidia AI kuelewa **lini** itumie zana. Eleza kwa mahususi inachofanya na lini inafaa kutumika. Rudisha ujumbe wa hitilafu ambao AI inaweza kuelewa: `{"error": "No slots available for that date"}` badala ya hitilafu za jumla za 500. Rudisha tu kile AI inahitaji ili kuendeleza mazungumzo. Payload kubwa hupunguza kasi ya muda wa majibu. Weka alama kwenye sehemu kama `required` tu inapohitajika kweli. AI itamwomba mtumiaji taarifa zinazohitajika kabla ya kuita zana. --- ## Yanayohusiana Tumia prompt kwa vitendo vya simu vinavyosimamiwa na jukwaa bila kufafanua endpoint. Zana zinazosimamiwa na jukwaa za HubSpot, Salesforce, Slack, Google Calendar, Google Sheets, na Cal.com — hakuna endpoint inayohitajika. Ambatisha seva ya MCP na uruhusu ejenti kuita zana zake. Miunganisho ya REST inayoweza kutumika tena unayoweza kuambatisha kwa ejenti. Kisaidizi kimoja cha uthibitishaji kwa webhook na miito ya zana.