Το ThunderPhone v3 είναι πλέον διαθέσιμο.Ξεκινήστε μόνοι σας, από 2¢/λεπτό.Διαβάστε την ανακοίνωση

Function Tools

Εργαλεία συναρτήσεων

Δώστε στους AI πράκτορές σας εργαλεία συναρτήσεων που καλούν εξωτερικά API κατά τη διάρκεια της συνομιλίας — ανακτούν δεδομένα πελατών, κλείνουν ραντεβού, ενημερώνουν εγγραφές — με παραμέτρους τύπου.

Τα εργαλεία συναρτήσεων επιτρέπουν στους AI πράκτορές σας να καλούν εξωτερικά API κατά τη διάρκεια τηλεφωνικών κλήσεων. Χρησιμοποιήστε τα για να αναζητάτε δεδομένα πελατών, να ελέγχετε διαθεσιμότητα, να κλείνετε ραντεβού ή να εκτελείτε οποιαδήποτε ενέργεια υποστηρίζει το backend σας.

Πώς λειτουργεί

  1. Ορίζετε εργαλεία με ένα σχήμα (ποια ορίσματα δέχεται το εργαλείο)
  2. Παρέχετε μια διαμόρφωση endpoint (πού καλεί το ThunderPhone το API σας) — ή την παραλείπετε για να λαμβάνετε κλήσεις εργαλείων στο webhook του οργανισμού σας
  3. Κατά τη διάρκεια μιας κλήσης, το AI αποφασίζει πότε να χρησιμοποιήσει ένα εργαλείο βάσει της συνομιλίας
  4. Το ThunderPhone καλεί το endpoint σας με τα ορίσματα του εργαλείου
  5. Η απόκριση του API σας επιστρέφεται στο AI για να συνεχίσει τη συνομιλία
ΔυνατότηταΠού εκτελείταιΡύθμιση
Ενσωματωμένα εργαλείαThunderPhoneΟδηγίες prompt· ορισμένα εργαλεία χρειάζονται επίσης μια ρύθμιση πράκτορα
Συνδέσεις εφαρμογώνThunderPhone και ο συνδεδεμένος πάροχοςΣυνδέστε τον λογαριασμό και επισυνάψτε εγκεκριμένες ενέργειες
Συνδέσεις API και εργαλεία συναρτήσεωνΤο HTTP API σαςΟρίστε το endpoint και το σχήμα ή λαμβάνετε κλήσεις συναρτήσεων μέσω webhook
Διακομιστές MCPΈνας απομακρυσμένος διακομιστής MCPΠροσθέστε τον διακομιστή, εντοπίστε τα εργαλεία του και επισυνάψτε τον στον πράκτορα

Σχήμα εργαλείου

Κάθε εργαλείο ακολουθεί αυτή τη δομή:

