telephony.complete / web.complete

Webhook non bloquant envoyé à la fin d’un appel, avec transcription, URL de l’enregistrement et métriques.

Un événement de fin est déclenché après chaque appel — téléphonie entrante, téléphonie sortante, appel web ou appel de test (session micro du builder). Il est non bloquant : répondez avec n’importe quel code 2xx.

L’événement est envoyé sur les deux chemins :

• Les points de terminaison webhook reçoivent telephony.complete (appels téléphoniques) ou web.complete (appels web et appels de test au micro du builder) avec la charge utile stable documentée ci-dessous, un event_id par livraison, un délai d’expiration de 30 s et des tentatives pendant jusqu’à 24 h.
• Le webhook historique à URL unique reçoit une tentative synchrone unique (délai d’expiration de 10 s, aucune nouvelle tentative) avec une charge utile légèrement différente — consultez Différences de charge utile historique.

Charge utile de requête (livraisons d’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_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"
}

Raisons de fin#

Format de transcription#

Chaque entrée de transcripts correspond à un tour de conversation. Les rôles sont user (parole de l’appelant), model (parole de l’agent et appels d’outils), tool (résultats d’outils) et system (événements d’appel tels que les changements de langue).

[
  {
    "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"] }
    }
  }
]

Pour l’historique complet et structuré des tours (avec les marqueurs d’interruption, les prompts d’acquiescement verbal et les positions brutes), utilisez GET /v1/calls/{call_id}/history.

Différences de charge utile héritée#

L’enveloppe webhook héritée à URL unique est {"type": "telephony.complete" | "web.complete", "data": {…}} sans event_id, et ses data diffèrent de la charge utile de l’endpoint :

La charge utile de fin héritée contient également agent_id et agent_name.

• Le tableau des tours se trouve sous history, et non sous transcripts (même schéma de tour que ci-dessus).
• L’ensemble des champs correspond au rapport brut de fin d’appel et peut inclure des champs internes supplémentaires au-delà du tableau ci-dessus : traitez les champs inconnus comme des informations.
• Les appels web (direction: "web") omettent from_number / to_number et ajoutent origin_domain.
• Les appels de test du micro dans le Builder sont signalés comme telephony.complete sur le chemin hérité (le système de l’endpoint les mappe vers web.complete).
• Coordination du transfert : lorsqu’un appel se termine par un transfert, le webhook hérité est appelé de manière synchrone et peut répondre {"transfer_ready": false} pour indiquer que la cible du transfert n’est pas prête. Toute autre réponse (ou l’absence de webhook hérité) permet au transfert de se poursuivre. Les livraisons via l’endpoint ne sont jamais consultées à cette fin.

Exemple de gestionnaire#

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 });
  },
);

Cas d'utilisation courants#

Associés#