Danh mục sự kiện

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, 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: 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ũ: yêu cầu cấu hình telephony.incoming / web.incoming (số ở chế độ webhook và khóa widget, thời gian chờ 10 giây) và điều phối tool ở 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 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 để biết schema yêu cầu / phản hồi đầy đủ.

{
  "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 để 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. 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).

{
  "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": <http status>, "response": <your endpoint's JSON>} khi thành công hoặc {"status": <status>, "error": "<message>"} 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 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.

{
  "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, 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 hoàn tất cho một cuộc gọi. Không chặn.

{
  "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 đề đượ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.

{
  "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ử đạ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.

{
  "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 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.

{
  "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 để tạo quy tắc, chỉ số, thời gian hồi và các kênh email / Slack.

Liên quan

telephony.incoming / web.incoming

Payload cuộc gọi đến có tính chặn mà bạn phải phản hồi.

telephony.complete / web.complete

Bản ghi cuộc gọi và chỉ số sau cuộc gọi.

Điểm cuối webhook

Đăng ký một URL cho một tập hợp con của các sự kiện này.

Công cụ hàm

Cách các sự kiện telephony.tool / web.tool được tạo.

Webhooks

Function Tools

Sự kiện cuộc gọi

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Sự kiện chất lượng

`call.graded`

`issue.reported`

Sự kiện cuộc gọi kiểm thử

`test-call.completed`

Sự kiện cảnh báo

`alert.triggered`

Liên quan

telephony.incoming / web.incoming

telephony.complete / web.complete

Điểm cuối webhook

Công cụ hàm

​Sự kiện cuộc gọi

​telephony.incoming

​telephony.complete

​telephony.tool

​web.incoming

​web.complete

​web.tool

​Sự kiện chất lượng

​call.graded

​issue.reported

​Sự kiện cuộc gọi kiểm thử

​test-call.completed

​Sự kiện cảnh báo

​alert.triggered

​Liên quan

telephony.incoming / web.incoming

telephony.complete / web.complete

Điểm cuối webhook

Công cụ hàm

Sự kiện cuộc gọi

`telephony.incoming`

`telephony.complete`

`telephony.tool`

`web.incoming`

`web.complete`

`web.tool`

Sự kiện chất lượng

`call.graded`

`issue.reported`

Sự kiện cuộc gọi kiểm thử

`test-call.completed`

Sự kiện cảnh báo

`alert.triggered`

Liên quan