{
  "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 ή 600 με wait_mode: "hold")
wait_modeσυμβολοσειράΌχιΤι ακούει ο καλών ενώ εκτελείται το εργαλείο: updates (προεπιλογή), σύντομες προφορικές ενημερώσεις· ή hold, μουσική αναμονής. Δείτε Μεγάλες αναμονές: λειτουργία αναμονής και απάντηση αργότερα
call_startαντικείμενοΌχιΕκτελέστε επίσης το εργαλείο αυτόματα στην αρχή κάθε τηλεφωνικής κλήσης, πριν από τον χαιρετισμό. Δείτε Εκτέλεση εργαλείου στην αρχή της κλήσης

Ορισμός συνάρτησης

ΠεδίοΤύποςΑπαιτείταιΠεριγραφή
nameσυμβολοσειράΝαιΑναγνωριστικό του εργαλείου, μοναδικό μεταξύ των εργαλείων μιας κλήσης. Διαφορετικοί πράκτορες μπορούν να έχουν ο καθένας το δικό του εργαλείο με το ίδιο όνομα
descriptionσυμβολοσειράΝαιΕξηγεί στην AI πότε να χρησιμοποιεί αυτό το εργαλείο
parametersαντικείμενοΝαιΣχήμα JSON για τα ορίσματα του εργαλείου

Διαμόρφωση endpoint

ΠεδίοΤύποςΥποχρεωτικόΠεριγραφή
urlσυμβολοσειράΝαιURL του endpoint του API σας
methodσυμβολοσειράΌχιΜέθοδος HTTP (προεπιλογή: POST)
headersαντικείμενοΌχιΠροσαρμοσμένες κεφαλίδες προς συμπερίληψη

Δύο διαδρομές κλήσης

Το αίτημα που λαμβάνει ο διακομιστής σας εξαρτάται από το αν το εργαλείο έχει endpoint:

Εργαλείο με endpointΕργαλείο χωρίς endpoint
Πού αποστέλλεται το αίτημαΑπευθείας στο endpoint.urlΣτην παλαιού τύπου URL webhook του οργανισμού σας
ΣώμαΕπιλεγμένη μορφή αιτήματος (μόνο ορίσματα από προεπιλογή)Περιτύλιγμα telephony.tool / web.tool
ΚεφαλίδεςΤα endpoint.headers σας + X-ThunderPhone-Call-ID + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature, καθώς και οι αριθμοί της κλήσης στις τηλεφωνικές κλήσειςContent-Type + X-ThunderPhone-Signature-V2 + X-ThunderPhone-Signature
Κλειδί υπογραφήςΜυστικό webhook οργανισμούΜυστικό webhook οργανισμού

Και οι δύο διαδρομές είναι αποκλειστικές — ο AI πράκτορας περιμένει το αποτέλεσμα ενώ βρίσκεται στη μέση μιας πρότασης. Το προεπιλεγμένο χρονικό όριο είναι 20 s· ορίστε το timeout ανώτατου επιπέδου του εργαλείου για να επιτρέψετε μεγαλύτερο χρόνο εκτέλεσης, έως το μέγιστο όριο πλατφόρμας των 180 s. Διατηρείτε τους χειριστές γρήγορους. Για αναμονές για ένα άτομο ή μια αργή εργασία, χρησιμοποιήστε τη λειτουργία αναμονής. Επιτρέπεται συνδυασμός: σε μια κλήση της οποίας ο οργανισμός διαθέτει URL webhook, τα εργαλεία με endpoint καλούνται απευθείας και τα υπόλοιπα χρησιμοποιούν το webhook.

Άμεσες κλήσεις endpoint

Όταν ο AI πράκτορας καλεί ένα εργαλείο που έχει endpoint, το ThunderPhone στέλνει ένα αίτημα στο URL σας:

Κεφαλίδες αιτήματος

POST /appointments/search HTTP/1.1
Host: api.example.com
Content-Type: application/json
X-ThunderPhone-Signature-V2: t=1767225600,v1=5f2c...
X-ThunderPhone-Signature: abc123...
X-ThunderPhone-Call-ID: 987654321
X-ThunderPhone-From-Number: +14155550199
X-ThunderPhone-To-Number: +14155550100
X-ThunderPhone-Call-Direction: inbound
X-Api-Key: your-api-key

Οι προσαρμοσμένες κεφαλίδες από το endpoint.headers περιλαμβάνονται πάντα αυτούσιες, μαζί με τις ακόλουθες κεφαλίδες με χώρο ονομάτων ThunderPhone:

  • X-ThunderPhone-Signature-V2 — HMAC-SHA256 με χρονική σήμανση για τη μέθοδο, τη διαδρομή, το ερώτημα και το σώμα, με κλειδί το μυστικό webhook του οργανισμού σας. Επαληθεύστε αυτήν την υπογραφή και απορρίψτε αιτήματα παλαιότερα από 5 λεπτά· δείτε Επαλήθευση υπογραφών webhook
  • X-ThunderPhone-Signature — παλαιού τύπου HMAC-SHA256 των ακριβών byte του σώματος αιτήματος, με το ίδιο κλειδί, που εξακολουθεί να αποστέλλεται για υπάρχοντες επαληθευτές
  • X-ThunderPhone-Call-ID — Το αναγνωριστικό της τρέχουσας κλήσης
  • X-ThunderPhone-From-Number και X-ThunderPhone-To-Number — οι αριθμοί From και To της κλήσης σε E.164. Έχουν την ίδια σημασία με τα from_number και to_number στο telephony.complete: σε εξερχόμενη κλήση, το From είναι ο αριθμός του πράκτορά σας και το To είναι το άτομο που καλείται. Ένας αριθμός παραλείπεται όταν η αναγνώριση καλούντος είναι απόκρυφη ή δεν είναι αριθμός τηλεφώνου
  • X-ThunderPhone-Call-Direction — inbound ή outbound, ώστε να μπορείτε να προσδιορίσετε ποιος αριθμός ανήκει στον πελάτη

Οι κεφαλίδες αριθμών κλήσης αποστέλλονται μόνο σε τηλεφωνικές κλήσεις. Οι δοκιμές ιστού, widget, πραγματικού χρόνου και ομιλίας στο πρόγραμμα περιήγησης δεν έχουν αριθμό τηλεφώνου και τις παραλείπουν. Οι δοκιμαστικές κλήσεις από το πρόγραμμα επεξεργασίας πράκτορα και οι προσομοιώσεις AI μεταφέρουν τον προσομοιωμένο αριθμό του καλούντος. Οι υπογραφές δεν καλύπτουν κεφαλίδες: η V2 υπογράφει τη χρονική σήμανση, τη μέθοδο, τη διαδρομή, το ερώτημα και το σώμα. Αν χρειάζεστε υπογεγραμμένους αριθμούς, διαβάστε τους από το σώμα: η μορφή αιτήματος retell περιλαμβάνει και τους τρεις, ενώ η vapi περιλαμβάνει τον αριθμό του πελάτη.

Το Content-Type: application/json ορίζεται εκτός αν το endpoint.headers το παρακάμπτει — ένα προσαρμοσμένο Content-Type υπερισχύει.

Μορφή αιτήματος

Κάθε σύνδεση API διαθέτει ρύθμιση request_format. Επιλέξτε vapi ή retell όταν ένα εισαγόμενο εργαλείο πρέπει να συνεχίσει να καλεί ένα endpoint που έχει δημιουργηθεί για αυτή την πλατφόρμα. Οι νέες και οι υπάρχουσες συνδέσεις χρησιμοποιούν από προεπιλογή το standard.

Για POST / PUT / PATCH, το ThunderPhone σειριοποιεί το επιλεγμένο περιτύλιγμα κανονικά (ταξινομημένα κλειδιά, συμπαγείς διαχωριστές). Και οι δύο υπογραφές καλύπτουν ακριβώς αυτά τα byte.

Standard

Το standard στέλνει μόνο τα ορίσματα του εργαλείου, χωρίς περιτύλιγμα. Αυτή είναι η προεπιλογή και διατηρεί το αρχικό σώμα αιτήματος του ThunderPhone byte προς byte:

{"date":"2025-01-02","service":"consultation"}

Vapi

vapi στέλνει το μήνυμα διακομιστή tool-calls του Vapi με τη μορφή που τεκμηριώνει το Vapi. Το call.id είναι το αναγνωριστικό κλήσης του ThunderPhone. Στις τηλεφωνικές κλήσεις, το call.customer.number είναι ο αριθμός του άλλου μέρους, όπως στο αντικείμενο κλήσης του Vapi: ο καλών σε εισερχόμενη κλήση, το άτομο που καλείται σε εξερχόμενη κλήση. Παραλείπεται όταν αυτός ο αριθμός είναι απόρρητος ή δεν είναι τηλεφωνικός αριθμός. Το id της κλήσης εργαλείου είναι μοναδικό για την επίκληση και επαναχρησιμοποιείται για την αντιστοίχιση του αποτελέσματος του endpoint. Η κλήση εμφανίζεται και στα toolCallList και toolWithToolCallList, με το function.arguments ως αντικείμενο JSON:

{
  "message": {
    "type": "tool-calls",
    "timestamp": 1725000000123,
    "call": { "id": "987654321" },
    "toolCallList": [
      {
        "id": "call_00112233445566778899aabbccddeeff",
        "type": "function",
        "function": {
          "name": "search_appointments",
          "arguments": { "date": "2025-01-02", "service": "consultation" }
        }
      }
    ],
    "toolWithToolCallList": [
      {
        "type": "function",
        "function": { "name": "search_appointments" },
        "toolCall": {
          "id": "call_00112233445566778899aabbccddeeff",
          "type": "function",
          "function": {
            "name": "search_appointments",
            "arguments": { "date": "2025-01-02", "service": "consultation" }
          }
        }
      }
    ]
  }
}

Πεδία αποκλειστικά του Vapi, όπως τα assistant, artifact και το πλήρες αντικείμενο call, δεν αποστέλλονται.

Επιστρέψτε το περιτύλιγμα απόκρισης του Vapi με το αντίστοιχο ID κλήσης εργαλείου:

{
  "results": [
    {
      "toolCallId": "call_00112233445566778899aabbccddeeff",
      "result": "{\"available_slots\":[\"9:00 AM\",\"2:00 PM\"]}"
    }
  ]
}

Το ThunderPhone δίνει στον AI πράκτορα την αποσυσκευασμένη συμβολοσειρά result. Δέχεται επίσης μια τιμή JSON για συμβατότητα με endpoint που ήδη επιστρέφουν μία. Ένα error στη θέση του result επιστρέφεται στον AI πράκτορα ως σφάλμα εργαλείου. Αν το endpoint επιστρέψει εσφαλμένα διαμορφωμένο ή ασύμβατο περιτύλιγμα Vapi, το ThunderPhone καταγράφει μια προειδοποίηση και επιστρέφει στην τυπική ανάλυση απόκρισης αντί να αποτύχει η κλήση.

Retell

Το retell στέλνει το αίτημα που τεκμηριώνεται για μια προσαρμοσμένη συνάρτηση Retell:

{
  "name": "search_appointments",
  "call": {
    "call_id": "987654321",
    "from_number": "+14155550199",
    "to_number": "+14155550100",
    "direction": "inbound"
  },
  "args": { "date": "2025-01-02", "service": "consultation" }
}

Στις τηλεφωνικές κλήσεις, το αντικείμενο call περιέχει τα call_id, from_number, to_number και direction (inbound ή outbound), τα ονόματα πεδίων που χρησιμοποιεί το αντικείμενο τηλεφωνικής κλήσης του Retell. Αντιστοιχούν στις κεφαλίδες αριθμών κλήσης και, σε αντίθεση με τις κεφαλίδες, καλύπτονται και από τις δύο υπογραφές. Ένας αριθμός που είναι απόρρητος ή δεν είναι αριθμός τηλεφώνου παραλείπεται. Στις δοκιμές ιστού, widget, πραγματικού χρόνου και Μιλήστε στο πρόγραμμα περιήγησης, περιέχει μόνο το call_id. Το ThunderPhone δεν περιλαμβάνει πεδία ειδικά για το Retell που δεν μπορεί να παρέχει αξιόπιστα κατά την αποστολή, όπως τα agent_id, transcript, transcript_object, metadata ή δυναμικές μεταβλητές. Το Retell δέχεται οποιοδήποτε σώμα απόκρισης· το ThunderPhone το προωθεί χρησιμοποιώντας τον τυπικό χειρισμό αποκρίσεων.

Για GET / DELETE, τα ορίσματα αποστέλλονται ως παράμετροι ερωτήματος και το σώμα είναι κενό ανεξάρτητα από το request_format. Η υπογραφή V2 καλύπτει τη συμβολοσειρά ερωτήματος όπως αποστέλλεται· η παλαιού τύπου υπογραφή υπολογίζεται στο κενό σύνολο byte. Δείτε Επαλήθευση υπογραφών webhook.

Απόκριση

Επιστρέψτε μια απόκριση JSON με το αποτέλεσμα του εργαλείου:

{
  "available_slots": ["9:00 AM", "2:00 PM", "4:30 PM"],
  "timezone": "America/Los_Angeles"
}

Η απόκριση μορφοποιείται και παρέχεται στον AI πράκτορα για να συνεχίσει τη συνομιλία. Οι αποκρίσεις που δεν είναι JSON περικλείονται ως {"data": "<text>"}; τα χρονικά όρια και οι αποτυχίες σύνδεσης αναφέρονται στον AI πράκτορα ως σφάλματα, ώστε ο πράκτορας να μπορεί να ζητήσει συγγνώμη και να συνεχίσει αντί να σταματήσει.

Αποστολή σε λειτουργία webhook

Τα εργαλεία χωρίς endpoint αποστέλλονται στο URL παλαιού τύπου webhook του οργανισμού σας ως υπογεγραμμένο αίτημα telephony.tool (τηλεφωνικές κλήσεις) ή web.tool (κλήσεις web). Σε αντίθεση με τις ειδοποιήσεις ελέγχου που παραδίδονται σε endpoint webhook μετά την εκτέλεση, αυτό το αίτημα είναι η εκτέλεση — η απόκρισή σας 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 μεταφέρει το origin_domain αντί για τα from_number / to_number. Απαντήστε με το αποτέλεσμα του εργαλείου ως JSON — με το ίδιο συμβόλαιο απόκρισης όπως στις άμεσες κλήσεις endpoint. Το αίτημα υπογράφεται με το μυστικό webhook του οργανισμού, με αμφότερες τις κεφαλίδες υπογραφής, όπως κάθε άλλο webhook.


Μεγάλες αναμονές: λειτουργία αναμονής και απάντηση αργότερα

Ορισμένα εργαλεία περιμένουν ένα άτομο: έναν διαχειριστή που εγκρίνει μια έκπτωση, έναν ιδιοκτήτη που απαντά σε μια ερώτηση στο Slack. Ορίστε το wait_mode σε "hold" σε αυτά τα εργαλεία.

wait_mode: "updates" (προεπιλογή)wait_mode: "hold"
Τι ακούει ο καλώνΤη γραμμή έναρξης του εργαλείου, έπειτα μια σύντομη γραμμή «ακόμη εργάζομαι» μετά από περίπου 12 δευτ. και άλλη μία περίπου κάθε 15 δευτ.Τη γραμμή έναρξης του εργαλείου, έπειτα μουσική αναμονής έως ότου φτάσει το αποτέλεσμα
Μέγιστο timeout180 δευτ.600 δευτ.
Εκκρεμείς απαντήσειςΜεταβιβάζονται στον πράκτορα ως αποτέλεσμαΤο εργαλείο παραμένει ανοιχτό έως ότου παραδώσετε το αποτέλεσμα

Στη λειτουργία αναμονής, ο πράκτορας λέει μία γραμμή κατά την έναρξη του εργαλείου (με δικά του λόγια ή τη γραμμή έναρξης εργαλείου που έχει οριστεί στον πράκτορα) και έπειτα ο καλών ακούει μουσική αναμονής. Η μουσική χαμηλώνει πριν ο πράκτορας πει το αποτέλεσμα. Ένα εργαλείο που απαντά μέσα σε ένα ή δύο δευτερόλεπτα δεν αναπαράγει καθόλου μουσική. Όταν ο πράκτορας μιλά με ένα τηλεφωνικό μενού ή ένα γραμματοκιβώτιο φωνητικών μηνυμάτων, χρησιμοποιεί προφορικές ενημερώσεις αντί για μουσική, καθώς η μουσική θα μπορούσε να εκληφθεί ως απάντηση. Αυτό περιλαμβάνει μια κλήση που διαπιστώνεται ότι είναι μενού ή γραμματοκιβώτιο κατά τη διάρκεια της αναμονής: η μουσική σταματά και αναλαμβάνουν οι προφορικές ενημερώσεις. Το ίδιο ισχύει για μια κλήση όπου η μουσική δεν μπορεί να αναπαραχθεί.

Αν ο καλών μιλήσει κατά την αναμονή, η μουσική συνεχίζει να παίζει και ο πράκτορας δεν απαντά ακόμη. Ακούει τι είπε ο καλών και απαντά σε αυτό μαζί με το αποτέλεσμα. Ο τερματισμός της κλήσης τερματίζει την κλήση και το ανοιχτό εργαλείο.

Απάντηση αργότερα

Η απάντηση του δικού σας endpoint πρέπει και πάλι να φτάσει εντός 180 δευτ. Για να κρατήσετε τον καλούντα σε αναμονή περισσότερο, απαντήστε αμέσως με ένα εκκρεμές αποτέλεσμα:

{ "status": "pending", "request_id": "ask-4471" }

Το request_id είναι οποιαδήποτε συμβολοσειρά έως 200 χαρακτήρων που αναγνωρίζει αυτό το αίτημα από τη δική σας πλευρά. Ο καλών παραμένει σε αναμονή έως ότου παραδώσετε το αποτέλεσμα για αυτό με POST /v1/calls/{call_id}/tool-results. Το call_id είναι η κεφαλίδα X-ThunderPhone-Call-ID του αιτήματος εργαλείου.

curl -X POST https://api.thunderphone.com/v1/calls/987654321/tool-results \
  -H "Authorization: Bearer sk_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "request_id": "ask-4471",
    "result": { "answer": "Yes, book Tuesday at 10." }
  }'

