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).

Hai kiểu gửi mang các sự kiện này:

• Các lần gửi 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 kiểu cũ: yêu cầu cấu hình telephony.incoming / web.incoming (số ở chế độ webhook: 13 giây, bao gồm một lần thử lại; khóa widget ở chế độ webhook: 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 hiển thị envelope endpoint theo thứ tự trên wire (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 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 không chờ phản hồ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 sẽ nhận thêm yêu cầu cấu hình chặn trên webhook cũ — xem telephony.incoming / web.incoming để biết đầy đủ schema yêu cầu / phản hồi.

{
  "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à 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. Đây là 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 bao gồm các công cụ hàm của riêng bạn và công cụ tích hợp sẵn send_sms (không bao gồm công cụ tích hợp sẵn khác, cơ sở kiến thức, kết nối ứng dụng hoặc công cụ MCP). Với send_sms, cả arguments.to và arguments.body đều là [REDACTED]. Bản chép lời khi hoàn tất cũng ẩn chúng; truy xuất nội dung và người nhận từ tài nguyên SMS theo phạm vi tổ chức bằng message_id trong phản hồi.

{
  "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 cuộc gọi viễn thông đang diễn ra, một lần cho mỗi lượt có lời nói ngay khi lượt đó xảy ra — phần trả lời được nói của tác nhân AI và lượt của người gọi được chép lời. Cho phép bạn theo dõi cuộc trò chuyện trực tiếp qua webhook đơn thuần 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. Việc gửi đến endpoint là gửi đi không chờ phản hồi cho mọi phiên web. Khóa có thể công khai ở mode="webhook" sẽ nhận thêm 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 ký tự "web". Với 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 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 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 cho from_number / to_number.

web.turn#

Tương đương trên kênh web của telephony.turn, bao gồm 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 cho from_number / to_number. Giống 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.

call.transfer_completed#

Được gửi một lần cho mỗi cuộc gọi cùng kết quả cuối cùng của chuyển cuộc gọi: chuyển lạnh hoặc cầu nối giữa hai người mà chuyển ấm để lại sau khi tác nhân AI rời cuộc gọi. Không chặn và chỉ được gửi đến endpoint (không bao giờ đến webhook một URL cũ). Sự kiện đến sau telephony.complete của cuộc gọi: khi nhà cung cấp tiếp nhận cuộc gọi hoặc việc chuyển thất bại, hoặc khi ThunderPhone tạo cầu nối cho cuộc gọi, sau khi cầu nối kết thúc.

{
  "data": {
    "agent_id": 12,
    "agent_name": "Front desk",
    "bridge_kind": "cold_fallback",
    "bridge_seconds": 255,
    "bridge_total_cents": 5,
    "call_id": 987654321,
    "destination": "+15555550102",
    "sip_status": 403,
    "transfer_outcome": "bridged"
  },
  "event_id": "5b0f6c1e-9d2a-5e7b-8c4d-1a2b3c4d5e6f",
  "type": "call.transfer_completed"
}

Các giá trị tương tự cũng có trên đối tượng cuộc gọi dưới dạng transfer_outcome, transfer_destination, transfer_sip_status, transfer_bridge_kind, transfer_bridge_seconds và transfer_bridge_total_cents. event_id giống nhau trên mọi lần gửi cho một cuộc gọi, vì vậy báo cáo lặp lại không bao giờ tạo sự kiện thứ hai.

Sự kiện SMS#

Sự kiện SMS mô tả tin nhắn được gửi qua tài khoản Twilio hoặc Telnyx đã kết nối của tổ chức. Nội dung tin nhắn được lược bỏ và to được che giấu. Truy xuất tin nhắn trong phạm vi tổ chức từ GET /v1/sms/{message_id} khi cần nội dung hoặc người nhận.

sms.sent#

Được gửi khi nhà mạng của khách hàng chấp nhận yêu cầu gửi SMS. Đây không phải biên nhận đã gửi đến thiết bị.

{
  "data": {
    "accepted_at": "2026-09-19T15:42:10.113Z",
    "agent_id": 12,
    "call_id": 987654321,
    "created_at": "2026-09-19T15:42:09.901Z",
    "direction": "outbound",
    "error_code": null,
    "error_message": null,
    "from_number": "+15551234567",
    "id": "313a3117-827b-46e9-a01a-ac1493838724",
    "provider": "twilio",
    "provider_id": "SM0123456789abcdef0123456789abcdef",
    "segment_count": 1,
    "source": "agent_tool",
    "status": "accepted",
    "to": "[REDACTED]"
  },
  "event_id": "0ae347b4-1716-45bb-9a0e-b52373586e37",
  "type": "sms.sent"
}

sms.failed#

Được gửi sau khi nhà mạng từ chối vĩnh viễn, sau khi đã hết lượt thử lại tạm thời hoặc khi kết quả không xác định một cách cuối cùng. error_code là mã ThunderPhone ổn định và error_message nêu hành động khách hàng cần thực hiện khi có. status: "unknown" nghĩa là nhà mạng có thể đã chấp nhận SMS; hãy đối chiếu trong nhật ký nhà mạng vì ThunderPhone sẽ không tự động gửi lại.

sms.received#

Dành riêng cho hỗ trợ SMS đến. Không có sự kiện sms.received nào được phát ra trong bản phát hành hiện tại. Cấu hình webhook nhà mạng cho SMS đến và xác minh chữ ký sẽ được phát hành riêng.

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 ứng với kết quả cuối cùng thay vì thăm dò điểm cuối thông tin chi tiết bản sao.

voice.ready và voice.failed chỉ được gửi đến điểm cuối toàn tổ chức có events: []. Không thể chọn chúng làm bộ lọc sự kiện rõ ràng.

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ần chấm điểm cuộc gọi bằng 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…"
    },
    "report": null
  },
  "event_id": "7c1d2e3f-4a5b-4c6d-8e9f-0a1b2c3d4e5f",
  "type": "call.graded"
}

call.data_extracted#

Được gửi mỗi khi quá trình trích xuất dữ liệu có cấu trúc hoàn tất thành công, bao gồm lần thử lại muộn sau telephony.complete / web.complete hoặc lần chạy lại thủ công qua POST /v1/calls/{call_id}/extract. Không chặn.

Ở chế độ trích xuất chặn, sự kiện hoàn tất thông thường chờ không quá ngân sách trích xuất 75 giây. Nếu tiến trình worker trích xuất bị mất, quy trình xử lý hoàn tất trong môi trường production (mỗi năm phút) sẽ giải phóng một sự kiện hoàn tất có blocking_deadline_at đã qua trước khi bắt đầu một lần thử trích xuất khác. Thành công muộn hơn được gửi riêng dưới dạng sự kiện này.

{
  "data": {
    "call_id": 987654321,
    "agent_id": 12,
    "agent_name": "Acme intake",
    "extracted_data": {
      "status": "completed",
      "fields": {
        "customer_name": "Alex Morgan",
        "appointment_date": "2026-04-23"
      },
      "evidence": {
        "customer_name": {
          "quote": "My name is Alex Morgan",
          "speaker_role": "caller",
          "turn_index": 4
        },
        "appointment_date": {
          "quote": "April 23 works for me",
          "speaker_role": "caller",
          "turn_index": 7
        }
      },
      "verification": "verified",
      "field_reasons": {},
      "schema_version": "92850758e231a3c95a..."
    },
    "extracted_at": "2026-04-20T18:25:11.002Z",
    "model": "<model id>",
    "summary": "Alex Morgan called to book a follow-up visit and confirmed Thursday, April 23."
  },
  "event_id": "4d79ef1d-c2b1-4ed6-85b8-8326bd2895ef",
  "type": "call.data_extracted"
}

campaign.completed#

Được gửi một lần khi chiến dịch chuyển từ running sang completed, dù lịch chạy kết thúc hay mọi liên hệ đã đạt trạng thái cuối. Các lần thử lại của runner không gửi thêm sự kiện. Sự kiện vòng đời cấp tổ chức này chỉ được gửi đến endpoint phạm vi tổ chức, không gửi đến endpoint phạm vi tác nhân. Không chặn.

{
  "data": {
    "campaign_id": "3f6b2c9e-2a0d-4c63-b6d6-a708dc98f403",
    "name": "May win-back",
    "agent_id": 12,
    "status": "completed",
    "started_at": "2026-04-20T17:00:00Z",
    "completed_at": "2026-04-20T18:25:11Z",
    "counts": {
      "contacts_total": 150,
      "completed": 121,
      "failed": 11,
      "no_answer": 18,
      "remaining": 0
    }
  },
  "event_id": "8d8f52ce-6b46-423f-9dde-cea0b91ec135",
  "type": "campaign.completed"
}

Bốn số lượng kết quả không chồng lấp và tổng bằng contacts_total: completed chứa các liên hệ thành công; no_answer chứa các liên hệ thất bại/đã hết lượt thử ở trạng thái cuối là không trả lời; failed chứa mọi liên hệ thất bại/đã hết lượt thử ở trạng thái cuối khác; và remaining chứa các liên hệ đang chờ, đã lên lịch hoặc hiện đang gọi. Một liên hệ đang chờ thử lại là remaining, kể cả khi lần thử gần nhất không được trả lời. Các cuộc gọi đang diễn ra được đối soát trước ảnh chụp hoàn tất chỉ diễn ra một lần. started_at là thời điểm bắt đầu chiến dịch đã cấu hình, hoặc thời điểm tạo chiến dịch khi chưa cấu hình thời điểm bắt đầu.

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 tính nă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"
}

