> ## 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. # Danh mục sự kiện > Tất cả loại sự kiện webhook mà ThunderPhone phát ra. Mọi nội dung webhook đều có trường `type` với giá trị là một trong các loại sự kiện trên trang này. Khi bạn đăng ký một [endpoint](/vi/webhooks/endpoints), mảng `events` phải chứa các loại sự kiện bạn muốn nhận (hoặc để trống để đăng ký mọi sự kiện). Có hai kiểu gửi các sự kiện này: * **Gửi đến endpoint** luôn là thông báo **không chặn** có [cơ chế thử lại](/vi/webhooks/overview): phản hồi bằng bất kỳ mã 2xx nào; envelope chứa `event_id` để khử trùng lặp. * Các trao đổi **chặn** chỉ chạy trên [webhook URL đơn cũ](/vi/webhooks/overview): yêu cầu cấu hình [`telephony.incoming` / `web.incoming`](/vi/webhooks/call-incoming) (số ở chế độ webhook và khóa widget, thời gian chờ 10 giây) và [điều phối tool](/vi/tools/overview) ở chế độ webhook. Phản hồi của bạn định hình cuộc gọi trực tiếp. Các payload ví dụ bên dưới hiển thị envelope endpoint theo thứ tự trên wire (các khóa được sắp xếp theo thứ tự chữ cái: `data`, `event_id`, `type`); các lần gửi cũ có cùng `data` nhưng không có `event_id`. ## Sự kiện cuộc gọi ### `telephony.incoming` Được gửi khi một cuộc gọi đến đến một trong các [số điện thoại](/api-reference/phone-numbers) của bạn. Các lần gửi đến endpoint là thông báo fire-and-forget được gửi cho **mọi** cuộc gọi đến, dù số đó được cấu hình tác nhân AI hay cấu hình webhook. Các số không có tác nhân AI được chỉ định cũng nhận yêu cầu cấu hình **chặn** trên webhook cũ — xem [`telephony.incoming` / `web.incoming`](/vi/webhooks/call-incoming) để biết schema yêu cầu / phản hồi đầy đủ. ```json theme={null} { "data": { "call_id": 987654321, "from_number": "+14155550199", "to_number": "+15551234567" }, "event_id": "3f6b2ad0-1c9e-4a57-9f2b-8f6f0f9d2f11", "type": "telephony.incoming" } ``` ### `telephony.complete` Được gửi khi một cuộc gọi viễn thông đến hoặc đi kết thúc. Không chặn. Bao gồm bản chép lời đầy đủ, URL bản ghi âm và tóm tắt thanh toán. Xem [`telephony.complete` / `web.complete`](/vi/webhooks/call-complete) để biết schema payload. ### `telephony.tool` Được gửi sau khi một cuộc gọi viễn thông gọi một [công cụ hàm](/vi/tools/overview). Thông báo kiểm tra không chặn — công cụ đã được thực thi khi sự kiện này được gửi; sự kiện này bao gồm các công cụ hàm của riêng bạn (không bao gồm công cụ tích hợp sẵn, cơ sở kiến thức, kết nối ứng dụng hoặc MCP). ```json theme={null} { "data": { "arguments": { "date": "2026-04-21" }, "call_id": 987654321, "from_number": "+14155550199", "response": { "response": { "available_slots": ["9:00 AM", "2:00 PM"] }, "status": 200 }, "to_number": "+15551234567", "tool_name": "search_appointments" }, "event_id": "1f0a7c3e-52d4-4a0e-8f4b-b1a6a1c0d9e2", "type": "telephony.tool" } ``` `response` là kết quả đã thực thi: `{"status": , "response": }` khi thành công hoặc `{"status": , "error": ""}` khi thất bại. ### `web.incoming` Tương đương với `telephony.incoming` trên kênh web, được gửi khi một phiên [widget web](/vi/widget/overview) hoặc cuộc gọi kiểm tra mic trong trình tạo bắt đầu. Các lần gửi đến endpoint là fire-and-forget cho mọi phiên web. Các khóa có thể công khai trong `mode="webhook"` cũng nhận yêu cầu cấu hình **chặn** trên webhook cũ — yêu cầu chặn đó có cấu trúc khác (`origin_domain`, `publishable_key_prefix`; không có số điện thoại). Xem [`telephony.incoming` / `web.incoming`](/vi/webhooks/call-incoming). ```json theme={null} { "data": { "call_id": 987654322, "from_number": "web", "origin_domain": "https://example.com", "publishable_key_prefix": "pk_live_a1b2", "to_number": "+15551234567" }, "event_id": "9a2b4c6d-8e0f-4a1b-9c2d-3e4f5a6b7c8d", "type": "web.incoming" } ``` `from_number` luôn là giá trị chuỗi `"web"`. Với các phiên widget ở chế độ webhook, `to_number` trống (số tác nhân AI của phiên được chỉ định sau khi cấu hình); với các cuộc gọi kiểm tra mic trong trình tạo, `origin_domain` và `publishable_key_prefix` trống. ### `web.complete` Tương đương với `telephony.complete` trên kênh web, bao gồm các cuộc gọi widget web (`direction: "web"`) và cuộc gọi kiểm tra mic trong trình tạo (`direction: "test"`). Không chặn. Có cấu trúc payload giống [`telephony.complete`](/vi/webhooks/call-complete), bổ sung `origin_domain`, với `from_number` được đặt thành `"web"`. Trên webhook cũ có một URL duy nhất, các cuộc gọi kiểm tra mic trong trình tạo trước đây được báo cáo là `telephony.complete` — chỉ các cuộc gọi `direction: "web"` mới sử dụng loại `web.complete` tại đó. Hệ thống endpoint ánh xạ cả cuộc gọi web và cuộc gọi kiểm tra thành `web.*`. Payload cũ có thể chứa các giá trị `direction` cũ là `widget` hoặc `mic`. ### `web.tool` Tương đương với `telephony.tool` trên kênh web. `data` chứa `origin_domain` thay vì `from_number` / `to_number`. *** ## Sự kiện chất lượng ### `call.graded` Được gửi mỗi khi một [lần chạy chấm điểm AI](/api-reference/calls#ai-call-grading) hoàn tất cho một cuộc gọi. Không chặn. ```json theme={null} { "data": { "call_id": 987654321, "grade": { "call_outcome": "success", "created_at": "2026-04-20T18:25:11.002Z", "detected_issues": [], "graded_at": "2026-04-20T18:25:11.002Z", "grader_model": "heuristic-v1", "id": 5512, "score": 92, "status": "completed", "summary": "Caller asked about their policy and got a full answer…" } }, "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f", "type": "call.graded" } ``` | Trường | Loại | Mô tả | | ------------------------------------- | --------------- | --------------------------------------------------------------- | | `grade.id` | integer | ID điểm đánh giá | | `grade.score` | integer \| null | 0–100 | | `grade.call_outcome` | string | `success`, `failure`, `unknown` hoặc `no_conversation` | | `grade.summary` | string | Tóm tắt một đoạn | | `grade.detected_issues` | array | Chuỗi mô tả vấn đề do trình chấm điểm tìm thấy | | `grade.status` | string | Luôn là `completed` — chỉ các lần chạy đã hoàn tất mới được gửi | | `grade.grader_model` | string | Trình chấm điểm nào tạo ra kết quả (ví dụ: `heuristic-v1`) | | `grade.graded_at`, `grade.created_at` | timestamp | | Một cuộc gọi có thể được chấm điểm nhiều lần — điểm đánh giá heuristic nhanh thường được theo sau bởi điểm đánh giá từ mô hình đầy đủ khi bản ghi âm khả dụng, và cũng có thể chấm điểm lại thủ công. Mỗi lần chạy hoàn tất sẽ gửi sự kiện `call.graded` riêng; coi `graded_at` mới nhất là nguồn xác thực. ### `issue.reported` Được gửi khi một [báo cáo vấn đề](/api-reference/issue-reports) được tạo — do người dùng gửi từ dashboard (`source: "user"`) hoặc tự động bởi quá trình chấm điểm cuộc gọi (`source: "system"`). Không chặn. ```json theme={null} { "data": { "call_id": 987654321, "issue_report": { "created_at": "2026-04-20T18:25:11.002Z", "description": "Five-second silence before responding to the main question.", "id": 4321, "severity": "warning", "source": "system", "status": "open", "title": "Agent paused too long" } }, "event_id": "5e6f7a8b-9c0d-4e1f-8a2b-3c4d5e6f7a8b", "type": "issue.reported" } ``` | Trường | Loại | Mô tả | | ----------------------- | ------ | ------------------------------------------------------------------------------- | | `issue_report.severity` | string | `critical`, `warning` hoặc `info` | | `issue_report.status` | string | `open` hoặc `resolved` | | `issue_report.source` | string | `user` (được gửi từ dashboard) hoặc `system` (được tạo bởi quá trình chấm điểm) | Chấm điểm lại một cuộc gọi sẽ tạo lại các báo cáo vấn đề do hệ thống tạo, từ đó gửi lại `issue.reported` cho các báo cáo được tạo lại. Khử trùng lặp theo `call_id` + `title` nếu bạn chỉ muốn một thông báo cho mỗi vấn đề cơ bản. *** ## Sự kiện cuộc gọi kiểm thử ### `test-call.completed` Được gửi khi một [lần chạy cuộc gọi kiểm thử](/api-reference/test-calls#test-call-run-object) đạt trạng thái kết thúc — `completed` hoặc `failed`, bao gồm cả các lần chạy thất bại khi khởi chạy và không bao giờ tạo cuộc gọi. Không chặn. Hữu ích để kết nối các lần chạy CI hàng loạt với hệ thống chat/thông báo của bạn. ```json theme={null} { "data": { "test_call_run": { "call_id": 987654321, "completed_at": "2026-04-20T18:25:04.822Z", "error_message": "", "id": 7110, "status": "completed", "target_id": 12, "target_type": "agent" } }, "event_id": "2b3c4d5e-6f7a-4b8c-9d0e-1f2a3b4c5d6e", "type": "test-call.completed" } ``` | Trường | Loại | Mô tả | | ----------------------------- | --------------- | --------------------------------------------------------------------------------- | | `test_call_run.target_type` | string | `agent` hoặc `phone_number` | | `test_call_run.target_id` | integer | ID tác nhân AI hoặc ID số điện thoại mà lần chạy nhắm đến, khớp với `target_type` | | `test_call_run.status` | string | `completed` hoặc `failed` | | `test_call_run.call_id` | integer \| null | `null` khi lần chạy thất bại trước khi thực hiện cuộc gọi | | `test_call_run.error_message` | string | Trống khi thành công | *** ## Sự kiện cảnh báo ### `alert.triggered` Được gửi khi một [quy tắc cảnh báo](/vi/guides/alerts) có kênh **Gửi đến webhook nhà phát triển** được bật vượt ngưỡng. Không chặn. Một quy tắc kích hoạt một lần rồi tuân theo thời gian hồi, vì vậy một vi phạm kéo dài tạo một sự kiện cho mỗi khoảng thời gian hồi. ```json theme={null} { "data": { "comparator": "lt", "event_id": "b8e6a1d4-2c3f-4a5b-9c8d-7e6f5a4b3c2d", "fired_at": "2026-04-20T18:00:00+00:00", "metric": "success_rate", "metric_value": 71.4, "rule_id": "d2c3b4a5-6f7e-4d8c-9b0a-1c2d3e4f5a6b", "rule_name": "Success rate below 80%", "threshold": 80.0, "window_hours": 24 }, "event_id": "4d5e6f7a-8b9c-4d0e-9f1a-2b3c4d5e6f7a", "type": "alert.triggered" } ``` | Trường | Loại | Mô tả | | ------------------------- | ------------ | ---------------------------------------------------------------------------------- | | `event_id` (trong `data`) | UUID | ID **kích hoạt** cảnh báo — khác với `event_id` dùng để phân phối của envelope | | `rule_id`, `rule_name` | UUID, string | Quy tắc đã kích hoạt | | `metric` | string | `success_rate`, `failure_rate`, `avg_score`, `call_volume` hoặc `suite_regression` | | `comparator` | string | `lt`, `lte`, `gt` hoặc `gte` | | `metric_value` | number | Giá trị của chỉ số trong khoảng thời gian khi quy tắc kích hoạt | | `threshold` | number | Ngưỡng đã cấu hình | | `window_hours` | integer | Khoảng thời gian đánh giá lùi | | `fired_at` | timestamp | | Xem [hướng dẫn Cảnh báo](/vi/guides/alerts) để tạo quy tắc, chỉ số, thời gian hồi và các kênh email / Slack. *** ## Liên quan Payload cuộc gọi đến có tính chặn mà bạn phải phản hồi. Bản ghi cuộc gọi và chỉ số sau cuộc gọi. Đăng ký một URL cho một tập hợp con của các sự kiện này. Cách các sự kiện `telephony.tool` / `web.tool` được tạo.