--- title: "Εργαλεία συναρτήσεων" description: "Δώστε στους AI πράκτορές σας εργαλεία συναρτήσεων που καλούν εξωτερικά API κατά τη διάρκεια της συνομιλίας — ανακτούν δεδομένα πελατών, κλείνουν ραντεβού, ενημερώνουν εγγραφές — με παραμέτρους τύπου." --- Τα εργαλεία συναρτήσεων επιτρέπουν στους AI πράκτορές σας να καλούν εξωτερικά API κατά τη διάρκεια τηλεφωνικών κλήσεων. Χρησιμοποιήστε τα για να αναζητάτε δεδομένα πελατών, να ελέγχετε διαθεσιμότητα, να κλείνετε ραντεβού ή να εκτελείτε οποιαδήποτε ενέργεια υποστηρίζει το backend σας. ## Πώς λειτουργεί 1. Ορίζετε εργαλεία με ένα σχήμα (ποια ορίσματα δέχεται το εργαλείο) 2. Παρέχετε μια διαμόρφωση `endpoint` (πού καλεί το ThunderPhone το API σας) — ή την παραλείπετε για να λαμβάνετε κλήσεις εργαλείων στο webhook του οργανισμού σας 3. Κατά τη διάρκεια μιας κλήσης, το AI αποφασίζει πότε να χρησιμοποιήσει ένα εργαλείο βάσει της συνομιλίας 4. Το ThunderPhone καλεί το endpoint σας με τα ορίσματα του εργαλείου 5. Η απόκριση του API σας επιστρέφεται στο AI για να συνεχίσει τη συνομιλία | Δυνατότητα | Πού εκτελείται | Ρύθμιση | | --- | --- | --- | | [Ενσωματωμένα εργαλεία](/el/guides/built-in-tools) | ThunderPhone | Οδηγίες prompt· ορισμένα εργαλεία χρειάζονται επίσης μια ρύθμιση πράκτορα | | [Συνδέσεις εφαρμογών](/el/guides/connect-apps) | ThunderPhone και ο συνδεδεμένος πάροχος | Συνδέστε τον λογαριασμό και επισυνάψτε εγκεκριμένες ενέργειες | | [Συνδέσεις API](/el/guides/api-connections) και εργαλεία συναρτήσεων | Το HTTP API σας | Ορίστε το endpoint και το σχήμα ή λαμβάνετε κλήσεις συναρτήσεων μέσω webhook | | [Διακομιστές MCP](/el/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 για τα ορίσματα του εργαλείου | ### Διαμόρφωση endpoint | Πεδίο | Τύπος | Υποχρεωτικό | Περιγραφή | |-------|------|----------|-------------| | `url` | συμβολοσειρά | Ναι | URL του endpoint του API σας | | `method` | συμβολοσειρά | Όχι | Μέθοδος HTTP (προεπιλογή: `POST`) | | `headers` | αντικείμενο | Όχι | Προσαρμοσμένες κεφαλίδες προς συμπερίληψη | Η διαμόρφωση `endpoint` **δεν** αποστέλλεται στο μοντέλο AI — χρησιμοποιείται μόνο από το ThunderPhone για την εκτέλεση της κλήσης εργαλείου. --- ## Δύο διαδρομές κλήσης Το αίτημα που λαμβάνει ο διακομιστής σας εξαρτάται από το αν το εργαλείο έχει `endpoint`: | | Εργαλείο **με** `endpoint` | Εργαλείο **χωρίς** `endpoint` | |---|---|---| | Πού αποστέλλεται το αίτημα | Απευθείας στο `endpoint.url` | Στο [URL webhook παλαιού τύπου](/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` | | Κλειδί υπογραφής | Μυστικό webhook οργανισμού | Μυστικό webhook οργανισμού | Και οι δύο διαδρομές είναι **δεσμευτικές** — το AI περιμένει στη μέση της πρότασης για το αποτέλεσμα. Το προεπιλεγμένο χρονικό όριο είναι **20 δευτ.**· ορίστε το `timeout` ανώτατου επιπέδου του εργαλείου για να επιτρέψετε μεγαλύτερο χρόνο εκτέλεσης, έως το μέγιστο της πλατφόρμας των **180 δευτ.**. Διατηρείτε τους χειριστές γρήγορους. Επιτρέπεται ένας συνδυασμός: σε μια κλήση όπου ο οργανισμός διαθέτει URL webhook, τα εργαλεία με `endpoint` καλούνται απευθείας και τα υπόλοιπα επιστρέφουν στο webhook. ## Άμεσες κλήσεις 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 των ακριβών byte του σώματος αιτήματος, με κλειδί το **μυστικό webhook του οργανισμού σας** - `X-ThunderPhone-Call-ID` — Το αναγνωριστικό της τρέχουσας κλήσης Το `Content-Type: application/json` ορίζεται εκτός αν το `endpoint.headers` το παρακάμπτει — ένα προσαρμοσμένο `Content-Type` υπερισχύει. Η υπογραφή χρησιμοποιεί ως κλειδί το μυστικό webhook σε επίπεδο οργανισμού από το [`GET /v1/webhook`](/api-reference/organizations#legacy-single-url-webhook). Αν ο οργανισμός σας δεν έχει ποτέ ρυθμίσει το παλαιού τύπου webhook, δεν υπάρχει μυστικό και οι κλήσεις εργαλείων περιέχουν **μόνο** το `X-ThunderPhone-Call-ID` — ένας χειριστής που αποτυγχάνει οριστικά όταν λείπει υπογραφή θα τις απορρίψει. Ρυθμίστε το παλαιού τύπου webhook για να αποκτήσετε μυστικό ή τοποθετήστε το δικό σας κοινόχρηστο μυστικό στο `endpoint.headers`. ### Σώμα αιτήματος Για `POST` / `PUT` / `PATCH`, το σώμα περιέχει **μόνο** τα ορίσματα του εργαλείου (χωρίς περιτύλιγμα), σειριοποιημένα κανονικά (ταξινομημένα κλειδιά, συμπαγείς διαχωριστές): ```json {"date":"2025-01-02","service":"consultation"} ``` Για `GET` / `DELETE`, τα ορίσματα αποστέλλονται ως **παράμετροι ερωτήματος** και το σώμα είναι κενό — η υπογραφή υπολογίζεται τότε πάνω στην κενή συμβολοσειρά byte. Δείτε [Επαλήθευση υπογραφών webhook](/el/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` αποστέλλονται στο URL παλαιού τύπου webhook του οργανισμού σας ως υπογεγραμμένο αίτημα `telephony.tool` (τηλεφωνικές κλήσεις) ή `web.tool` (κλήσεις web). Σε αντίθεση με τις [ειδοποιήσεις ελέγχου](/el/webhooks/events) που παραδίδονται σε endpoint webhook μετά την εκτέλεση, αυτό το αίτημα **είναι** η εκτέλεση — η απόκρισή σας 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` περιέχει `origin_domain` αντί για `from_number` / `to_number`. Απαντήστε με το αποτέλεσμα του εργαλείου ως JSON — το ίδιο συμβόλαιο απόκρισης με τις άμεσες κλήσεις endpoint. Το αίτημα υπογράφεται με το μυστικό webhook του οργανισμού πάνω στο ακατέργαστο σώμα, όπως κάθε άλλο webhook. Τα εγγεγραμμένα [endpoint webhook](/el/webhooks/endpoints) λαμβάνουν επιπλέον μια μη αποκλειστική `telephony.tool` / `web.tool` **ειδοποίηση μετά** από κάθε εκτέλεση εργαλείου (ανεξάρτητα από τη διαδρομή που το εκτέλεσε), η οποία περιλαμβάνει την απόκριση του εργαλείου — χρήσιμη για ίχνη ελέγχου. Δείτε τον [κατάλογο συμβάντων](/el/webhooks/events). --- ## Επαλήθευση υπογραφής Οι άμεσες κλήσεις εργαλείων υπογράφονται με τον ίδιο τρόπο όπως τα webhook: - HMAC-SHA256 πάνω στα ακριβή byte του σώματος αιτήματος (το κανονικό JSON — ταξινομημένα κλειδιά, χωρίς επιπλέον κενά) - Με κλειδί το μυστικό webhook του οργανισμού σας - Τα εργαλεία `GET` / `DELETE` υπογράφουν την κενή συμβολοσειρά byte ```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 }); }); ``` Οι πλήρεις οδηγίες — συμπεριλαμβανομένης της περίπτωσης κενού σώματος και της επισήμανσης για την απουσία μυστικού — βρίσκονται στο [Επαλήθευση υπογραφών webhook](/el/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 πράκτορας: `{"error": "No slots available for that date"}` αντί για γενικά σφάλματα 500. Επιστρέφετε μόνο ό,τι χρειάζεται ο AI πράκτορας για να συνεχίσει τη συνομιλία. Τα μεγάλα φορτία δεδομένων επιβραδύνουν τους χρόνους απόκρισης. Επισημαίνετε τα πεδία ως `required` μόνο όταν είναι πραγματικά απαραίτητο. Ο AI πράκτορας θα ζητήσει από τον χρήστη τις απαιτούμενες πληροφορίες πριν καλέσει το εργαλείο. --- ## Σχετικά Ενεργοποιήστε ενέργειες κλήσεων που διαχειρίζεται η πλατφόρμα χωρίς να ορίσετε endpoint. Εργαλεία που διαχειρίζεται η πλατφόρμα για τα HubSpot, Salesforce, Slack, Google Calendar, Google Sheets και Cal.com — δεν απαιτείται endpoint. Συνδέστε έναν διακομιστή MCP και επιτρέψτε στον πράκτορα να καλεί τα εργαλεία του. Επαναχρησιμοποιήσιμες ενσωματώσεις REST που μπορείτε να συνδέσετε με πράκτορες. Ένα βοήθημα επαλήθευσης για webhook και κλήσεις εργαλείων.