Open in
telephony.complete / web.complete
Μη αποκλειστικό webhook που αποστέλλεται όταν ολοκληρώνεται μια κλήση, με απομαγνητοφώνηση, URL εγγραφής και μετρήσεις.
Ένα συμβάν ολοκλήρωσης ενεργοποιείται μετά το τέλος κάθε κλήσης — εισερχόμενη τηλεφωνική κλήση, εξερχόμενη τηλεφωνική κλήση, διαδικτυακή κλήση ή δοκιμαστική κλήση (συνεδρία μικροφώνου στον δημιουργό). Είναι μη αποκλειστικό: απαντήστε με οποιονδήποτε κωδικό 2xx.
Το συμβάν παραδίδεται και στις δύο διαδρομές:
- Τα τελικά σημεία webhook λαμβάνουν
telephony.complete(τηλεφωνικές κλήσεις) ήweb.complete(διαδικτυακές κλήσεις και δοκιμαστικές κλήσεις μικροφώνου στον δημιουργό) με το σταθερό ωφέλιμο φορτίο που τεκμηριώνεται παρακάτω, έναevent_idανά παράδοση, χρονικό όριο 30 δευτ. και επαναλήψεις για έως 24 ώρες. - Το παλαιό webhook ενός URL λαμβάνει μία σύγχρονη προσπάθεια (χρονικό όριο 10 δευτ., χωρίς επαναλήψεις) με ελαφρώς διαφορετικό ωφέλιμο φορτίο — δείτε Διαφορές παλαιού ωφέλιμου φορτίου.
Ωφέλιμο φορτίο αιτήματος (παραδόσεις endpoint)
{
"data": {
"billable_minutes": 1.25,
"billing_total_cents": 8,
"call_id": 987654321,
"direction": "inbound",
"duration_seconds": 54,
"end_reason": "user_hangup",
"end_time": "2026-04-20T18:25:04.822Z",
"extracted_data": {
"status": "completed",
"fields": {
"customer_name": "Alex Morgan",
"appointment_date": "2026-04-23"
},
"evidence": {
"customer_name": {
"quote": "My name is Alex Morgan",
"speaker_role": "caller",
"turn_index": 4
},
"appointment_date": {
"quote": "April 23 works for me",
"speaker_role": "caller",
"turn_index": 7
}
},
"verification": "verified",
"field_reasons": {},
"schema_version": "92850758e231a3c95a..."
},
"from_number": "+14155550199",
"product": "spark",
"recording_stopped_at": null,
"recording_stopped_reason": null,
"recording_url": "https://storage.example.com/…",
"start_time": "2026-04-20T18:24:10.113Z",
"status": "completed",
"summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23. The agent read the appointment back and Alex asked for a reminder text the day before.",
"to_number": "+15551234567",
"transcripts": [ /* see Transcript format */ ],
"transfer_number": null,
"unresolved_variables": ["campaign_owner"],
"variables": {"campaign_name": "Spring renewals"},
"voice": "john"
},
"event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
"type": "telephony.complete"
}| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
call_id | ακέραιος | Σταθερό σε κάθε συμβάν για αυτήν την κλήση |
agent_id | ακέραιος | null | Πράκτορας που διαχειρίστηκε την κλήση, όταν είχε εκχωρηθεί |
agent_name | συμβολοσειρά | null | Πράκτορας που διαχειρίστηκε την κλήση, όταν είχε εκχωρηθεί |
direction | συμβολοσειρά | inbound, outbound, web, test. Τα ιστορικά ωφέλιμα φορτία μπορεί να περιέχουν παλαιές τιμές mic ή widget |
from_number, to_number | συμβολοσειρά | E.164. Το from_number είναι κυριολεκτικά "web" για κλήσεις ιστού και δοκιμαστικές κλήσεις |
origin_domain | συμβολοσειρά | Μόνο για ιστό/δοκιμή — η προέλευση της σελίδας που φιλοξένησε το γραφικό στοιχείο (κενή για συνεδρίες μικροφώνου) |
start_time, end_time | χρονική σήμανση | ISO 8601 UTC |
duration_seconds | ακέραιος | null | Προκύπτει από την ώρα έναρξης/λήξης |
status | συμβολοσειρά | completed ή failed |
end_reason | συμβολοσειρά | Δείτε τον παρακάτω πίνακα |
answered_by | συμβολοσειρά | null | Μόνο για εξερχόμενες τηλεφωνικές κλήσεις (απουσιάζει σε κάθε άλλη περίπτωση): ποιος απάντησε, human, voicemail, screener (βοηθός φιλτραρίσματος κλήσεων), ivr (τηλεφωνικό μενού) ή unknown. null όταν δεν απάντησε κανείς και πάντα null σε συμβάντα migration.call.complete για εξερχόμενες κλήσεις που διαχειρίστηκε η πλατφόρμα από την οποία μεταφέρεστε. Ίδιες τιμές με το αντικείμενο κλήσης |
product, voice | συμβολοσειρά | Διαμόρφωση πράκτορα που ίσχυε κατά τον χρόνο της κλήσης |
variables | αντικείμενο | Μεταβλητές εισόδου όπως καταγράφηκαν όταν ξεκίνησε η κλήση |
unresolved_variables | πίνακας | Ονόματα μεταβλητών που αναφέρονται από τη διαμόρφωση κλήσης αλλά δεν παρασχέθηκαν κατά την έναρξη της κλήσης |
transfer_number | συμβολοσειρά | null | Ορίζεται όταν η κλήση μεταφέρθηκε |
scheduled_send_id | συμβολοσειρά | Μόνο σε κλήση που πραγματοποιήθηκε από μια προγραμματισμένη αποστολή: το αναγνωριστικό αυτής της αποστολής. Απουσιάζει σε κάθε άλλη κλήση |
recording_url | συμβολοσειρά | null | Υπογεγραμμένο URL που λήγει· πραγματοποιήστε λήψη άμεσα. null όταν δεν υπάρχει διαθέσιμο στοιχείο εγγραφής |
recording_stopped_at | χρονική σήμανση | null | Όταν η εγγραφή διακόπηκε πριν από τη λήξη της κλήσης· τίποτα μετά από αυτήν τη στιγμή δεν περιλαμβάνεται στην εγγραφή. null όταν η εγγραφή συνεχίστηκε έως το τέλος της κλήσης ή η κλήση δεν καταγράφηκε |
recording_stopped_reason | συμβολοσειρά | null | Γιατί η εγγραφή διακόπηκε νωρίς. warm_transfer: διακόπτεται ακριβώς πριν μια θερμή μεταφορά καλέσει τον προορισμό και παραμένει απενεργοποιημένη ακόμη και αν η μεταφορά αποτύχει και ο καλών επιστρέψει στον πράκτορα. Αντιμετωπίστε άλλες τιμές ως ενημερωτικές· μπορεί να προστεθούν περισσότερες. null όταν το recording_stopped_at είναι null |
billable_minutes | αριθμός | Λεπτά που χρεώνονται, στρογγυλοποιημένα στο πλησιέστερο τέταρτο του λεπτού (προσαυξήσεις 15 δευτερολέπτων, ελάχιστο 0.25). Οι κλήσεις που πηγαίνουν απευθείας στον τηλεφωνητή εξακολουθούν να αναφέρουν εδώ τα πραγματικά μετρημένα λεπτά τους, αλλά η χρέωση περιορίζεται στο ένα λεπτό με την τιμή του προγράμματος. |
billing_total_cents | ακέραιος | null | Σεντ USD. null όσο το billing_pending είναι true |
billing_pending | λογική τιμή | Παρουσιάζεται μόνο, ως true, σε μια μετρημένη κλήση της οποίας η χρέωση δεν έχει ακόμη διευθετηθεί: μια μετρημένη κλήση χρεώνεται λίγα λεπτά μετά τη λήξη της, μόλις καταγραφεί η χρήση της, επομένως τα billable_minutes και billing_total_cents είναι εδώ null και η χρέωση φτάνει στο call.billed. Απουσιάζει σε κάθε άλλη κλήση |
transcripts | πίνακας | Καταχωρίσεις απομαγνητοφώνησης ανά σειρά ομιλίας· μπορεί να είναι κενός όταν δεν είναι διαθέσιμη απομαγνητοφώνηση |
summary | συμβολοσειρά | null | Σύνοψη μετά την κλήση σε απλή γλώσσα (δύο έως τέσσερις προτάσεις πεζού κειμένου, έως 2.000 χαρακτήρες, γραμμένη στη summary_language του πράκτορα, διαφορετικά στη γλώσσα σύνοψης του οργανισμού, διαφορετικά στη γλώσσα της κλήσης: την κύρια γλώσσα του πράκτορα, εκτός αν η κλήση την παράκαμψε) όταν ο πράκτορας έχει ενεργοποιημένη τη Δημιουργία σύνοψης κλήσης στην ενότητα Δεδομένα προς συλλογή στο εργαλείο δημιουργίας πρακτόρων (call_summary_enabled στον Πράκτορα) και η δημιουργία ολοκληρώθηκε με επιτυχία· null σε διαφορετική περίπτωση, συμπεριλαμβανομένων κλήσεων που είναι πολύ σύντομες για σύνοψη, κλήσεων χωρίς απομαγνητοφώνηση και πρακτόρων με απενεργοποιημένη εγγραφή. Η σύνοψη δημιουργείται στο ίδιο βήμα μετά την κλήση με την εξαγωγή, επομένως η ρύθμιση Αναμονή για εξαγόμενα δεδομένα πριν από την αποστολή του webhook ολοκλήρωσης κλήσης (extraction_blocks_completion) καθορίζει αν αυτό το συμβάν την αναμένει: σε λειτουργία αναμονής η σύνοψη είναι έτοιμη πριν αποσταλεί αυτό το συμβάν (η ίδια η σύνοψη λαμβάνει έως 30 δευτερόλεπτα εντός του προϋπολογισμού 75 δευτερολέπτων του βήματος)· όταν το συμβάν δεν αναμένει (never, ή μεταφορά ή επιστροφή στο κέντρο επικοινωνίας σας υπό το except_transfers) αυτό το πεδίο είναι null και η σύνοψη δεν αποστέλλεται ξανά στο call.data_extracted, επομένως διαβάστε τη αργότερα από το summary στο αντικείμενο κλήσης. Διατίθεται επίσης στη σελίδα κλήσης στον πίνακα ελέγχου |
extracted_data | αντικείμενο | null | Αποτέλεσμα δομημένης εξαγωγής με status, fields, evidence, verification, field_reasons και schema_version. Κάθε πεδίο που δεν είναι null έχει το ακριβές απόσπασμα που ελέγχθηκε δομικά (έως 1.000 χαρακτήρες), καθώς και τον ρόλο ομιλητή και τον δείκτη σειράς ομιλίας του· μεγαλύτερα αποσπάσματα που επιστρέφονται από το μοντέλο απορρίπτονται αντί να περικόπτονται. Το αποδεικτικό στοιχείο είναι null όταν το πεδίο είναι null. Το verified σημαίνει ότι κάθε υποψήφιο έλαβε ακριβώς μία έγκυρη ανεξάρτητη ετυμηγορία. Το unavailable καλύπτει επίσης κακοσχηματισμένη ή μερική έξοδο επαληθευτή· οι έγκυρες μερικές ετυμηγορίες εξακολουθούν να εφαρμόζονται, ενώ τα υποψήφια χωρίς μία έγκυρη ετυμηγορία μηδενίζονται. Το status είναι completed, failed, exhausted, skipped ή skipped_recording_disabled· null όταν ο πράκτορας δεν είχε πεδία εξαγωγής |
steps_trace | πίνακας | Μόνο σε κλήσεις των οποίων ο πράκτορας έχει βήματα ή παραδόσεις. Η σειρά με την οποία η κλήση πέρασε από αυτά: κάθε καταχώριση έχει t_ms (χιλιοστά του δευτερολέπτου από την έναρξη της κλήσης), agent (το κλειδί του πράκτορα, a συν το αναγνωριστικό του), step (το αναγνωριστικό βήματος ή null σε παράδοση σε πράκτορα χωρίς βήματα) και via (start, model, condition, on_enter ή handoff). Περιέχει μόνο αναγνωριστικά και χρόνους, επομένως διατηρείται ακόμη και όταν η εγγραφή είναι απενεργοποιημένη |
collected_values | αντικείμενο | Μόνο σε κλήσεις των οποίων ο πράκτορας έχει βήματα ή παραδόσεις. Οι τιμές που συνέλεξε ο πράκτορας στα βήματά του, με κλειδί το όνομα πεδίου συλλογής, καθώς και <tool>_result για το αποτέλεσμα on_enter_tool κάθε βήματος. Παραλείπεται όταν το περιεχόμενο της κλήσης δεν διατηρείται (η εγγραφή είναι απενεργοποιημένη) |
Αιτίες τερματισμού
| Τιμή | Σημασία |
|---|---|
user_hangup | Ο απομακρυσμένος συνομιλητής έκλεισε πρώτος |
ai_hangup | Ο AI πράκτορας τερμάτισε σκόπιμα την κλήση |
ai_transfer | Ο AI πράκτορας μετέφερε την κλήση· το transfer_number έχει οριστεί |
ai_warm_transfer | Ο AI πράκτορας ολοκλήρωσε μια θερμή μεταφορά με παρουσία |
returned_to_platform | Ο AI πράκτορας επέστρεψε την κλήση στο κέντρο επικοινωνίας σας: τερμάτισε την κλήση, με τις κεφαλίδες της εγγραφής επιστροφής στο SIP BYE, εφόσον υπάρχουν |
voicemail_hangup | Εντοπίστηκε τηλεφωνητής και η κλήση τερματίστηκε σύμφωνα με το voicemail_action σας |
max_duration | Η κλήση έφτασε το μέγιστο όριο διάρκειας: το όριο του πράκτορα, το δικό της όριο ή το όριο πλατφόρμας των 6 ωρών. Μια κλήση που τερματίζεται από τον AI πράκτορα ή τον καλούντα μετά την προειδοποίηση χρονικού ορίου διατηρεί το ai_hangup ή το user_hangup |
superseded | Η συνεδρία αντικαταστάθηκε από νεότερη |
inbound_config_webhook_failed | Εισερχόμενη κλήση σε αριθμό σε λειτουργία webhook: το webhook διαμόρφωσης δεν επέστρεψε αξιοποιήσιμη διαμόρφωση, επομένως η κλήση τερματίστηκε προτού απαντήσει πράκτορας. Το status είναι failed και η κλήση δεν χρεώνεται |
outbound_queue_timeout | Μια κλήση σε ουρά περίμενε 10 λεπτά χωρίς διαθέσιμη χωρητικότητα για κλήση. Το status είναι failed, δεν πραγματοποιήθηκε κλήση και η κλήση δεν χρεώνεται |
outbound_queue_canceled | Ακυρώσατε μια κλήση σε ουρά πριν πραγματοποιηθεί η κλήση. Το status είναι failed και η κλήση δεν χρεώνεται |
unknown | Δεν ήταν δυνατό να προσδιοριστεί ο λόγος τερματισμού |
Μορφή απομαγνητοφώνησης
Κάθε εγγραφή στο transcripts είναι μία εναλλαγή συνομιλίας. Οι ρόλοι είναι
user (ομιλία καλούντος), model (ομιλία πράκτορα και κλήσεις εργαλείων),
tool (αποτελέσματα εργαλείων) και system (συμβάντα κλήσης, όπως αλλαγές
γλώσσας).
[
{
"role": "user",
"content_type": "text/plain",
"content": "Hi, I'm calling about my appointment.",
"start_ms": 1200,
"end_ms": 4100,
"audio_url": "https://storage.example.com/…"
},
{
"role": "model",
"content_type": "text/plain",
"content": "Sure, what date works best?",
"start_ms": 4200,
"end_ms": 6100
},
{
"role": "model",
"content_type": "application/json",
"content": {
"tool_call": "search_appointments",
"arguments": { "date": "2026-04-21" }
}
},
{
"role": "tool",
"content_type": "application/json",
"content": {
"tool_name": "search_appointments",
"response": { "available_slots": ["9:00 AM", "2:00 PM"] }
}
}
]| Πεδίο | Τύπος | Περιγραφή |
|---|---|---|
role | συμβολοσειρά | user, model, tool ή system |
content_type | συμβολοσειρά | text/plain για ομιλία· application/json για κλήσεις εργαλείων, αποτελέσματα εργαλείων και συμβάντα συστήματος |
content | συμβολοσειρά | αντικείμενο | Κείμενο ομιλίας ή το δομημένο αντικείμενο που εμφανίζεται παραπάνω. Κλήσεις εργαλείων: {"tool_call": name, "arguments": {…}}. Αποτελέσματα εργαλείων: {"tool_name": name, "response": {…}} |
start_ms, end_ms | ακέραιος | Μετατοπίσεις από την έναρξη της κλήσης, σε ms. Υπάρχουν όταν είναι γνωστός ο χρονισμός ήχου |
ttfa_ms | ακέραιος | Χρόνος έως τον πρώτο ήχο για μία εναλλαγή model, όταν μετράται |
audio_url, audio_urls | συμβολοσειρά / πίνακας | Υπογεγραμμένα URL με λήξη για τον ήχο της εναλλαγής, όταν η εγγραφή γίνεται ανά εναλλαγή |
Για το πλήρως δομημένο ιστορικό εναλλαγών (με δείκτες διακοπών,
προτροπές επιβεβαίωσης και ακατέργαστες θέσεις), χρησιμοποιήστε το
GET /v1/calls/{call_id}/history.
Διαφορές παλαιού ωφέλιμου φορτίου
Το παλαιό περιτύλιγμα webhook ενός URL είναι
{"type": "telephony.complete" | "web.complete", "data": {…}} χωρίς
event_id, και το data του διαφέρει από το ωφέλιμο φορτίο του endpoint:
Το παλαιό ωφέλιμο φορτίο ολοκλήρωσης περιλαμβάνει επίσης τα agent_id και agent_name.
- Ο πίνακας εναλλαγών βρίσκεται στο
history, όχι στοtranscripts(ίδιο σχήμα εναλλαγών με παραπάνω). - Το σύνολο πεδίων είναι η ακατέργαστη αναφορά τέλους κλήσης και μπορεί να περιλαμβάνει επιπλέον εσωτερικά πεδία πέρα από τον παραπάνω πίνακα — αντιμετωπίστε τα άγνωστα πεδία ως ενημερωτικά.
- Οι κλήσεις web (
direction: "web") παραλείπουν ταfrom_number/to_numberκαι προσθέτουν τοorigin_domain. - Οι δοκιμαστικές κλήσεις μικροφώνου του Builder αναφέρονται ως
telephony.completeστην παλαιά διαδρομή (το σύστημα endpoint τις αντιστοιχίζει σεweb.complete). - Συντονισμός μεταφοράς: όταν μία κλήση τερματίζεται με μεταφορά, το
παλαιό webhook καλείται συγχρονισμένα και μπορεί να απαντήσει
{"transfer_ready": false}για να υποδείξει ότι ο στόχος μεταβίβασης δεν είναι έτοιμος. Οποιαδήποτε άλλη απάντηση (ή η απουσία παλαιού webhook) επιτρέπει τη μεταφορά να συνεχιστεί. Οι παραδόσεις endpoint δεν λαμβάνονται ποτέ υπόψη για αυτό.
Παράδειγμα χειριστή
import hashlib
import hmac
import json
import os
from fastapi import FastAPI, HTTPException, Request
app = FastAPI()
SECRET = os.environ["THUNDERPHONE_WEBHOOK_SECRET"]
def verify(body: bytes, signature: str) -> bool:
expected = hmac.new(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"] in ("telephony.complete", "web.complete"):
data = event["data"]
# Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
turns = data.get("transcripts") or data.get("history") or []
await persist_call_record(
call_id=data["call_id"],
turns=turns,
recording_url=data.get("recording_url"),
)
if data["end_reason"] in ("ai_transfer", "ai_warm_transfer"):
await notify_team(data.get("transfer_number"), data["call_id"])
return {"ok": True}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" }),
async (req, res) => {
if (!verify(req.body, req.header("X-ThunderPhone-Signature"))) {
return res.sendStatus(401);
}
const event = JSON.parse(req.body.toString("utf8"));
if (["telephony.complete", "web.complete"].includes(event.type)) {
const data = event.data;
// Endpoint deliveries use "transcripts"; the legacy webhook uses "history".
const turns = data.transcripts ?? data.history ?? [];
await persistCallRecord({ ...data, turns });
if (["ai_transfer", "ai_warm_transfer"].includes(data.end_reason)) {
await notifyTeam(data.transfer_number, data.call_id);
}
}
res.json({ ok: true });
},
);Συνήθεις περιπτώσεις χρήσης
Αποθηκεύστε το απομαγνητοφωνημένο κείμενο και το URL εγγραφής κάθε κλήσης μαζί με τα αρχεία πελατών σας.
Διοχετεύστε απομαγνητοφωνημένα κείμενα σε μια ροή επεξεργασίας για μοντελοποίηση θεμάτων, εξαγωγή σημάτων CSAT ή παρακολούθηση του ποσοστού μεταφορών.
Ανοίξτε κλήσεις σε ένα εργαλείο QA για ανθρώπινο έλεγχο ή εκτελέστε τες μέσω του δικού σας μοντέλου αξιολόγησης.
Ενεργοποιήστε έναν ανθρώπινο συνεργάτη σε περίπτωση μεταφοράς / αποτυχίας.