Webhooks

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, 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 — ngoại trừ các sự kiện theo từng lượt telephony.turn / web.turn, chỉ được gửi đến các endpoint nêu rõ chúng).

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ó thử lại: phản hồi bằng bất kỳ mã 2xx nào; phong bì 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, hết thời gian chờ sau 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 đang diễn ra.

Các payload ví dụ bên dưới hiển thị phong bì endpoint theo thứ tự truyền tải của nó (các khóa được sắp xếp theo thứ tự bảng chữ cái: data, event_id, type); các lần gửi cũ 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. Các lượt gửi đến endpoint là thông báo gửi và không chờ phản hồi cho mọi cuộc gọi đến, bất kể số đó được cấu hình cho 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 điện thoại đế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ó sẵn 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 điện thoại 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.

telephony.turn#

Được gửi trong khi một cuộc gọi điện thoại đang diễn ra, một lần cho mỗi lượt có lời nói ngay khi xảy ra — phần trả lời được nói của tác nhân AI và lượt được chép lời của người gọi. Cho phép bạn theo dõi cuộc trò chuyện trực tiếp qua webhook thông thường thay vì thăm dò GET /v1/calls/{call_id}/transcript. Không chặn.

{
  "data": {
    "call_id": 987654321,
    "entry_type": "completion",
    "from_number": "+14155550199",
    "position": 7,
    "role": "assistant",
    "start_ms": 15200,
    "text": "How many employees does your company have?",
    "to_number": "+15551234567"
  },
  "event_id": "8d3f5a2c-7b1e-4c9a-b6d0-2e4f6a8c0d1e",
  "type": "telephony.turn"
}

web.incoming#

Tương đương trên kênh web của telephony.incoming, đượ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ượt gửi đến endpoint là gửi và không chờ phản hồi cho mọi phiên web. Khóa có thể xuất bản 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ị cố định "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 gán sau khi cấu hình); với 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 trên kênh web của telephony.complete, 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".

web.tool#

Tương đương trên kênh web của telephony.tool. data chứa origin_domain thay vì from_number / to_number.

web.turn#

Tương đương trên kênh web của telephony.turn, bao gồm các cuộc gọi widget web và cuộc gọi kiểm tra mic trong trình tạo. Có cùng cấu trúc payload, với origin_domain thay vì from_number / to_number. Giống như telephony.turn, sự kiện này yêu cầu đăng ký rõ ràng — không bao giờ được gửi qua mảng events trống.

Sự kiện giọng nói#

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

voice.ready#

Được gửi khi 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"
}

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

call.graded#

Được gửi mỗi khi một lượt 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"
}

issue.reported#

Được gửi khi một báo cáo vấn đề được tạo — hoặc do người dùng gửi từ dashboard (source: "user") hoặc được tạo 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"
}

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

test-call.completed#

Được gửi khi một lượt 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ượt 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ượt 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"
}

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 dành cho nhà phát triển được bật vượt qua ngưỡng của quy tắc đó. 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 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"
}

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#