Open in
telephony.incoming / web.incoming
Webhook αποκλεισμού που διαμορφώνει τη ρύθμιση μιας εισερχόμενης κλήσης σε πραγματικό χρόνο.
Όταν μια εισερχόμενη τηλεφωνική κλήση φτάνει σε έναν αριθμό χωρίς
εκχωρημένο πράκτορα (δείτε τις Επανακλήσεις για καλούντες που επιστρέφουν τις
εξερχόμενες κλήσεις σας), ή όταν ξεκινά μια συνεδρία γραφικού στοιχείου ιστού με δημοσιεύσιμο κλειδί σε
mode="webhook", το ThunderPhone στέλνει ένα δεσμευτικό
αίτημα telephony.incoming / web.incoming στο
παλαιού τύπου URL webhook
σας και αναμένει απάντηση διαμόρφωσης: έως 13 δευτερόλεπτα για μια
τηλεφωνική κλήση, συμπεριλαμβανομένης μίας επανάληψης, και έως 10 δευτερόλεπτα για μια συνεδρία
γραφικού στοιχείου (δείτε τα Χρονικά όρια και επαναλήψεις). Χρησιμοποιήστε αυτή την
ανταλλαγή για να επιλέγετε δυναμικά προτροπή, φωνή και εργαλεία ανά κλήση —
δείτε τον οδηγό δυναμικής διαμόρφωσης κλήσεων
για το ολοκληρωμένο μοτίβο.
Ένας αριθμός με εκχωρημένο πράκτορα απαντά με τον συγκεκριμένο πράκτορα. Όταν ο πράκτορας έχει το δικό του webhook ρύθμισης κλήσης, η ίδια δεσμευτική ανταλλαγή εκτελείται πρώτα, στη διεύθυνση URL του πράκτορα, για να συμπληρωθούν οι μεταβλητές του πράκτορα και το περιβάλλον της κλήσης.
Χρονικά όρια και επαναλήψεις
Απαντήστε γρήγορα: ο καλών περιμένει στη γραμμή ενώ αποφασίζετε.
Για μια τηλεφωνική κλήση (telephony.incoming):
- Η πρώτη προσπάθεια μπορεί να διαρκέσει έως 10 δευτερόλεπτα.
- Αν λήξει το χρονικό όριο, δεν μπορεί να συνδεθεί ή λάβει απόκριση
5xx,408ή429, το ThunderPhone προσπαθεί άλλη μία φορά. Η επανάληψη λαμβάνει ό,τι απομένει από έναν προϋπολογισμό 13 δευτερολέπτων για ολόκληρη την ανταλλαγή: περίπου 3 δευτερόλεπτα μετά από μια πρώτη προσπάθεια της οποίας έληξε το χρονικό όριο, σχεδόν και τα 13 μετά από μια γρήγορη αποτυχία. Δεν γίνεται επανάληψη όταν θα απέμεναν λιγότερα από 2 δευτερόλεπτα. - Κάθε άλλη απόκριση
4xx, μια απόκριση που υπερβαίνει το όριο μεγέθους, ή μια2xxτης οποίας το σώμα δεν είναι έγκυρη διαμόρφωση είναι οριστική και δεν επαναλαμβάνεται. - Και οι δύο προσπάθειες στέλνουν το ίδιο σώμα, την ίδια κεφαλίδα
X-ThunderPhone-Signatureκαι την ίδια κεφαλίδαX-ThunderPhone-Idempotency-Key(telephony-incoming-<call_id>), ώστε ένας χειριστής με παρενέργειες να μπορεί να αναγνωρίσει την επανάληψη.
Εάν δεν ληφθεί χρησιμοποιήσιμη διαμόρφωση, η κλήση τερματίζεται αμέσως
αντί να παραμείνει ο καλών σε σιωπηλή γραμμή. Εμφανίζεται στο ιστορικό
κλήσεων ως αποτυχημένη κλήση χωρίς χρέωση με end_reason
inbound_config_webhook_failed και αποστέλλεται το συνήθες συμβάν
telephony.complete. Η σελίδα της κλήσης στον
πίνακα ελέγχου και το config_webhook_failure στο
GET /v1/calls/{call_id} αναφέρουν τι έκανε η
διαδικτυακή ειδοποίησή σας: {kind, attempts, http_status, host, source}, όπου
το kind είναι http_error, timeout, connection, dns, tls, response_too_large,
blocked_url, other, invalid_json, non_object_json ή
invalid_config, το host είναι το όνομα κεντρικού υπολογιστή της διαδικτυακής
ειδοποίησής σας και το source είναι number (αυτή η διαδικτυακή ειδοποίηση)
ή agent_setup (διαδικτυακή ειδοποίηση ρύθμισης κλήσης ενός πράκτορα).
Για το invalid_config, το reason αναφέρει γιατί δεν μπορούσε να χρησιμοποιηθεί
η απόκριση και το fields ονομάζει τα πεδία στα οποία αναφέρεται: no_agent
(ούτε agent_id ούτε prompt; το fields παραθέτει τα κλειδιά που αγνοήθηκαν,
όπως ένα agentId με ορθογραφικό λάθος), agent_not_found,
agent_id_not_integer, unexpected_fields (κλειδιά εκτός από variables,
context, timezone και language δίπλα στο agent_id), invalid_variables,
invalid_context, invalid_language, unsupported_language,
invalid_config_fields ή agent_settings_invalid. Διαφορετικά, το reason
είναι null και το fields είναι κενό. Η μόνη εξαίρεση είναι ένας καλών που
επιστρέφει μία από τις εξερχόμενες κλήσεις σας όταν απέτυχε η ίδια η ανταλλαγή:
δείτε Επανακλήσεις.
Μια συνεδρία widget (web.incoming) λαμβάνει μία μόνο προσπάθεια έως 10
δευτερολέπτων. Αν αποτύχει, το αίτημα συνεδρίας αποτυγχάνει με 502 ή 422.
Ωφέλιμο φορτίο αιτήματος
Για τηλεφωνικές κλήσεις (telephony.incoming):
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567"
}
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
call_id | ακέραιος | Αναγνωριστικό κλήσης — σταθερό σε όλα τα συμβάντα για αυτή την κλήση |
from_number | συμβολοσειρά | Αριθμός καλούντος E.164 |
to_number | συμβολοσειρά | Προορισμός E.164 (ένας από τους αριθμούς σας στο ThunderPhone) |
returning_call | αντικείμενο | Παρόν μόνο όταν αυτός ο αριθμός κάλεσε τον καλούντα τις τελευταίες 30 ημέρες. Δείτε Επανακλήσεις |
sip_headers | αντικείμενο | Παρόν μόνο όταν η κλήση έφτασε μέσω μη αυτόματης σύνδεσης SIP με κεφαλίδες SIP X-* ή User-to-User: όνομα κεφαλίδας με πεζά γράμματα → τιμή. Δείτε Κεφαλίδες SIP |
Για συνεδρίες γραφικού στοιχείου ιστού (web.incoming), το data αναγνωρίζει τη
σελίδα ενσωμάτωσης αντί για τηλεφωνικούς αριθμούς:
{
"type": "web.incoming",
"data": {
"call_id": 987654322,
"origin_domain": "https://example.com",
"publishable_key_prefix": "pk_live_a1b2"
}
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
call_id | integer | Αναγνωριστικό κλήσης |
origin_domain | string | Η προέλευση της σελίδας που φιλοξενεί το στοιχείο, όπως την έστειλε το πρόγραμμα περιήγησης. Ένας πελάτης εκτός προγράμματος περιήγησης μπορεί να στείλει οποιαδήποτε τιμή, επομένως μην τη θεωρείτε απόδειξη της προέλευσης του αιτήματος |
publishable_key_prefix | string | Πρώτοι χαρακτήρες του δημοσιεύσιμου κλειδιού που άνοιξε τη συνεδρία |
language, primary_language | string | Υπάρχει όταν η συνεδρία του στοιχείου ζήτησε παράκαμψη γλώσσας |
voice | string | Υπάρχει όταν η συνεδρία του στοιχείου ζήτησε παράκαμψη φωνής |
website_context | string | Υπάρχει όταν το στοιχείο πέρασε περιεχόμενο σελίδας ανά συνεδρία |
Τα πεδία παράκαμψης (language, voice, website_context και τυχόν
variables του προγράμματος περιήγησης) φτάνουν μόνο όταν το δημοσιεύσιμο κλειδί τα επιτρέπει στις
παρακάμψεις προγράμματος περιήγησης. Ένα
αίτημα συνεδρίας που περιέχει παράκαμψη την οποία δεν επιτρέπει το κλειδί απορρίπτεται πριν
κληθεί αυτό το webhook.
Σχήμα απόκρισης
Επιστρέψτε ένα αντικείμενο JSON που περιγράφει τη διαμόρφωση του πράκτορα για αυτή την κλήση.
Τα prompt και voice είναι υποχρεωτικά· όλα τα υπόλοιπα είναι προαιρετικά.
{
"prompt": "You are a helpful booking assistant for Acme Restaurant.",
"voice": "john",
"product": "spark",
"background_track": null,
"tools": []
}| Πεδίο | Τύπος | Απαιτείται | Περιγραφή |
|---|---|---|---|
prompt | συμβολοσειρά | ναι | Προτροπή συστήματος που καθοδηγεί τον πράκτορα |
voice | συμβολοσειρά | ναι | Αναγνωριστικό φωνής από GET /v1/voices, π.χ. john. Το voice_name γίνεται δεκτό ως ψευδώνυμο. Άγνωστες φωνές αποτυγχάνουν στην επικύρωση και η κλήση απορρίπτεται |
product | συμβολοσειρά | όχι | Στείλτε bolt. Η προεπιλογή είναι spark, μια παλαιότερη τιμή που εξακολουθεί να γίνεται δεκτή μαζί με τις storm-base, storm-base-with-ack, storm-extra και storm-extra-with-ack |
thinking_level | συμβολοσειρά | όχι | minimal, base (προεπιλογή) ή extra. Στις παλαιότερες τιμές προϊόντος storm-*, το storm-extra* επιβάλλει το extra και τα άλλα storm-* επιβάλλουν το base |
audio_context_mode | συμβολοσειρά | όχι | full (προεπιλογή) ή reduced |
watchdog_enabled | λογική τιμή | όχι | Ενεργοποιήστε την επίβλεψη για αυτή την κλήση. Προεπιλογή: false |
additional_audio_context | λογική τιμή | null | όχι | Συμπεριλάβετε τις τελευταίες λίγες εναλλαγές ήχου του καλούντος αντί μόνο την πιο πρόσφατη, βελτιώνοντας τις διορθώσεις και τη συλλογή δεδομένων με έμφαση στην ορθογραφία ή στους αριθμούς, με μικρή επιβάρυνση λανθάνουσας καθυστέρησης/κόστους. Ενεργοποιείται από προεπιλογή για εισερχόμενες συνεδρίες και απενεργοποιείται για εξερχόμενες τηλεφωνικές κλήσεις· το null διατηρεί την προεπιλογή |
storm_feedback_mode | συμβολοσειρά | όχι | none, acknowledgement (προεπιλογή) ή tick: τι ακούει ο καλών ενώ διαμορφώνεται μια πιο αργή απάντηση όταν το audio_tier είναι plus ή max |
language | συμβολοσειρά | όχι | Συντομογραφία για το primary_language. Επιτρέπεται επίσης δίπλα στο agent_id, όπου είναι η γλώσσα στην οποία ξεκινά αυτή η κλήση, με τη φωνή του πράκτορα για αυτήν· δείτε Ορισμός της γλώσσας ανά κλήση |
primary_language | συμβολοσειρά | όχι | Κωδικός γλώσσας, κανονικοποιημένος (προεπιλογή en). Κωδικοί που δεν μπορούν να επιλυθούν απορρίπτουν την κλήση |
has_additional_languages | λογική τιμή | όχι | Προεπιλογή: false |
additional_languages | πίνακας συμβολοσειρών | όχι | Πρόσθετες γλώσσες στις οποίες μπορεί να αλλάξει ο πράκτορας |
native_voice_switching | λογική τιμή | όχι | Προεπιλογή: false. Όταν η κλήση αλλάζει σε άλλη γλώσσα, αλλάζει σε φωνή φυσικού ομιλητή αυτής της γλώσσας (αντιστοιχισμένη κατά φύλο) αντί να διατηρεί τη διαμορφωμένη φωνή |
language_switching | συμβολοσειρά | null | όχι | ask_first (προεπιλογή) ή follow_caller· το null είναι το ίδιο με το ask_first. Πώς ένας πολύγλωσσος πράκτορας χειρίζεται το άλλο άτομο όταν μιλά μία από τις άλλες γλώσσες του. Το ask_first αλλάζει αμέσως όταν ζητούν τη γλώσσα ή λένε μια πλήρη πρόταση σε αυτήν, και ρωτά αν θέλουν να συνεχίσουν σε αυτήν μετά από κάτι σύντομο, όπως ένα «ναι». Το follow_caller αλλάζει σε οποιαδήποτε διαμορφωμένη γλώσσα μιλούν, ακόμη και για μία μόνο λέξη. Ισχύει μόνο όταν έχει οριστεί το additional_languages |
audio_tier | συμβολοσειρά | null | όχι | Μόνο για product: "bolt". Ακρόαση: πόσο προσεκτικά ακούει ο πράκτορας τον καλούντα. Το standard (προεπιλογή· το "" και το null σημαίνουν το ίδιο) είναι κατάλληλο για τις περισσότερες κλήσεις (οι κλήσεις που επεξεργάζονται PHI χρησιμοποιούν μόνο παρόχους που καλύπτονται από BAA). Το lite είναι το φθηνότερο και παρερμηνεύει συχνότερα. Το plus ακούει πιο προσεκτικά σε δύσκολες εναλλαγές, οι οποίες διαρκούν περίπου 1–2 δευτερόλεπτα περισσότερο. Το max είναι για τον δυσκολότερο ήχο και σπάνιες γλώσσες· κάθε απάντηση διαρκεί 3–4 δευτερόλεπτα και η κλήση εκτελεί νοημοσύνη pro (το intelligence αγνοείται). Το max δεν είναι γενικά διαθέσιμο: για έναν οργανισμό για τον οποίο δεν έχει ενεργοποιηθεί, η κλήση εκτελεί plus και το intelligence που ορίζετε (ένα αίτημα εξερχόμενης κλήσης με αυτό απορρίπτεται με 400). Οι παλαιότερες τιμές lean (Lite), hearing (Plus) και deep_hearing (Max) εξακολουθούν να γίνονται δεκτές. Άλλα προϊόντα το αγνοούν |
endpointing | συμβολοσειρά | null | όχι | faster (200 ms), fast (300 ms), normal (500 ms, προεπιλογή) ή patient (800 ms)· το null είναι το ίδιο με το normal. Για πόσο περιμένει ένας πράκτορας Bolt v2 αφού σταματήσει ο καλών πριν ζητήσει απάντηση από το μοντέλο. Οι μικρότερες αναμονές μπορούν να απαντήσουν νωρίτερα, αλλά στέλνουν περισσότερα αιτήματα που οι επόμενες λέξεις του καλούντος καθιστούν παρωχημένα, αυξάνοντας το κόστος του μοντέλου. Άλλα προϊόντα το αγνοούν |
eagerness | συμβολοσειρά | null | όχι | Καταργημένο: το όνομα του endpointing έως τις 19 Οκτωβρίου 2026, εξακολουθεί να διαβάζεται. Αγνοείται όταν έχει οριστεί το endpointing |
intelligence | συμβολοσειρά | null | όχι | core ή pro (προεπιλογή)· το null είναι το ίδιο με το pro. Πόσο αξιόπιστα ένας πράκτορας bolt στη διοχέτευση Bolt v2 ακολουθεί τις οδηγίες του. Το core χρειάζεται ~700 ms έως την πρώτη λέξη, είναι το φθηνότερο και ελαφρώς λιγότερο αξιόπιστο (σε κλήσεις που αντιμετωπίζονται ως PHI, ~900 ms και λιγότερο αξιόπιστο)· το pro χρειάζεται ~900 ms· απαντήσεις Core που θα καλούσαν μόνο ένα εργαλείο ανατίθενται στο Pro. Οι παλαιότερες τιμές lite (Core) και standard (Pro) εξακολουθούν να γίνονται δεκτές, ενώ τα αποσυρμένα plus και max εκτελούνται σε pro. Αγνοείται όταν το audio_tier είναι max. Άλλα προϊόντα το αγνοούν |
faster_replies | λογική τιμή | null | όχι | Επιτάχυνση. Προεπιλογή: true. Σε έναν πράκτορα bolt στη διοχέτευση Bolt v2, οι απαντήσεις ξεκινούν λίγο νωρίτερα, με λίγο μεγαλύτερο κόστος. Το false το απενεργοποιεί. Άλλα προϊόντα το αγνοούν |
background_track | συμβολοσειρά | null | όχι | Αναγνωριστικό ήχου περιβάλλοντος ή null |
acknowledgement_prompt_mode | συμβολοσειρά | όχι | auto (προεπιλογή) ή manual (παλαιότερες τιμές προϊόντος -with-ack) |
acknowledgement_prompt | συμβολοσειρά | όχι | Χρησιμοποιείται όταν acknowledgement_prompt_mode="manual" |
silence_interval_seconds | ακέραιος | null | όχι | 5–120. Δευτερόλεπτα σιωπής του καλούντος πριν από έναν έλεγχο |
silence_max_checkins | ακέραιος | null | όχι | 1–10 |
silence_checkins_enabled | λογική τιμή | όχι | Προεπιλογή: true |
silence_final_action | συμβολοσειρά | όχι | Μετά τον τελευταίο έλεγχο: hang_up (προεπιλογή) ή transfer προς το silence_transfer_destination |
silence_transfer_destination | συμβολοσειρά | όχι | Όνομα μιας καταχώρισης στο transfer_destinations αυτής της διαμόρφωσης· απαιτείται με το transfer. Χωρίς transfer_destinations, η μεταφορά δεν μπορεί να πραγματοποιηθεί και ο πράκτορας τερματίζει την κλήση |
silence_final_message | συμβολοσειρά | όχι | ≤ 300 χαρακτήρες, διαβάζεται όπως έχει γραφτεί· το "" (προεπιλογή) χρησιμοποιεί την προεπιλεγμένη φράση |
connect_tone_enabled | λογική τιμή | όχι | Προεπιλογή: false |
pronunciation_dicts | λογική τιμή | null | όχι | Προεπιλογή: false· το null είναι το ίδιο με το false. Όταν είναι true, η ομιλία Cartesia της κλήσης χρησιμοποιεί το λεξικό προφοράς του ThunderPhone για τη γλώσσα της κλήσης, όπου υπάρχει. Λειτουργεί για τηλεφωνικές κλήσεις και κλήσεις γραφικού στοιχείου. Ισχύει μόνο για τις φωνές Cartesia του ίδιου του ThunderPhone, όχι για φωνές στο δικό σας κλειδί API Cartesia. Δεν χρησιμοποιείται με το agent_id, όπου εφαρμόζονται οι ρυθμίσεις του αποθηκευμένου πράκτορα |
words | πίνακας | null | όχι | Πώς ο πράκτορας προφέρει συγκεκριμένες λέξεις, οι ίδιες καταχωρίσεις με τα words ενός πράκτορα χωρίς το support. Μια καταχώριση χωρίς language λαμβάνει τη γλώσσα αυτής της διαμόρφωσης. Τα null και [] σημαίνουν καμία. Δεν χρησιμοποιείται με το agent_id, όπου εφαρμόζονται οι λέξεις του αποθηκευμένου πράκτορα |
voicemail_action | συμβολοσειρά | όχι | prompt (προεπιλογή), hangup ή message |
voicemail_message | συμβολοσειρά | όχι | Χρησιμοποιείται όταν voicemail_action="message" |
agent_name | συμβολοσειρά | όχι | Εμφανιζόμενο όνομα που αναφέρεται στους πίνακες ελέγχου και στο γραφικό στοιχείο |
org_name | συμβολοσειρά | όχι | Εμφανιζόμενο όνομα οργανισμού για την περσόνα του πράκτορα |
tools | πίνακας | όχι | Ενσωματωμένα σχήματα εργαλείων συναρτήσεων (δείτε Εργαλεία συναρτήσεων) |
transfer_destinations | πίνακας αντικειμένων | null | όχι | Έως 50 καταχωρίσεις {name, number} προς τις οποίες μπορεί να μεταφέρει αυτή η κλήση, επικυρωμένες όπως οι αριθμοί μεταφοράς ενός πράκτορα. Ο πράκτορας μεταφέρει βάσει ονόματος και μόνο σε αυτές· το [] σημαίνει καμία μεταφορά. Παραλείψτε το ή στείλτε null για να επιτρέψετε στον πράκτορα να μεταφέρει σε έναν αριθμό που επιλέγει ο ίδιος |
timezone | συμβολοσειρά | όχι | Ζώνη ώρας IANA για αυτή την κλήση, όπως America/Chicago. Ο πράκτορας αναφέρει την ημερομηνία και την ώρα σε αυτήν, αντί για τη δική του ζώνη ώρας. Επιτρέπεται επίσης δίπλα στο agent_id. Τιμές που δεν είναι ζώνες IANA αγνοούνται. Δείτε Ορισμός της ζώνης ώρας ανά κλήση |
context | συμβολοσειρά | null | όχι | Κείμενο ελεύθερης μορφής για αυτή την κλήση, όπως σημειώσεις που συνέλεξε το σύστημά σας, έως 20.000 χαρακτήρες. Προστίθεται μετά την προτροπή σε οριοθετημένο μπλοκ και δεν αποδίδεται ως πρότυπο. Επιτρέπεται επίσης δίπλα στο agent_id. Μια τιμή που δεν είναι συμβολοσειρά ή είναι μεγαλύτερη απορρίπτει την κλήση. Δείτε μεταβλητές κλήσης και περιβάλλον |
call_id | ακέραιος | όχι | Προαιρετική επανάληψη του αναγνωριστικού κλήσης του αιτήματος· αγνοείται |
Επειδή τα prompt και voice είναι υποχρεωτικά, η επιστροφή του {} ή οποιασδήποτε απάντησης που αποτυγχάνει στην επικύρωση απορρίπτει την κλήση: μια τηλεφωνική κλήση τερματίζεται όπως περιγράφεται στα Χρονικά όρια και επαναλήψεις, και ένα αίτημα συνεδρίας widget αποτυγχάνει με 422. Αυτό ισχύει και για καλούντες που επιστρέφουν: οποιοδήποτε αντικείμενο JSON επιστρέφει το webhook σας είναι η απάντησή του και το {} είναι ο τρόπος απόρριψης μιας κλήσης.
Webhook ρύθμισης κλήσης πράκτορα
Ένας πράκτορας μπορεί να έχει το δικό του webhook ρύθμισης κλήσης: το πεδίο
Webhook ρύθμισης κλήσης στις ρυθμίσεις του ή το
call_setup_webhook_url
στο API. Αναθέστε τον πράκτορα σε έναν αριθμό και, πριν από κάθε εισερχόμενη κλήση
σε αυτόν τον αριθμό που απαντά ο πράκτορας, το ThunderPhone ζητά από το webhook τις
μεταβλητές και το περιεχόμενο της συγκεκριμένης κλήσης. Ο αριθμός διατηρεί τον πράκτορά του, ώστε η σελίδα αριθμών τηλεφώνου και η σελίδα του πράκτορα να εμφανίζουν ποιος πράκτορας απαντά σε αυτόν.
Είναι ρύθμιση όπως οι υπόλοιπες του πράκτορα: αποθηκεύεται ως πρόχειρο, δημοσιεύεται κατά την
ανάπτυξη και διατηρείται στο ιστορικό εκδόσεων. Ένας αριθμός
καρφιτσωμένος σε παλαιότερη έκδοση
ζητά το URL αυτής της έκδοσης. Τα αιτήματα υπογράφονται με το δικό του
πράκτορα call_setup_webhook_signing_secret (όχι με το μυστικό webhook του οργανισμού),
με την ίδια κεφαλίδα X-ThunderPhone-Signature, χρονικά όρια,
επανάληψη και κλειδί ιδιομορφίας όπως παραπάνω. Το μυστικό είναι
μόνο για εγγραφή: ορίστε ένα που ελέγχει το τελικό σημείο σας (στις ρυθμίσεις του πράκτορα ή με
PATCH /v1/agents/{id})· καμία ανάγνωση δεν το επιστρέφει και το
call_setup_webhook_signing_secret_set δηλώνει αν έχει οριστεί.
Το αίτημα είναι το παραπάνω ωφέλιμο φορτίο telephony.incoming μαζί με τον πράκτορα που
συμπληρώνει:
{
"type": "telephony.incoming",
"data": {
"call_id": 987654321,
"from_number": "+14155550199",
"to_number": "+15551234567",
"variables": null,
"agent": {
"id": 12,
"name": "Front desk",
"version": 7,
"version_pinned": false
}
}
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
agent.id | integer | Ο πράκτορας που έχει ανατεθεί στον αριθμό |
agent.name | string | Το όνομά του |
agent.version | integer | null | Ο αριθμός της έκδοσης που θα απαντήσει: η καρφιτσωμένη έκδοση του αριθμού, διαφορετικά η πιο πρόσφατη δημοσιευμένη έκδοση του πράκτορα (null αν δεν έχει) |
agent.version_pinned | boolean | Αν ο αριθμός είναι καρφιτσωμένος σε αυτή την έκδοση |
Απαντήστε με ό,τι χρειάζεται η κλήση. Οποιοδήποτε από τα παρακάτω συμπληρώνει τον ανατεθειμένο πράκτορα, στην έκδοση του αριθμού:
{"variables": {...}},{"context": "..."}, ή και τα δύο- το ίδιο με το
"agent_id"ορισμένο στο αναγνωριστικό του ανατεθειμένου πράκτορα {}: ο πράκτορας απαντά χωρίς να έχει συμπληρωθεί τίποτα
Τα timezone και language επιτρέπονται επίσης, όπως δίπλα σε ένα
agent_id. Οι μεταβλητές συμπληρώνουν τα
{{placeholders}} του πράκτορα· το περιεχόμενο προστίθεται μετά την προτροπή.
Ή αποφασίστε εσείς για την κλήση. Ένα agent_id άλλου πράκτορα ή μια
πλήρης διαμόρφωση με prompt απαντά σε αυτή τη μία κλήση αντί για τον
ανατεθειμένο πράκτορα (και την καρφιτσωμένη έκδοσή του). Οι λεπτομέρειες κλήσης επισημαίνουν κάθε περίπτωση στο
call_setup_webhook: assigned_agent,
other_agent ή inline_config. Μια απάντηση που δεν μπορεί να χρησιμοποιηθεί (άγνωστο
agent_id, άλλα κλειδιά δίπλα στο variables, διαμόρφωση που
αποτυγχάνει στην επικύρωση) τερματίζει την κλήση όπως για το webhook ενός αριθμού.
Πότε πρέπει να απαντήσει το webhook. Ένας πράκτορας χρειάζεται το webhook του όταν οι
ρυθμίσεις του χρησιμοποιούν ένα {{variable}} χωρίς προεπιλεγμένη τιμή: στην προτροπή του ή σε επαναχρησιμοποιήσιμες
οδηγίες, σε οδηγίες ή γραμμές βημάτων, στην προτροπή επιβεβαίωσης,
στο μήνυμα φωνητικού ταχυδρομείου, στην ανακοίνωση συναίνεσης ή σε έναν αριθμό προώθησης
{{variable}}. Το call_setup_webhook_variables του πράκτορα τα παραθέτει.
- Χρειάζεται το webhook: όταν λήγει το χρονικό όριο του webhook, δεν είναι
προσβάσιμο ή απαντά με σφάλμα ή με σώμα που δεν είναι αντικείμενο JSON,
η κλήση δεν ξεκινά, ακόμη και όταν η κλήση περιλαμβάνει ήδη τιμή για
μία από αυτές τις μεταβλητές. Τερματίζεται και καταγράφεται ακριβώς όπως περιγράφεται
στα Χρονικά όρια και επαναλήψεις (
end_reasoninbound_config_webhook_failed, χωρίς χρέωση). - Δεν χρειάζεται τίποτα (δεν υπάρχουν μεταβλητές ή καθεμία έχει προεπιλεγμένη τιμή όπως
{{first_name|there}}): το webhook εξακολουθεί να εκτελείται, αλλά όταν αποτυγχάνει ο πράκτορας απαντά χωρίς αυτό και οι λεπτομέρειες κλήσης εμφανίζουνwebhook_failedμε το πρόβλημα που προέκυψε.
Το περιβάλλον κλήσης από μόνο του δεν καθιστά ποτέ το webhook υποχρεωτικό: τίποτα στις ρυθμίσεις ενός πράκτορα δεν δηλώνει ότι χρειάζεται περιβάλλον. Χρησιμοποιήστε μια μεταβλητή χωρίς προεπιλεγμένη τιμή, αν μια κλήση δεν πρέπει να ξεκινά χωρίς την απάντηση του webhook σας.
Ανάθεση και ανάπτυξη. Ένας πράκτορας που χρειάζεται το webhook του δεν μπορεί να ανατεθεί σε έναν αριθμό χωρίς webhook: η ανάθεση απορρίπτεται με μήνυμα που αναφέρει τις μεταβλητές. Ο ίδιος έλεγχος εκτελείται όταν αλλάζει η έκδοση ενός αριθμού, συμπεριλαμβανομένης της επιστροφής ενός καρφιτσωμένου αριθμού στην «Τελευταία». Ενώ απαντά σε έναν αριθμό με τις
δημοσιευμένες ρυθμίσεις του, μια ανάπτυξη που προσθέτει μια τέτοια μεταβλητή χωρίς webhook
(ή αφαιρεί το webhook) απορρίπτεται με τον ίδιο τρόπο. Η αποθήκευση του προσχεδίου επιτρέπεται
πάντα και τα warnings του πράκτορα περιέχουν
call_setup_webhook_needed μέχρι να διορθωθεί.
Το webhook του πράκτορα εκτελείται μόνο για εισερχόμενες τηλεφωνικές κλήσεις σε αριθμούς στους οποίους είναι ανατεθειμένος. Οι εξερχόμενες κλήσεις, οι συνεδρίες γραφικού στοιχείου ιστού, οι διευθύνσεις SIP, οι προσομοιώσεις και οι δοκιμαστικές συνομιλίες στον πίνακα ελέγχου δεν το καλούν· λαμβάνουν τις μεταβλητές τους από το αίτημα όπως πριν.
Δοκιμή με αποθηκευμένα δείγματα. Για να δοκιμάσετε τι κάνει ο πράκτοράς σας με μια
συγκεκριμένη απάντηση (έναν καλούντα που επιστρέφει, μη εύρεση εγγραφής, έναν ισπανόφωνο),
αποθηκεύστε αυτή την απάντηση στον πράκτορα ως δείγμα: τα variables, το context
και προαιρετικά το language, πληκτρολογημένα ή αντιγραμμένα από προηγούμενη κλήση. Επιλέξτε το
όταν ξεκινάτε μια δοκιμαστική συνομιλία στον πίνακα ελέγχου, μια δοκιμαστική κλήση στο τηλέφωνό σας
ή μια προσομοίωση με τον πράκτορα, και η κλήση εκτελείται σαν να είχε απαντήσει με αυτό
το webhook σας. Τα δείγματα μοιράζονται σε κάθε έκδοση του πράκτορα.
Η επεξεργασία ενός δείγματος διατηρεί τις προηγούμενες εκδόσεις του: όταν μια αλλαγή στον πράκτορα χρειάζεται μια
μεταβλητή που δεν ορίζει το δείγμα, προσθέστε τη στο δείγμα και οι παλαιότερες εκδόσεις του πράκτορα
συνεχίζουν να χρησιμοποιούν το δείγμα όπως ήταν. Οι προσομοιώσεις που καλούν έναν αριθμό τηλεφώνου
εκτελούν αντί γι’ αυτό το πραγματικό webhook σας.
Αριθμοί χωρίς ανατεθειμένο πράκτορα συνεχίζουν να χρησιμοποιούν το webhook του αριθμού ή του οργανισμού ακριβώς όπως παραπάνω.
Επανακλήσεις
Οι χρήστες συχνά καλούν ξανά έναν αριθμό που τους κάλεσε, για παράδειγμα αφού ο πράκτοράς σας άφησε ένα φωνητικό μήνυμα. Όταν λαμβάνεται μια τηλεφωνική κλήση από κάποιον τον οποίο κάλεσε ο ίδιος αριθμός τις τελευταίες 30 ημέρες, το ThunderPhone εντοπίζει την πιο πρόσφατη αντίστοιχη εξερχόμενη κλήση (μία που χτύπησε το τηλέφωνό του) και τη χρησιμοποιεί με τρεις τρόπους:
-
returning_callστο αίτημα. Το παραπάνω αίτημα αποκλεισμού, καθώς και η ειδοποίηση τελικού σημείου, το περιλαμβάνουν, ώστε ο χειριστής σας να μπορεί να δρομολογεί τον καλούντα:{ "type": "telephony.incoming", "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567", "returning_call": { "call_id": 987650001, "agent_id": 13, "started_at": "2026-10-21T19:05:12.402Z", "outcome": "voicemail" } } }Πεδίο Τύπος Περιγραφή call_idακέραιος Η προηγούμενη εξερχόμενη κλήση agent_idακέραιος | null Ο πράκτορας που την πραγματοποίησε· nullγια κλήση που πραγματοποιήθηκε με ενσωματωμένη διαμόρφωση ή της οποίας ο πράκτορας διαγράφηκεstarted_atσυμβολοσειρά Πότε ξεκίνησε (ISO 8601, UTC) outcomeσυμβολοσειρά no_answer(χτύπησε χωρίς απάντηση, ήταν κατειλημμένη ή απορρίφθηκε),voicemail(απάντησε ο τηλεφωνητής ή κανείς δεν μίλησε με τον πράκτορα),conversation(κάποιος μίλησε με τον πράκτορα) ήanswered(απαντήθηκε· δεν είναι ακόμη γνωστό ποιος απάντησε) -
Πλαίσιο για τον πράκτορα. Όποιος πράκτορας απαντήσει λαμβάνει μια σύντομη σημείωση στο τέλος της προτροπής του: πότε πραγματοποιήθηκε η προηγούμενη κλήση, από ποιον πράκτορα και ποια ήταν η έκβασή της. Ο πράκτορας λαμβάνει οδηγία να μην τη διαβάσει δυνατά και, επειδή η αναγνώριση κλήσης μπορεί να πλαστογραφηθεί, να μη μοιραστεί τίποτα για εκείνη την κλήση πέρα από το ότι ο αριθμός είχε κληθεί νωρίτερα.
-
Εφεδρικός πράκτορας. Όταν ο αριθμός δεν έχει εισερχόμενο πράκτορα και δεν φτάνει διαμόρφωση επειδή δεν υπάρχει διεύθυνση URL webhook ή το webhook σας δεν έδωσε απάντηση (έληξε το χρονικό όριο, δεν ήταν προσβάσιμο ή απάντησε
5xx,408ή429και στις δύο προσπάθειες), η κλήση δρομολογείται στον πράκτορα που πραγματοποίησε την προηγούμενη κλήση αντί να τερματιστεί, εφόσον αυτός ο πράκτορας εξακολουθεί να υπάρχει στον οργανισμό σας. Εκτελείται με τις αναπτυγμένες ρυθμίσεις αυτού του πράκτορα. Κάθε απάντηση που δίνει το webhook σας εξακολουθεί να καθορίζει την έκβαση: ένα άλλο4xx, ένα σώμα που δεν είναι αντικείμενο JSON, το{}ή μια διαμόρφωση που αποτυγχάνει στην επικύρωση τερματίζει την κλήση όπως και πριν. Ένας εισερχόμενος πράκτορας στον αριθμό απαντά πάντα.
Κοινοποίηση των στοιχείων της προηγούμενης κλήσης. Η αναγνώριση κλήσης μπορεί να πλαστογραφηθεί,
επομένως από προεπιλογή κανένα στοιχείο από το περιεχόμενο της προηγούμενης κλήσης δεν μεταφέρεται
στη νέα. Ένας διαχειριστής οργανισμού μπορεί να ενεργοποιήσει το Κοινοποίηση των στοιχείων της προηγούμενης κλήσης
στην ενότητα Οργανισμός → Γενικά → Επανακλήσεις (ή να ορίσει
callback_context_details_enabled).
Όταν είναι ενεργοποιημένο, η σημείωση του πράκτορα παραθέτει επίσης τη σύνοψη της προηγούμενης κλήσης
και μια κλήση που δρομολογείται στον πράκτορα που πραγματοποίησε την προηγούμενη κλήση εκτελείται με τις
variables εκείνης της κλήσης (όπως το όνομα μιας επαφής). Ενεργοποιήστε το μόνο αν αυτά τα στοιχεία
είναι ασφαλές να κοινοποιούνται σε οποιονδήποτε καλεί από αυτόν τον αριθμό. Ακόμη και όταν είναι
ενεργοποιημένο, μια κλήση που ενδέχεται να περιέχει προστατευμένες πληροφορίες υγείας δεν μεταβιβάζει
ποτέ τη σύνοψή της ή τις μεταβλητές της σε κλήση που δεν έχει οριστεί για επεξεργασία PHI.
Στις λεπτομέρειες κλήσης. Μια εισερχόμενη κλήση που αντιστοιχίστηκε με προηγούμενη κλήση έχει ένα αντικείμενο callback στο GET /v1/calls/{call_id}:
το παραπάνω returning_call, το routed_as_callback (αν την απάντησε ο εφεδρικός μηχανισμός)
και το config_webhook_failure ({kind, attempts, http_status, host} όταν το webhook σας δεν έδωσε απάντηση και ο εφεδρικός μηχανισμός ανέλαβε
την κλήση, διαφορετικά null), ώστε μια διακοπή του webhook να παραμένει ορατή ακόμη και αν
η κλήση απαντήθηκε.
Όριο μεγέθους απόκρισης
Παράδειγμα χειριστή
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
WEBHOOK_SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, signature: str) -> bool:
expected = hmac.new(WEBHOOK_SECRET.encode(), body, hashlib.sha256).hexdigest()
return hmac.compare_digest(expected, signature or "")
@app.post("/thunderphone-webhook")
async def webhook(request: Request):
body = await request.body()
if not verify(body, request.headers.get("X-ThunderPhone-Signature", "")):
raise HTTPException(status_code=401)
event = json.loads(body)
if event["type"] == "telephony.incoming":
caller = event["data"]["from_number"]
prompt = (
"Greet the caller as a San Francisco local…"
if caller.startswith("+1415")
else "You are a friendly customer support agent…"
)
return {
"prompt": prompt,
"voice": "john",
"product": "spark",
}
if event["type"] == "web.incoming":
return {
"prompt": "You are the website's helpful voice assistant…",
"voice": "john",
"product": "spark",
}
return {}import crypto from "node:crypto";
import express from "express";
const app = express();
const SECRET = process.env.THUNDERPHONE_WEBHOOK_SECRET;
function verify(body, signature) {
const expected = crypto
.createHmac("sha256", SECRET)
.update(body)
.digest("hex");
return signature &&
crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(signature));
}
app.post(
"/thunderphone-webhook",
express.raw({ type: "application/json" }),
(req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (event.type === "telephony.incoming" || event.type === "web.incoming") {
const caller = event.data.from_number || "web";
const prompt = caller.startsWith("+1415")
? "Greet the caller as a San Francisco local…"
: "You are a friendly customer support agent…";
return res.json({
prompt,
voice: "john",
product: "spark",
});
}
res.json({});
},
);Απόκριση με εργαλεία συναρτήσεων
Επισυνάψτε εργαλεία ώστε ο AI πράκτορας να μπορεί να καλεί τα API σας κατά τη διάρκεια της συνομιλίας:
{
"prompt": "You are a booking assistant. Use the available tools to help customers schedule appointments.",
"voice": "john",
"product": "spark",
"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": "your-key"
}
}
}
]
}Συνοπτικός οδηγός ρυθμίσεων
Στείλτε product: "bolt" και ρυθμίστε την κλήση με αυτά τα πεδία. Οι παλαιότερες
τιμές του product (spark και οι τιμές storm-*) εξακολουθούν να γίνονται δεκτές.
| Πεδίο | Τιμές | Τι αντισταθμίζει |
|---|---|---|
intelligence | core, pro (προεπιλογή) | Το Core είναι φθηνότερο και αρχίζει να απαντά νωρίτερα· το Pro ακολουθεί μεγάλες οδηγίες πιο αξιόπιστα |
audio_tier | lite, standard (προεπιλογή), plus, max | Οι υψηλότερες βαθμίδες ακούν καλύτερα και κοστίζουν περισσότερο· το Plus προσθέτει 1–2 δευτ. σε ορισμένες εναλλαγές, κάθε απάντηση Max διαρκεί 3–4 δευτ. (το Max δεν είναι γενικά διαθέσιμο) |
endpointing | faster, fast, normal (προεπιλογή), patient | Οι μικρότερες αναμονές απαντούν νωρίτερα και κοστίζουν περισσότερο |
faster_replies | true (προεπιλογή), false | Επιτάχυνση: απαντά λίγο νωρίτερα, με λίγο υψηλότερο κόστος |
Σχετικά
Το μη αποκλειστικό συμβάν ολοκλήρωσης κλήσης.
Πλήρες σχήμα JSON για tools[] και το συμβόλαιο του υπογεγραμμένου endpoint.
Εγγράψτε πολλαπλά URL στα telephony.incoming / web.incoming.
Μοτίβα για προτροπές, εργαλεία και δοκιμές A/B ανά καλούντα.