Ο πράκτορας διαβάζει το result ως την απάντηση του εργαλείου, όπως ακριβώς αν το είχε επιστρέψει το endpoint σας. Αν δεν φτάσει αποτέλεσμα πριν από το timeout του εργαλείου, που μετρά από τη στιγμή κλήσης του εργαλείου, ο πράκτορας ενημερώνεται ότι δεν επέστρεψε απάντηση και προτείνει στον καλούντα επόμενα βήματα, όπως τη λήψη μηνύματος.

Μπορείτε να δημοσιεύσετε το αποτέλεσμα όποτε θέλετε, ακόμη και πριν η εκκρεμής απάντησή σας φτάσει στο ThunderPhone. Ένα 202 σημαίνει ότι η κλήση το αποδέχτηκε: το έλαβε ένα ανοιχτό αίτημα ή το αίτημα του ίδιου του εργαλείου βρίσκεται ακόμη σε εξέλιξη και η εκκρεμής απάντησή του θα το διεκδικήσει. Ένα αποτέλεσμα που δεν διεκδικείται ποτέ από κανένα αίτημα (το endpoint σας απάντησε τότε κάτι άλλο εκτός από pending για αυτό το request_id) απορρίπτεται.

Αν η σύνδεση έχει μετασχηματισμό απόκρισης (κώδικα που ξαναγράφει την απάντηση του endpoint σας πριν τη δει ο πράκτορας), ο μετασχηματισμός εκτελείται στην απάντηση του endpoint σας, πριν το ThunderPhone ελέγξει για εκκρεμή απάντηση, επομένως πρέπει να διατηρεί τα status και request_id σε μια εκκρεμή απάντηση. Δεν εκτελείται σε αποτέλεσμα που δημοσιεύετε αργότερα: ο πράκτορας λαμβάνει αυτό το αποτέλεσμα όπως το στέλνετε.

