telephony.complete / web.complete

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

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

• Τελικά σημεία webhook λαμβάνουν telephony.complete (τηλεφωνικές κλήσεις) ή web.complete (διαδικτυακές κλήσεις και δοκιμαστικές κλήσεις μικροφώνου του εργαλείου δημιουργίας) με το σταθερό ωφέλιμο φορτίο που τεκμηριώνεται παρακάτω, ένα event_id ανά παράδοση, χρονικό όριο 30 δευτ. και επαναλήψεις για έως 24 ώρες.
• Το παλαιού τύπου webhook μίας διεύθυνσης URL λαμβάνει μία σύγχρονη προσπάθεια (χρονικό όριο 10 δευτ., χωρίς επαναλήψεις) με ένα ελαφρώς διαφορετικό ωφέλιμο φορτίο — δείτε τις Διαφορές παλαιού ωφέλιμου φορτίου.

Ωφέλιμο φορτίο αιτήματος (παραδόσεις τελικών σημείων)

{
  "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",
    "from_number": "+14155550199",
    "product": "spark",
    "recording_url": "https://storage.example.com/…",
    "start_time": "2026-04-20T18:24:10.113Z",
    "status": "completed",
    "to_number": "+15551234567",
    "transcripts": [ /* see Transcript format */ ],
    "transfer_number": null,
    "voice": "john"
  },
  "event_id": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "type": "telephony.complete"
}

Αιτίες τερματισμού

Μορφή απομαγνητοφώνησης

Κάθε καταχώριση στο 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"] }
    }
  }
]

Για το πλήρως δομημένο ιστορικό σειρών (με δείκτες διακοπών, προτροπές επιβεβαίωσης και ακατέργαστες θέσεις), χρησιμοποιήστε GET /v1/calls/{call_id}/history.

Διαφορές παλαιού φορτίου

Το παλαιό περιτύλιγμα webhook με ένα URL είναι {"type": "telephony.complete" | "web.complete", "data": {…}} χωρίς event_id, και το data του διαφέρει από το φορτίο του endpoint:

• Ο πίνακας σειρών βρίσκεται στο history, όχι στο transcripts (ίδιο σχήμα σειράς με παραπάνω).
• Το σύνολο πεδίων είναι η ακατέργαστη αναφορά τέλους κλήσης και μπορεί να περιλαμβάνει πρόσθετα εσωτερικά πεδία πέρα από τον παραπάνω πίνακα — αντιμετωπίζετε τα άγνωστα πεδία ως ενημερωτικά.
• Οι διαδικτυακές κλήσεις (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 });
  },
);

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

Σχετικά