> ## 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
> خطاف ويب غير حاجب يُسلَّم عند انتهاء المكالمة، ويتضمن النص المفرغ ورابط التسجيل والمقاييس.
يتم تشغيل حدث إكمال بعد انتهاء كل مكالمة — الاتصالات الهاتفية الواردة،
والاتصالات الهاتفية الصادرة، أو مكالمة الويب، أو مكالمة اختبار (جلسة ميكروفون أداة الإنشاء). وهو
**غير حاجب**: استجب بأي رمز 2xx.
يتم تسليم الحدث عبر كلا المسارين:
* تستقبل **[نقاط نهاية Webhook](/ar/webhooks/endpoints)**
`telephony.complete` (المكالمات الهاتفية) أو `web.complete` (مكالمات الويب ومكالمات اختبار الميكروفون في أداة الإنشاء)
بحمولة ثابتة موثقة أدناه،
و`event_id` لكل عملية تسليم، ومهلة قدرها 30 ثانية، و
[إعادات محاولة لمدة تصل إلى 24 ساعة](/ar/webhooks/overview).
* يستقبل **[Webhook أحادي الرابط القديم](/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 });
},
);
```
***
## حالات الاستخدام الشائعة
احفظ النص المفرغ لكل مكالمة ورابط التسجيل إلى جانب
سجلات العملاء.
دفق النصوص المفرغة إلى مسار معالجة لنمذجة الموضوعات، أو استخراج
مؤشرات CSAT، أو مراقبة معدل التحويل.
افتح المكالمات في أداة QA لمراجعة بشرية، أو مررها عبر
نموذج التقييم الخاص بك.
نبّه زميلاً بشرياً عند التحويل أو الفشل.
***
## ذو صلة
النظير الحاجب الذي يعمل عند بدء المكالمة.
أنواع أحداث أخرى يمكنك الاشتراك فيها.
البيانات نفسها متاحة عبر REST للملء اللاحق أو إعادة التشغيل.