Ένας πράκτορας πλήρους αμφίδρομης επικοινωνίας δεν έχει μουσική αναμονής ή γραμμές ενημέρωσης, επομένως στις κλήσεις του ένα εργαλείο αναμονής συμπεριφέρεται σαν εργαλείο updates: μια εκκρεμής απάντηση φτάνει στον πράκτορα ως αποτέλεσμα του εργαλείου.

Μια εκκρεμής απάντηση από εργαλείο σε λειτουργία updates δεν διατηρείται ανοιχτή: ο πράκτορας τη λαμβάνει ως αποτέλεσμα του εργαλείου.

Επαλήθευση υπογραφής

Οι άμεσες κλήσεις εργαλείων υπογράφονται με τον ίδιο τρόπο όπως τα webhook, χρησιμοποιώντας ως κλειδί το μυστικό webhook του οργανισμού σας:

  • Το X-ThunderPhone-Signature-V2 υπογράφει τη χρονική σήμανση, τη μέθοδο, τη διαδρομή και τις παραμέτρους ερωτήματος όπως απεστάλησαν, καθώς και τις ακριβείς οκτάδες δυαδικών ψηφίων του σώματος. Απορρίψτε αιτήματα των οποίων η χρονική σήμανση απέχει περισσότερο από 5 λεπτά από την ώρα του ρολογιού σας.
  • Το X-ThunderPhone-Signature (παλαιού τύπου) υπογράφει μόνο τις οκτάδες δυαδικών ψηφίων του σώματος, δηλαδή την κενή συμβολοσειρά οκτάδων δυαδικών ψηφίων για GET / DELETE. Εξακολουθεί να αποστέλλεται, χωρίς αλλαγές.

