telephony.complete / web.complete

Tukio la ukamilishaji hutokea baada ya kila simu kuisha — simu za ndani, simu za nje, simu za wavuti, au simu za majaribio (kipindi cha maikrofoni cha builder). Halizuii utekelezaji: jibu kwa 2xx yoyote.

Tukio linawasilishwa kwenye njia zote mbili:

• Vituo vya webhook hupokea telephony.complete (simu za simu) au web.complete (simu za wavuti na simu za majaribio ya maikrofoni ya builder) zikiwa na payload thabiti iliyoelezewa hapa chini, event_id kwa kila uwasilishaji, muda wa kuisha wa s 30, na majaribio tena kwa hadi saa 24.
• Webhook ya urithi yenye URL moja hupokea jaribio moja la usawazishaji (muda wa kuisha wa s 10, hakuna majaribio tena) lenye payload tofauti kidogo — tazama Tofauti za payload ya urithi.

Payload ya ombi (uwasilishaji wa 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",
    "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"
}

Sababu za kuisha

Muundo wa transkripti

Kila ingizo katika transcripts ni zamu moja ya mazungumzo. Majukumu ni user (usemi wa mpigaji simu), model (usemi wa ejenti na miito ya zana), tool (matokeo ya zana), na system (matukio ya simu kama vile kubadilisha lugha).

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

Kwa historia kamili ya zamu iliyoundwa (yenye alama za kukatiza, prompt za uthibitisho, na nafasi ghafi), tumia GET /v1/calls/{call_id}/history.

Tofauti za payload za urithi

Bahasha ya webhook ya urithi yenye URL moja ni {"type": "telephony.complete" | "web.complete", "data": {…}} bila event_id, na data yake inatofautiana na payload ya endpoint:

• Mpangilio wa zamu uko chini ya history, si transcripts (schema sawa ya zamu kama ilivyo hapo juu).
• Seti ya sehemu ni ripoti ghafi ya mwisho wa simu na inaweza kujumuisha sehemu za ziada za ndani zaidi ya jedwali lililo hapo juu — chukulia sehemu zisizojulikana kama za taarifa.
• Simu za wavuti (direction: "web") hazijumuishi from_number / to_number na huongeza origin_domain.
• Simu za majaribio ya maikrofoni ya Builder huripotiwa kama telephony.complete kwenye njia ya urithi (mfumo wa endpoint huzitafsiri kama web.complete).
• Uratibu wa uhamisho: simu inapomalizika kwa uhamisho, webhook ya urithi huitwa kwa usawazishaji na inaweza kujibu {"transfer_ready": false} kuashiria kuwa lengwa la uhamisho haliko tayari. Jibu lingine lolote (au kutokuwepo kwa webhook ya urithi) huruhusu uhamisho kuendelea. Uwasilishaji wa endpoint hauangaliwi kamwe kwa hili.

Kishughulikiaji wa mfano

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

Matumizi ya kawaida

Zinazohusiana