> ## Documentation Index
> Fetch the complete documentation index at: https://docs.thunderphone.com/llms.txt
> Use this file to discover all available pages before exploring further.
# telephony.complete / web.complete
> Webhook לא חוסם שנשלח כאשר שיחה מסתיימת, עם תמליל, כתובת URL של ההקלטה ומדדים.
אירוע השלמה מופעל לאחר סיום כל שיחה — טלפוניה נכנסת,
טלפוניה יוצאת, שיחת ווב או שיחת בדיקה (סשן מיקרופון בבונה). הוא
**אינו חוסם**: השיבו עם כל קוד 2xx.
האירוע נמסר בשני הנתיבים:
* **[נקודות קצה של Webhook](/he/webhooks/endpoints)** מקבלות את
`telephony.complete` (שיחות טלפון) או את `web.complete` (שיחות ווב ושיחות
בדיקת מיקרופון בבונה) עם המטען היציב המתועד להלן,
`event_id` לכל מסירה, זמן קצוב של 30 שניות, וכן
[ניסיונות חוזרים למשך עד 24 שעות](/he/webhooks/overview).
* **ה-[Webhook מדור קודם בעל כתובת URL יחידה](/api-reference/organizations#legacy-single-url-webhook)**
מקבל ניסיון סינכרוני אחד (זמן קצוב של 10 שניות, ללא ניסיונות חוזרים) עם
מטען מעט שונה — ראו
[הבדלים במטען מדור קודם](#legacy-payload-differences).
## מטען הבקשה (מסירות לנקודות קצה)
```json theme={null}
{
"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"
}
```
| שדה | סוג | תיאור |
| -------------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `call_id` | integer | יציב בכל אירוע עבור שיחה זו |
| `direction` | string | `inbound`, `outbound`, `web`, `test`. מטענים היסטוריים עשויים להכיל את הערכים מדור קודם `mic` או `widget` |
| `from_number`, `to_number` | string | E.164. הערך של `from_number` הוא המחרוזת המילולית `"web"` עבור שיחות ווב ושיחות בדיקה |
| `origin_domain` | string | **לווב/בדיקה בלבד** — מקור הדף שאירח את הווידג'ט (ריק עבור סשני מיקרופון) |
| `start_time`, `end_time` | timestamp | ISO 8601 UTC |
| `duration_seconds` | integer \| null | נגזר מזמן ההתחלה והסיום |
| `status` | string | `completed` או `failed` |
| `end_reason` | string | ראו את הטבלה להלן |
| `product`, `voice` | string | תצורת הסוכן שהייתה בתוקף בזמן השיחה |
| `transfer_number` | string \| null | מוגדר כאשר השיחה הועברה |
| `recording_url` | string \| null | כתובת URL חתומה שתוקפה פג; הורידו בהקדם. `null` עבור סשנים ללא הקלטה |
| `billable_minutes` | number | דקות לחיוב, מעוגלות לרבע הדקה הקרוב ביותר (מרווחים של 15 שניות, מינימום 0.25). שיחות שמגיעות ישירות לתא קולי מחויבות בתעריף קבוע של 1¢ במקום זאת. |
| `billing_total_cents` | integer | סנטים של דולר אמריקאי |
| `transcripts` | array | תמליל לכל תור — ראו את הסעיף הבא |
### סיבות סיום
| ערך | משמעות |
| ------------------ | ------------------------------------------------------------ |
| `user_hangup` | הצד המרוחק ניתק ראשון |
| `ai_hangup` | הבינה המלאכותית סיימה את השיחה במכוון |
| `ai_transfer` | הבינה המלאכותית העבירה את השיחה; `transfer_number` מוגדר |
| `ai_warm_transfer` | הבינה המלאכותית השלימה העברה חמה (בליווי נציג) |
| `voicemail_hangup` | זוהתה תא קולי והשיחה הסתיימה בהתאם ל-`voicemail_action` שלכם |
| `max_duration` | השיחה הגיעה למגבלת משך הזמן המרבי |
| `superseded` | הסשן הוחלף בסשן חדש יותר |
| `unknown` | לא ניתן היה לקבוע את סיבת הסיום |
## פורמט התמליל
כל רשומה ב-`transcripts` היא תור שיחה אחד. התפקידים הם
`user` (דיבור המתקשר), `model` (דיבור הסוכן **וגם** קריאות לכלים),
`tool` (תוצאות כלים) ו-`system` (אירועי שיחה כגון החלפות
שפה).
```json theme={null}
[
{
"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` | string | `user`, `model`, `tool` או `system` |
| `content_type` | string | `text/plain` לדיבור; `application/json` לקריאות לכלים, תוצאות כלים ואירועי מערכת |
| `content` | string \| object | טקסט דיבור, או האובייקט המובנה המוצג למעלה. קריאות לכלים: `{"tool_call": name, "arguments": {…}}`. תוצאות כלים: `{"tool_name": name, "response": {…}}` |
| `start_ms`, `end_ms` | integer | היסטים מתחילת השיחה, במילישניות. קיימים כאשר תזמון האודיו ידוע |
| `ttfa_ms` | integer | זמן עד לאודיו הראשון עבור תור `model`, כאשר הוא נמדד |
| `audio_url`, `audio_urls` | string / array | כתובות URL חתומות שפג תוקפן עבור אודיו התור, כאשר ההקלטה מתבצעת לפי תור |
להיסטוריית התורים המובנית במלואה (עם סמני הפרעה,
הנחיות אישור ומיקומים גולמיים), השתמשו ב-
[`GET /v1/calls/{call_id}/history`](/api-reference/calls#get-history).
## הבדלים במטען הנתונים הישן
מעטפת ה-webhook הישנה עם כתובת URL יחידה היא
`{"type": "telephony.complete" | "web.complete", "data": {…}}` ללא
**`event_id`**, וה-`data` שלה שונה ממטען הנתונים של נקודת הקצה:
* מערך התורים נמצא תחת **`history`**, ולא תחת `transcripts` (אותה
סכמת תור כמו למעלה).
* קבוצת השדות היא דוח גולמי של סוף השיחה, ויכולה לכלול
שדות פנימיים נוספים מעבר לטבלה שלמעלה — התייחסו לשדות לא מוכרים כמידע בלבד.
* שיחות ווב (`direction: "web"`) **משמיטות** את `from_number` / `to_number`
ומוסיפות את `origin_domain`.
* שיחות בדיקת מיקרופון ב-Builder מדווחות כ-`telephony.complete` בנתיב
הישן (מערכת נקודת הקצה ממפה אותן ל-`web.complete`).
* **תיאום העברה:** כאשר שיחה מסתיימת בהעברה, ה-webhook הישן נקרא באופן סינכרוני ועשוי להחזיר
`{"transfer_ready": false}` כדי לציין שיעד ההעברה אינו
מוכן. כל תגובה אחרת (או היעדר webhook ישן) מאפשרת להעברה
להמשיך. מסירות לנקודת הקצה לעולם אינן נבדקות לצורך כך.
***
## מטפל לדוגמה
```python Python (FastAPI) theme={null}
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}
```
```javascript Node.js (Express) theme={null}
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 });
},
);
```
***
## תרחישי שימוש נפוצים
שמרו את תמליל כל שיחה ואת כתובת ה-URL של ההקלטה לצד
רשומות הלקוחות שלכם.
הזרימו תמלילים למערך לצורך מידול נושאים, חילוץ
אותות CSAT או ניטור שיעורי העברה.
פתחו שיחות בכלי QA לסקירה אנושית, או העבירו אותן דרך
מודל ההערכה שלכם.
הפעילו התראה לנציג אנושי בעת העברה או כשל.
***
## קשור
המקבילה החוסמת שפועלת בתחילת השיחה.
סוגי אירועים נוספים שתוכלו להירשם אליהם.
אותם נתונים זמינים באמצעות REST למילוי נתונים חסרים או להפעלה חוזרת.