Οι βοηθητικές συναρτήσεις του SDK ελέγχουν την κεφαλίδα V2, συμπεριλαμβανομένου του χρονικού παραθύρου των 5 λεπτών:

Python
import json
 
from fastapi import FastAPI, HTTPException, Request
from thunderphone import verify_signature
 
app = FastAPI()
 
@app.post("/appointments/search")
async def search_appointments(request: Request):
    body = await request.body()
    query = request.scope.get("query_string", b"").decode("latin-1")
    path = request.url.path + (f"?{query}" if query else "")
 
    if not verify_signature(
        request.headers.get("X-ThunderPhone-Signature-V2"),
        secret=WEBHOOK_SECRET,
        method=request.method,
        path=path,
        body=body,
    ):
        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}
Node.js
import express from "express";
import { verifySignature } from "@thunderphone/sdk";
 
app.post('/appointments/search', express.raw({type: 'application/json'}), (req, res) => {
  const ok = verifySignature({
    header: req.header('X-ThunderPhone-Signature-V2'),
    secret: WEBHOOK_SECRET,
    method: req.method,
    path: req.originalUrl,
    body: req.body,
  });
  if (!ok) 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 });
});

Πλήρεις οδηγίες — η υπογεγραμμένη συμβολοσειρά, ένα ολοκληρωμένο παράδειγμα, κώδικας χωρίς το SDK, η περίπτωση GET / DELETE και η επισήμανση για την απουσία μυστικού — βρίσκονται στην ενότητα Επαλήθευση υπογραφών 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" }
      }
    }
  ]
}

