Danh mục sự kiện

Cấu trúc payload

Mỗi sự kiện là một đối tượng JSON:

{
  "id": "evt_01HKQN9…",
  "type": "conversation.created",
  "occurred_at": "2026-04-20T14:23:45.123Z",
  "account_id": "7c1d2c6e-…",
  "site_id": "0f3a…",
  "data": { … the resource, in the same shape the API returns it … }
}

id là giá trị trong header X-RolChat-Event-Id và không đổi qua các lần thử lại. type có dạng <domain>.<noun>.<verb> hoặc <domain>.<verb> theo snake_case. data chứa tài nguyên đúng như endpoint GET tương ứng sẽ trả về, nên bộ nhận có thể được viết dựa trên tài liệu API mà không bao giờ cần schema thứ hai.

Các nhóm sự kiện

Nhóm	Ví dụ	Được gửi khi
conversation.*	conversation.created, conversation.assigned, conversation.resolved, conversation.reopened, conversation.merged	Cuộc trò chuyện đổi trạng thái hoặc người phụ trách
message.*	message.created, message.delivered, message.read, message.failed	Tin nhắn được gửi hoặc trạng thái gửi thay đổi
crm.*	crm.lead.created, crm.contact.created, crm.contact.updated, crm.contact.merged, crm.deal.stage_changed, crm.deal.won	Khách hàng tiềm năng, liên hệ, công ty hoặc giao dịch thay đổi
ticket.*	ticket.created, ticket.status_changed, ticket.assigned, ticket.sla_breached	Ticket thay đổi
visitor.*	visitor.identified, visitor.cobrowse.requested	Khách truy cập được nhận diện hoặc yêu cầu phiên cobrowse
marketing.*	marketing.form.submitted, marketing.booking.created, marketing.campaign.sent, marketing.unsubscribed	Biểu mẫu, đặt lịch, chiến dịch
kb.*	kb.article.published, kb.article.unpublished	Thay đổi trong cơ sở tri thức
phone.*	phone.call.started, phone.call.ended, phone.call.recorded, phone.call.transcribed, phone.voicemail.received	Cuộc gọi và hộp thư thoại
automation.*	automation.rule.executed, automation.rule.failed	Một quy tắc tự động hóa chạy
privacy.*	privacy.consent.granted, privacy.consent.withdrawn, privacy.dsr.received	Sự đồng ý và yêu cầu của chủ thể dữ liệu
billing.*	billing.invoice.created, billing.trial_expiring, billing.subscription.changed	Gói đăng ký và hóa đơn
auth.*	auth.api_key.created, auth.api_key.revoked, auth.account.swapped	Sự kiện tài khoản liên quan đến bảo mật
ai.*	ai.usage.recorded	Mọi lệnh gọi adapter AI, kèm số token

Danh sách chính xác mở rộng theo sản phẩm; màn hình đăng ký hiển thị mọi loại mà tài khoản của bạn có thể nhận và cho phép lọc theo loại.

Đăng ký

Đăng ký webhook thuộc về một plugin. Trong Cài đặt → Plugin, mở plugin (hoặc tạo plugin tùy chỉnh) và thêm một endpoint: URL HTTPS, các loại sự kiện bạn muốn và danh sách IP được phép (tùy chọn). Khóa ký chỉ hiển thị một lần. Các lần gửi, thử lại và dead letter của endpoint đó xuất hiện trong Nhật ký webhook của plugin.

Plugin Protocol trên trang Plugin mô tả cách một plugin khai báo các sự kiện nó cần trong manifest.

Thứ tự và cơ chế gửi

• Việc gửi đảm bảo ít nhất một lần. Hãy loại bỏ trùng lặp theo id.
• Sự kiện của một tài nguyên được gửi theo thứ tự, nhưng các lần thử lại có thể làm đảo thứ tự. Hãy dùng occurred_at và updated_at của tài nguyên thay vì thời điểm nhận.
• Một đăng ký liên tục thất bại sẽ tích lũy dead letter; hơn 100 dead letter cho một endpoint sẽ kích hoạt cảnh báo phía RolChat và hiển thị cảnh báo trong nhật ký của plugin.