Danh mục sự kiện

Mọi phần thân 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ý tất cả). 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; phần bao chứa event_id để khử trùng lặp.
Các trao đổi chặn chỉ chạy trên webhook URL đơn kế thừa: 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 công cụ ở 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 thể hiện phần bao endpoint theo thứ tự trên wire (các khóa được sắp xếp theo bảng chữ cái: data, event_id, type); các lần gửi kế thừa mang 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. Việc gửi đến endpoint là thông báo gửi đi mà không cần chờ phản hồi cho mọi cuộc gọi đến, bất kể số đó được cấu hình tác nhân AI hay webhook. Các số không được gán tác nhân AI 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, URL bản ghi khi có và bản 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 do bạn tự tạo (không bao gồm công cụ tích hợp sẵn, cơ sở tri 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. Việc gửi đến endpoint là gửi đi mà không cần chờ phản hồi 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à chuỗi nguyên văn "web". Với các phiên widget ở chế độ webhook, to_number để trống (số của tác nhân AI cho phiên được gán 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ùng cấu trúc payload với telephony.complete, cộng thêm origin_domain, với from_number được đặt thành "web".

Trên webhook cũ dùng 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 có direction: "web" mới 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.*. Các 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 cho from_number / to_number.

Sự kiện giọng nói

Việc tạo giọng nói tùy chỉnh diễn ra không đồng bộ. Các sự kiện không chặn này cho phép bạn phản hồi một kết quả cuối cùng thay vì thăm dò endpoint chi tiết bản sao.

`voice.ready`

Được gửi khi một giọng nói tùy chỉnh hoàn tất xử lý và có thể được gán cho một tác nhân AI.

{
  "data": {
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "ready",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "2d5f0a61-e9b5-4a3c-b684-29d7d9e4b214",
  "type": "voice.ready"
}

`voice.failed`

Được gửi khi quá trình xử lý giọng nói tùy chỉnh gặp lỗi vĩnh viễn.

{
  "data": {
    "reason": "audio sample could not be processed",
    "voice": {
      "created_at": "2026-07-30T14:12:08.317Z",
      "display_name": "Support voice",
      "failure_reason": "audio sample could not be processed",
      "gender": "female",
      "id": "cv_2f6f90b0e9a34ee8b39be7d1",
      "language": "en",
      "name": "custom:cv_2f6f90b0e9a34ee8b39be7d1",
      "status": "failed",
      "updated_at": "2026-07-30T14:13:31.605Z"
    }
  },
  "event_id": "3493e985-1a75-4f77-a10a-e74af440cd31",
  "type": "voice.failed"
}

Trường	Kiểu	Mô tả
`voice.id`	string	ID công khai của giọng nói tùy chỉnh
`voice.name`	string	Giá trị giọng nói của tác nhân AI theo dạng `custom:<public_id>`
`voice.display_name`	string	Tên giọng nói hiển thị cho tổ chức
`voice.language`	string	Mã ngôn ngữ duy nhất của bản sao
`voice.gender`	string	`male`, `female` hoặc chuỗi rỗng
`voice.status`	string	`ready` cho `voice.ready`; `failed` cho `voice.failed`
`voice.failure_reason`	string	Rỗng khi thành công; chi tiết lỗi xử lý khi thất bại
`voice.created_at`, `voice.updated_at`	timestamp	Dấu thời gian ISO 8601
`reason`	string	Chi tiết lỗi; chỉ có trong `voice.failed`

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

`call.graded`

Được gửi mỗi khi một lần 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
`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 đề được trình chấm điểm phát hiện
`grade.status`	string	Luôn là `completed` — chỉ các lần chạy đã hoàn tất mới phát sự kiện
`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 heuristic nhanh thường được theo sau bởi điểm từ mô hình đầy đủ sau khi bản ghi âm sẵn sàng, và cũng có thể chấm lại thủ công. Mỗi lần chạy hoàn tất phát sự kiện call.graded riêng; coi graded_at mới nhất là giá trị chính xá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 được tạo tự động bằng 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` (gửi từ dashboard) hoặc `system` (được tạo bằng chấm điểm)

Chấ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, khiến issue.reported được phát lại 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 theo lô 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 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 cuộc gọi được thực hiện
`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 qua ngưỡng của nó. Không chặn. Một quy tắc chỉ kích hoạt một lần rồi tuân thủ thời gian chờ, vì vậy một vi phạm kéo dài sẽ tạo một sự kiện cho mỗi khoảng thời gian chờ.

{
  "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ủa cảnh báo — khác với `event_id` phân phối của envelope
`rule_id`, `rule_name`	UUID, chuỗi	Quy tắc đã kích hoạt
`metric`	chuỗi	`success_rate`, `failure_rate`, `avg_score`, `call_volume` hoặc `suite_regression`
`comparator`	chuỗi	`lt`, `lte`, `gt` hoặc `gte`
`metric_value`	số	Giá trị của chỉ số trong khoảng thời gian khi quy tắc kích hoạt
`threshold`	số	Ngưỡng đã cấu hình
`window_hours`	số nguyên	Khoảng thời gian đánh giá gần nhất
`fired_at`	dấu thời gian

Xem hướng dẫn Cảnh báo để tạo quy tắc, chỉ số, thời gian chờ 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 chép lời và chỉ số sau cuộc gọi.

Điểm cuối webhook

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

Công cụ hàm

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

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 giọng nói

`voice.ready`

`voice.failed`

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 giọng nói

​voice.ready

​voice.failed

​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 giọng nói

`voice.ready`

`voice.failed`

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