Εκτέλεση εργαλείου στην αρχή της κλήσης

Ένα εργαλείο μπορεί επίσης να εκτελείται αυτόματα στην αρχή κάθε τηλεφωνικής κλήσης, πριν ο πράκτορας πει την πρώτη του λέξη, ώστε ο χαιρετισμός να μπορεί να χρησιμοποιεί το αποτέλεσμα. Η συνήθης περίπτωση είναι μια αναζήτηση σε CRM με βάση τον αριθμό του καλούντος: «Καλώς ήρθατε ξανά, Arthi! Θα θέλατε τη συνηθισμένη σας παραγγελία;»

Στον πίνακα ελέγχου, ανοίξτε τη σύνδεση API και ορίστε το Πότε εκτελείται σε Στην αρχή κάθε τηλεφωνικής κλήσης, έπειτα συμπληρώστε την τιμή που λαμβάνει κάθε παράμετρος. Μέσω του API, ορίστε το trigger της ενσωμάτωσης σε call_start και το call_start_arguments της (Συνδέσεις API), ή προσθέστε ένα μπλοκ call_start σε ένα ενσωματωμένο εργαλείο:

{
  "type": "function",
  "function": {
    "name": "get_contact_by_phone",
    "description": "Look up a customer by phone number.",
    "parameters": {
      "type": "object",
      "properties": {
        "business_id": {"type": "string"},
        "phone_number": {"type": "string"}
      },
      "required": ["business_id", "phone_number"]
    }
  },
  "endpoint": {"url": "https://crm.example.com/contacts/lookup"},
  "call_start": {
    "arguments": {
      "business_id": "a0a81c23",
      "phone_number": "{{caller_number}}"
    }
  }
}

