Tham chiếu sự kiện

Có thể đăng ký sáu loại sự kiện cho mỗi endpoint. Mọi request đều dùng cùng một envelope — event, timestamp, guild_id và data — và chỉ đối tượng data là khác nhau.

Sự kiện	Kích hoạt khi
`ticket.created`	Một ticket được mở
`ticket.closed`	Một ticket được đóng
`ticket.updated`	Bất cứ thứ gì khác thay đổi trên một ticket đang mở
`message.sent`	Thành viên hoặc staff viết trong ticket
`blacklist.added`	Một thành viên bị đưa vào blacklist
`blacklist.removed`	Một mục blacklist được gỡ bỏ

Các trường không thể phân giải sẽ được gửi dưới dạng null thay vì bị bỏ qua — vì vậy bạn có thể tin rằng các key luôn tồn tại. username là null khi Discord không trả về người dùng.

Các trường dùng chung

Mọi sự kiện ticket đều có các trường sau:

Trường	Kiểu	Mô tả
`ticket_id`	`string`	ID ticket dễ đọc theo mẫu của bạn, ví dụ `ticket-1042`
`ticket_num_id`	`number`	Số ticket tăng dần, ví dụ `1042`
`channel_id`	`string`	Kênh Discord của ticket
`category`	`string \| null`	Tên danh mục, `null` nếu ticket không có
`user`	`object \| null`	Chủ ticket dưới dạng `{ id, username }`

ticket.created

Được gửi ngay sau khi kênh ticket tồn tại.

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T08:23:11.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1042",
    "ticket_num_id": 1042,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "created_at": "2026-08-26T08:23:11.000Z"
  }
}

Sự kiện này được kích hoạt khi ticket được mở, tức là trước khi thành viên viết bất cứ điều gì. Nếu bạn cần tin nhắn đầu tiên, hãy lắng nghe thêm message.sent.

ticket.closed

{
  "event": "ticket.closed",
  "timestamp": "2026-08-26T07:45:02.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1041",
    "ticket_num_id": 1041,
    "channel_id": "998877665544332211",
    "category": "💸 Payment",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "closed_by": { "id": "112233445566778899", "username": "Staff_01" },
    "reason": "Issue resolved",
    "closed_at": "2026-08-26T07:45:02.000Z"
  }
}

Trường	Kiểu	Mô tả
`closed_by`	`object`	Ai đã đóng ticket. Các lần đóng tự động sẽ báo bot
`reason`	`string \| null`	Lý do đóng, `null` nếu không có

ticket.updated

Sự kiện tổng quát cho các thay đổi trên một ticket đang mở. action cho bạn biết điều gì đã thay đổi, còn changes chứa chi tiết của hành động cụ thể đó.

{
  "event": "ticket.updated",
  "timestamp": "2026-08-26T14:02:19.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1038",
    "ticket_num_id": 1038,
    "channel_id": "998877665544332211",
    "category": "🤖 Support",
    "user": { "id": "987654321098765432", "username": "Luna" },
    "action": "ticket_priority:add",
    "changes": { "priority": "high" },
    "reason": null,
    "updated_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

Các giá trị `action` có thể có

`action`	Ý nghĩa	`changes` chứa
`ticket_claim:add`	Một staff đã nhận ticket	(trống)
`ticket_unclaim:add`	Việc nhận ticket đã được hủy	(trống)
`ticket_priority:add`	Độ ưu tiên đã thay đổi	`priority`
`ticket_rename:add`	Kênh đã được đổi tên	`new_name`
`ticket_remind:add`	Một lời nhắc đã được gửi	(trống)
`ticket_feedback:add`	Thành viên đã đánh giá ticket	`star_count`, `feedback`
`ticket_schedule_close:add`	Một lần đóng đã được lên lịch	`duration`, `schedule_time`
`ticket_request_close:add`	Staff đã yêu cầu thành viên đóng ticket	`duration`, `request_duration_time`
`ticket_request_close_accept:add`	Thành viên đã chấp nhận	(trống)
`ticket_request_close_deny:add`	Thành viên đã từ chối	(trống)
`ticket_close_cancel:add`	Một lần đóng đang diễn ra đã bị hủy	(trống)
`ticket_additional_access:add`	Một người dùng hoặc vai trò đã được thêm vào ticket	`entity_type`, `entity_id`, `reason`
`ticket_additional_access:remove`	Một người dùng hoặc vai trò đã bị xóa	`entity_type`, `entity_id`, `reason`

Hãy xem danh sách này là mở rộng. Các hành động mới sẽ được thêm khi TicketWave phát triển, và chúng sẽ xuất hiện dưới dạng ticket.updated. Hãy xử lý những action bạn quan tâm và bỏ qua phần còn lại thay vì ném lỗi với các giá trị không xác định.

Trả lời một bước của ticket sẽ không tạo ra sự kiện. Nếu không, một ticket có nhiều bước sẽ làm endpoint của bạn bị spam trong khi thành viên vẫn đang điền form.

message.sent

Được gửi cho mọi tin nhắn của người thật bên trong một ticket đang mở. Tin nhắn từ bot — bao gồm cả TicketWave — sẽ bị bỏ qua.

{
  "event": "message.sent",
  "timestamp": "2026-08-26T22:10:55.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "ticket_id": "ticket-1040",
    "ticket_num_id": 1040,
    "channel_id": "998877665544332211",
    "message_id": "1234567890123456789",
    "content": "Hello, how can I help you?",
    "author": { "id": "112233445566778899", "username": "Staff_01" },
    "is_staff": true,
    "sent_at": "2026-08-26T22:10:55.000Z"
  }
}

Trường	Kiểu	Mô tả
`content`	`string`	Nội dung thô của tin nhắn. Để trống với tin nhắn chỉ có tệp đính kèm
`author`	`object`	`{ id, username }` của người gửi
`is_staff`	`boolean`	`true` nếu người gửi có vai trò hỗ trợ đã được cấu hình

Đây là sự kiện có tần suất cao nhất rất nhiều — một máy chủ bận rộn sẽ tạo ra một request cho mỗi tin nhắn. Chỉ đăng ký nếu bạn thực sự cần dữ liệu ở mức tin nhắn, và hãy đảm bảo bên nhận phản hồi thật nhanh.

blacklist.added

Không gắn với ticket, nên payload này không có ticket_id.

{
  "event": "blacklist.added",
  "timestamp": "2026-08-26T18:33:47.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "user": { "id": "111223344556677889", "username": "BadActor" },
    "reason": "Spam",
    "added_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

blacklist.removed

{
  "event": "blacklist.removed",
  "timestamp": "2026-08-26T18:40:12.000Z",
  "guild_id": "123456789012345678",
  "data": {
    "user": { "id": "111223344556677889", "username": "BadActor" },
    "removed_by": { "id": "112233445566778899", "username": "Staff_01" }
  }
}

Sự kiện kiểm thử

Nút Send test event sẽ gửi một request thật, đã được ký, với data chỉ là:

{
  "event": "ticket.created",
  "timestamp": "2026-08-26T12:00:00.000Z",
  "guild_id": "123456789012345678",
  "data": { "test": true }
}

event là loại đầu tiên mà endpoint đã đăng ký. Hãy kiểm tra data.test nếu bạn muốn bỏ qua các lần gửi thử trong logic production.

Các bước tiếp theo

Example Server (Xử lý các payload này trong Express)
Webhooks (Ký, thử lại và lịch sử gửi)

Tham chiếu sự kiện

On this page