issue.escalated#

Được gửi khi một mẫu vấn đề được chuyển đến ThunderPhone để đội ngũ xem xét: sau khi Báo cáo cho ThunderPhone, hoặc khi Khắc phục bằng AI không thể xác nhận cách khắc phục phía khách hàng và tự động chuyển vấn đề. Chỉ các endpoint phạm vi toàn tổ chức nhận được sự kiện này.

{
  "data": {
    "automatic": false,
    "cluster_id": "7ac2844c-2df0-4fa8-a560-7378da649e19",
    "escalation_id": "ec99f52b-c8c0-41dd-a4f2-dd8a07b10894",
    "status": "open"
  },
  "event_id": "d8f8f420-7a42-45ba-bcf1-b747f9bbecda",
  "type": "issue.escalated"
}

Đây là thông báo, không phải gói bằng chứng. Dùng cluster_id để liên kết với mẫu vấn đề. Xem Báo cáo cho ThunderPhone.

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"
}

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. Không chặn. Một quy tắc chỉ kích hoạt một lần rồi tuân theo thời gian chờ, do đó một vi phạm kéo dài 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.

Sự kiện di chuyển#

migration.call.complete#

Được gửi khi một cuộc gọi được thực hiện qua POST /v1/migrations/{id}/calls kết thúc, bất kể nền tảng nào thực hiện cuộc gọi đó. Không chặn. Sự kiện này đến trong khoảng tối đa 5 phút sau khi cuộc gọi kết thúc. data có mọi trường của telephony.complete cùng với một khối migration. Một cuộc gọi do ThunderPhone thực hiện cũng gửi telephony.complete như thông thường, với cùng call_id. Một cuộc gọi trên nền tảng khác chưa kết thúc sau 2 giờ, hoặc có quá trình di chuyển đã hoàn tất hoặc mất khóa trước đó, sẽ được gửi với status: "unknown" và không có bản chép lời.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "billable_minutes": null,
    "billing_total_cents": null,
    "call_id": null,
    "direction": "outbound",
    "duration_seconds": 94,
    "end_reason": "user_hangup",
    "end_time": "2026-10-06T17:01:34+00:00",
    "extracted_data": null,
    "from_number": "+15551234567",
    "migration": {
      "arm": "vendor",
      "id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
      "metadata": {
        "lead_id": "8812"
      },
      "routing_id": "9b2f8c1e-4d3a-4f6b-8e2d-1a7c5b9e0f34",
      "vendor": "retell",
      "vendor_call_id": "call_6a1f0e",
      "vendor_cost_usd": "0.1240"
    },
    "product": "",
    "recording_mode": "vendor",
    "recording_url": "https://…",
    "start_time": "2026-10-06T17:00:00+00:00",
    "status": "completed",
    "summary": "The callee booked a table for two on Thursday.",
    "thunderphone_retained_call_content": true,
    "to_number": "+14155552671",
    "transcripts": [
      {
        "content": "Hi Ada, this is Rosa's calling about your booking.",
        "role": "agent"
      },
      {
        "content": "Yes, Thursday works.",
        "role": "user"
      }
    ],
    "transfer_number": null,
    "unresolved_variables": [],
    "variables": {
      "first_name": "Ada"
    },
    "voice": ""
  },
  "event_id": "7c1e2f3a-4b5c-4d6e-8f7a-9b0c1d2e3f4a",
  "type": "migration.call.complete"
}