Τα ορίσματα χρειάζονται μια τιμή για κάθε υποχρεωτική παράμετρο, καθώς κανείς δεν συμπληρώνει τίποτα κατά την έναρξη της κλήσης. Οι τιμές είναι συμβολοσειρές, αριθμοί ή τιμές boolean. Αποθηκεύονται και επιστρέφονται ως απλό κείμενο και ο πράκτορας τις βλέπει, επομένως διατηρείτε μυστικά, όπως κλειδιά API, στις κεφαλίδες της σύνδεσης και όχι εδώ. Οι συμβολοσειρές μπορούν να χρησιμοποιούν αυτά τα σύμβολα κράτησης θέσης:

Σύμβολο κράτησης θέσηςΤιμή
{{caller_number}}Το άλλο άτομο στην κλήση σε μορφή E.164, π.χ. +61402122887: ο καλών σε εισερχόμενη κλήση, το άτομο που καλείται σε εξερχόμενη κλήση
{{caller_number_national}}Ο ίδιος αριθμός στην εθνική μορφή της χώρας του χωρίς κενά, π.χ. 0402122887
{{agent_number}}Ο αριθμός του ίδιου του πράκτορα

Τρόπος λειτουργίας:

  • Το αίτημα είναι το ίδιο με εκείνο που στέλνουν οι κλήσεις του εργαλείου του ίδιου του πράκτορα (ίδιο endpoint, κεφαλίδες, μορφή αιτήματος και υπογραφή).
  • Το εργαλείο ξεκινά όταν ξεκινά η κλήση και εκτελείται ενώ αναπαράγεται οποιοσδήποτε τόνος σύνδεσης, εισαγωγικό μήνυμα ή ειδοποίηση εγγραφής. Ο χαιρετισμός περιμένει το αποτέλεσμα για έως περίπου 3 δευτερόλεπτα από εκείνο το σημείο. Ένα πιο αργό αποτέλεσμα δίνεται στον πράκτορα μόλις φτάσει, για το υπόλοιπο της κλήσης. Σε εξερχόμενη κλήση ξεκινά όταν πραγματοποιείται η κλήση, επομένως εκτελείται σε κάθε προσπάθεια, συμπεριλαμβανομένων εκείνων στις οποίες δεν απαντά κανείς.
  • Σε έναν πράκτορα όπου ο καλών μιλά πρώτος, δεν υπάρχει χαιρετισμός που να περιμένει· ο πράκτορας λαμβάνει το αποτέλεσμα μόλις φτάσει.
  • Το αποτέλεσμα δίνεται στον πράκτορα ως πλαίσιο για ολόκληρη την κλήση. Ενημερώστε τον πράκτορα στο prompt σας για τον τρόπο χρήσης του· διαφορετικά δεν εκφωνείται.
  • Αν το εργαλείο αποτύχει ή λήξει το χρονικό όριο, ο πράκτορας χαιρετά τον καλούντα όπως θα έκανε συνήθως και δεν αναφέρει τίποτα σχετικά με αυτό.
  • Ο πράκτορας μπορεί ακόμη να καλέσει το εργαλείο ο ίδιος αργότερα στην κλήση.
  • Εκτελείται σε τηλεφωνικές κλήσεις, συμπεριλαμβανομένων δοκιμαστικών κλήσεων από τον πίνακα ελέγχου προς το τηλέφωνό σας, και σε προσομοιώσεις AI, οι οποίες στέλνουν τον αριθμό του προσομοιωμένου καλούντος στο endpoint σας. Δεν εκτελείται σε δοκιμές Μιλήστε στο πρόγραμμα περιήγησης ή σε συνεδρίες widget ιστού, που δεν έχουν αριθμό καλούντος, σε κλήσεις στις οποίες η αναγνώριση κλήσης είναι απόρρητη ή σε πράκτορες με βήματα.
  • Ένας πράκτορας εκτελεί το πολύ τρία εργαλεία έναρξης κλήσης, όλα ταυτόχρονα.

