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

Webhooks

telephony.complete / web.complete

Μη αποκλειστικό webhook που αποστέλλεται όταν ολοκληρώνεται μια κλήση, με απομαγνητοφώνηση, URL εγγραφής και μετρήσεις.

Ένα συμβάν ολοκλήρωσης ενεργοποιείται μετά το τέλος κάθε κλήσης — εισερχόμενη τηλεφωνική κλήση, εξερχόμενη τηλεφωνική κλήση, διαδικτυακή κλήση ή δοκιμαστική κλήση (συνεδρία μικροφώνου στον δημιουργό). Είναι μη αποκλειστικό: απαντήστε με οποιονδήποτε κωδικό 2xx.

Το συμβάν παραδίδεται και στις δύο διαδρομές:

Ωφέλιμο φορτίο αιτήματος (παραδόσεις 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 δεν λαμβάνονται ποτέ υπόψη για αυτό.

Παράδειγμα χειριστή

Python (FastAPI)
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}
Node.js (Express)
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 });
  },
);

Συνήθεις περιπτώσεις χρήσης

Ενσωμάτωση CRM

Αποθηκεύστε το απομαγνητοφωνημένο κείμενο και το URL εγγραφής κάθε κλήσης μαζί με τα αρχεία πελατών σας.

Αναλύσεις

Διοχετεύστε απομαγνητοφωνημένα κείμενα σε μια ροή επεξεργασίας για μοντελοποίηση θεμάτων, εξαγωγή σημάτων CSAT ή παρακολούθηση του ποσοστού μεταφορών.

Έλεγχος ποιότητας

Ανοίξτε κλήσεις σε ένα εργαλείο QA για ανθρώπινο έλεγχο ή εκτελέστε τες μέσω του δικού σας μοντέλου αξιολόγησης.

Ειδοποιήσεις

Ενεργοποιήστε έναν ανθρώπινο συνεργάτη σε περίπτωση μεταφοράς / αποτυχίας.


Σχετικά