telephony.complete / web.complete

ਹਰ ਕਾਲ ਖਤਮ ਹੋਣ ਤੋਂ ਬਾਅਦ ਇੱਕ ਕੰਪਲੀਸ਼ਨ ਇਵੈਂਟ ਚਲਦਾ ਹੈ — ਇਨਬਾਊਂਡ ਟੈਲੀਫੋਨੀ, ਆਊਟਬਾਊਂਡ ਟੈਲੀਫੋਨੀ, ਵੈੱਬ ਕਾਲ, ਜਾਂ ਟੈਸਟ ਕਾਲ (ਬਿਲਡਰ ਮਾਈਕ ਸੈਸ਼ਨ)। ਇਹ ਨਾਨ-ਬਲਾਕਿੰਗ ਹੈ: ਕਿਸੇ ਵੀ 2xx ਨਾਲ ਜਵਾਬ ਦਿਓ।

ਇਵੈਂਟ ਦੋਵੇਂ ਪਾਥਾਂ 'ਤੇ ਡਿਲੀਵਰ ਕੀਤਾ ਜਾਂਦਾ ਹੈ:

• ਵੇਬਹੁੱਕ ਐਂਡਪੌਇੰਟ ਨੂੰ telephony.complete (ਫ਼ੋਨ ਕਾਲਾਂ) ਜਾਂ web.complete (ਵੈੱਬ ਕਾਲਾਂ ਅਤੇ ਬਿਲਡਰ ਮਾਈਕ ਟੈਸਟ ਕਾਲਾਂ) ਹੇਠਾਂ ਦਸਤਾਵੇਜ਼ਿਤ ਸਥਿਰ ਪੇਲੋਡ, ਹਰ ਡਿਲੀਵਰੀ ਲਈ ਇੱਕ event_id, 30 s ਟਾਈਮਆਊਟ, ਅਤੇ 24 h ਤੱਕ ਰੀਟ੍ਰਾਈਆਂ ਦੇ ਨਾਲ ਮਿਲਦਾ ਹੈ।
• ਪੁਰਾਣੇ ਸਿੰਗਲ-URL ਵੇਬਹੁੱਕ ਨੂੰ ਥੋੜ੍ਹਾ ਵੱਖਰਾ ਪੇਲੋਡ ਦੇ ਨਾਲ ਇੱਕ ਸਿੰਕ੍ਰੋਨਸ ਕੋਸ਼ਿਸ਼ ਮਿਲਦੀ ਹੈ (10 s ਟਾਈਮਆਊਟ, ਕੋਈ ਰੀਟ੍ਰਾਈ ਨਹੀਂ) — ਵੇਖੋ ਪੁਰਾਣੇ ਪੇਲੋਡ ਦੇ ਅੰਤਰ।

ਰਿਕਵੇਸਟ ਪੇਲੋਡ (ਐਂਡਪੌਇੰਟ ਡਿਲੀਵਰੀਆਂ)

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

ਪੂਰੀ ਤਰ੍ਹਾਂ ਸਟ੍ਰਕਚਰਡ ਵਾਰੀ ਇਤਿਹਾਸ ਲਈ (ਇੰਟਰਪਸ਼ਨ ਮਾਰਕਰਾਂ, ack-prompts ਅਤੇ ਰਾਅ ਸਥਿਤੀਆਂ ਸਮੇਤ), ਵਰਤੋ GET /v1/calls/{call_id}/history।

ਪੁਰਾਣੇ ਪੇਲੋਡ ਦੇ ਅੰਤਰ

ਪੁਰਾਣਾ ਸਿੰਗਲ-URL webhook ਐਨਵਲਪ ਹੈ {"type": "telephony.complete" | "web.complete", "data": {…}}, ਜਿਸ ਵਿੱਚ ਕੋਈ event_id ਨਹੀਂ ਹੁੰਦਾ, ਅਤੇ ਇਸਦਾ data ਐਂਡਪੁਆਇੰਟ ਪੇਲੋਡ ਤੋਂ ਵੱਖਰਾ ਹੁੰਦਾ ਹੈ:

• ਵਾਰੀ ਐਰੇ transcripts ਦੀ ਬਜਾਏ history ਦੇ ਅਧੀਨ ਹੁੰਦਾ ਹੈ (ਉੱਪਰ ਦਿੱਤੀ ਉਹੀ ਵਾਰੀ ਸਕੀਮਾ)।
• ਫੀਲਡ ਸੈੱਟ ਰਾਅ ਕਾਲ-ਅੰਤ ਰਿਪੋਰਟ ਹੁੰਦਾ ਹੈ ਅਤੇ ਇਸ ਵਿੱਚ ਉੱਪਰਲੀ ਟੇਬਲ ਤੋਂ ਇਲਾਵਾ ਵਾਧੂ ਅੰਦਰੂਨੀ ਫੀਲਡ ਸ਼ਾਮਲ ਹੋ ਸਕਦੇ ਹਨ — ਅਣਜਾਣ ਫੀਲਡਾਂ ਨੂੰ ਜਾਣਕਾਰੀ ਵਜੋਂ ਵਰਤੋ।
• ਵੈੱਬ ਕਾਲਾਂ (direction: "web") ਵਿੱਚ from_number / to_number ਨਹੀਂ ਹੁੰਦੇ ਅਤੇ origin_domain ਜੋੜਿਆ ਜਾਂਦਾ ਹੈ।
• Builder ਮਾਈਕ ਟੈਸਟ ਕਾਲਾਂ ਪੁਰਾਣੇ ਪਾਥ 'ਤੇ telephony.complete ਵਜੋਂ ਰਿਪੋਰਟ ਹੁੰਦੀਆਂ ਹਨ (ਐਂਡਪੁਆਇੰਟ ਸਿਸਟਮ ਉਹਨਾਂ ਨੂੰ web.complete ਨਾਲ ਮੈਪ ਕਰਦਾ ਹੈ)।
• ਟ੍ਰਾਂਸਫਰ ਤਾਲਮੇਲ: ਜਦੋਂ ਕੋਈ ਕਾਲ ਟ੍ਰਾਂਸਫਰ ਵਿੱਚ ਖਤਮ ਹੁੰਦੀ ਹੈ, ਪੁਰਾਣੇ webhook ਨੂੰ ਸਿੰਕ੍ਰੋਨਸ ਢੰਗ ਨਾਲ ਕਾਲ ਕੀਤਾ ਜਾਂਦਾ ਹੈ ਅਤੇ ਇਹ ਸੰਕੇਤ ਦੇਣ ਲਈ {"transfer_ready": false} ਜਵਾਬ ਦੇ ਸਕਦਾ ਹੈ ਕਿ ਹੈਂਡਆਫ ਟਾਰਗੇਟ ਤਿਆਰ ਨਹੀਂ ਹੈ। ਕੋਈ ਵੀ ਹੋਰ ਜਵਾਬ (ਜਾਂ ਕੋਈ ਪੁਰਾਣਾ webhook ਨਾ ਹੋਣਾ) ਟ੍ਰਾਂਸਫਰ ਨੂੰ ਅੱਗੇ ਵਧਣ ਦਿੰਦਾ ਹੈ। ਇਸ ਲਈ ਐਂਡਪੁਆਇੰਟ ਡਿਲਿਵਰੀਆਂ ਨਾਲ ਕਦੇ ਸਲਾਹ ਨਹੀਂ ਕੀਤੀ ਜਾਂਦੀ।

ਉਦਾਹਰਨ ਹੈਂਡਲਰ

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

ਆਮ ਵਰਤੋਂ ਦੇ ਮਾਮਲੇ

ਸੰਬੰਧਿਤ