Αναφέρετε το αποτέλεσμα στο prompt σας, ώστε ο πράκτορας να γνωρίζει πώς να το χρησιμοποιήσει, για παράδειγμα: «Αν η αναζήτηση κατά την έναρξη της κλήσης βρήκε τον καλούντα, χαιρετήστε τον με το μικρό του όνομα.»


Βέλτιστες πρακτικές

Γράψτε σαφείς περιγραφές

Το πεδίο description βοηθά τον AI πράκτορα να κατανοήσει πότε να χρησιμοποιεί το εργαλείο. Περιγράψτε συγκεκριμένα τι κάνει και πότε είναι κατάλληλο.

Χειριστείτε τα σφάλματα ομαλά

Επιστρέφετε μηνύματα σφάλματος που μπορεί να κατανοήσει ο AI πράκτορας: {"error": "No slots available for that date"} αντί για γενικά σφάλματα 500.

Διατηρήστε τις αποκρίσεις σύντομες

Επιστρέψτε μόνο ό,τι χρειάζεται ο AI πράκτορας για να συνεχίσει τη συνομιλία. Ένα αποτέλεσμα εργαλείου παραμένει στη συνομιλία και διαβάζεται ξανά σε κάθε επόμενο γύρο, επομένως ένα μεγάλο αποτέλεσμα αυξάνει το κόστος και την καθυστέρηση για το υπόλοιπο της κλήσης. Αποτελέσματα άνω των 100.000 χαρακτήρων περικόπτονται σε μια προεπισκόπηση που ο AI πράκτορας γνωρίζει ότι είναι ελλιπής και, σε μια πολύ μεγάλη κλήση, παλαιότερα αποτελέσματα μπορεί να αφαιρεθούν (ο AI πράκτορας μπορεί να καλέσει ξανά το εργαλείο). Προσθέστε μια παράμετρο ώστε ο AI πράκτορας να μπορεί να αναζητά ένα στοιχείο ή κατηγορία κάθε φορά και τοποθετήστε μεγάλο περιεχόμενο αναφοράς, όπως μενού ή καταλόγους, σε μια βάση γνώσεων. Η επιλογή Αποστολή δοκιμαστικού αιτήματος στον πίνακα ελέγχου εμφανίζει το μέγεθος κάθε αποτελέσματος και προειδοποιεί όταν είναι μεγάλο.

Χρησιμοποιήστε συνετά τα υποχρεωτικά πεδία

Επισημαίνετε τα πεδία ως required μόνο όταν είναι πραγματικά απαραίτητο. Ο AI πράκτορας θα ζητήσει από τον χρήστη τις απαιτούμενες πληροφορίες πριν καλέσει το εργαλείο.


Σχετικά