Đối với cuộc gọi vendor, ThunderPhone không có dữ liệu thanh toán hoặc trích xuất: billable_minutes, billing_total_cents và extracted_data là null, product và voice để trống, recording_mode là vendor, và recording_url là liên kết của nền tảng khác, nếu nền tảng đó cung cấp.

migration.rollback#

Được gửi khi quá trình chuyển đổi dần của một đợt migration tự động chuyển mọi cuộc gọi trở lại nền tảng còn lại: 3 cuộc gọi không kết nối được với ThunderPhone trong vòng 15 phút, 2 cuộc gọi được gửi đến ThunderPhone kết thúc trước khi tác nhân AI trả lời, hoặc tỷ lệ kết quả tác vụ của ThunderPhone thấp hơn tỷ lệ của nền tảng còn lại vượt quá mức chênh lệch đã cấu hình. Không chặn, một lần cho mỗi lần hoàn tác. Sau đó, tỷ lệ cuộc gọi của ThunderPhone là 0% và migration bị tạm dừng cho đến khi có người tiếp tục nó trong tab Migration của tác nhân AI. Payload không chứa số điện thoại, bản chép lời hoặc ID cuộc gọi.

{
  "data": {
    "agent_id": 42,
    "agent_name": "Front desk",
    "dropped": 0,
    "migration_id": "5f0c2a9e-7b1d-4c3e-8a6f-2d9e1b4c7a30",
    "ours": {
      "graded": 20,
      "success_rate": 0.8
    },
    "ours_failed": 3,
    "ours_percent": 0,
    "previous_percent": 25,
    "reason": "ours_failed_burst",
    "rolled_back_at": "2026-10-10T12:05:00+00:00",
    "step": 1,
    "theirs": {
      "graded": 20,
      "success_rate": 0.8
    },
    "vendor": "retell"
  },
  "event_id": "3d1f6b2a-8c4e-5a7b-9d0e-2f1a3b4c5d6e",
  "type": "migration.rollback"
}

Liên quan#