事件参考

每个端点最多可订阅六种事件类型。每个请求都使用相同的信封——event、timestamp、guild_id 和 data——只有 data 对象不同。

事件	触发时机
`ticket.created`	工单被创建时
`ticket.closed`	工单被关闭时
`ticket.updated`	打开的工单发生其他任何变更时
`message.sent`	成员或客服在工单中发言时
`blacklist.added`	成员被加入黑名单时
`blacklist.removed`	黑名单条目被移除时

无法解析的字段会以 null 发送，而不是被省略——因此你可以依赖这些键始终存在。当 Discord 没有返回用户时，username 为 null。

共享字段

每个工单事件都包含这些字段：

字段	类型	描述
`ticket_id`	`string`	来自你模板的可读工单 ID，例如 `ticket-1042`
`ticket_num_id`	`number`	递增的工单编号，例如 `1042`
`channel_id`	`string`	该工单对应的 Discord 频道
`category`	`string \| null`	分类名称；如果工单没有分类则为 `null`
`user`	`object \| null`	工单所有者，格式为 `{ id, username }`

ticket.created

在工单频道创建后立即发送。

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

这会在工单被打开时触发，也就是成员还没有写任何内容之前。如果你需要第一条消息，也请监听 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"
  }
}

字段	类型	描述
`closed_by`	`object`	谁关闭了它。自动关闭会显示机器人
`reason`	`string \| null`	关闭原因；如果没有提供则为 `null`

ticket.updated

用于打开工单的所有变更。action 告诉你发生了什么，changes 则包含该具体操作的详细信息。

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

可能的 `action` 值

`action`	含义	`changes` 包含
`ticket_claim:add`	客服成员认领了工单	(空)
`ticket_unclaim:add`	认领已被取消	(空)
`ticket_priority:add`	优先级已更改	`priority`
`ticket_rename:add`	频道已重命名	`new_name`
`ticket_remind:add`	已发送提醒	(空)
`ticket_feedback:add`	成员对工单进行了评分	`star_count`、`feedback`
`ticket_schedule_close:add`	已安排关闭	`duration`、`schedule_time`
`ticket_request_close:add`	客服要求成员关闭工单	`duration`、`request_duration_time`
`ticket_request_close_accept:add`	成员已接受	(空)
`ticket_request_close_deny:add`	成员已拒绝	(空)
`ticket_close_cancel:add`	正在进行的关闭已取消	(空)
`ticket_additional_access:add`	用户或角色已被添加到工单	`entity_type`、`entity_id`、`reason`
`ticket_additional_access:remove`	用户或角色已被移除	`entity_type`、`entity_id`、`reason`

请将此列表视为开放式。随着 TicketWave 的发展，会不断新增动作，它们都会以 ticket.updated 的形式到达。请只处理你关心的动作，其余忽略，不要在遇到未知值时直接报错。

回答工单步骤不会产生事件。否则，一个包含很多步骤的工单会在成员填写表单时不断向你的端点发送请求。

message.sent

在打开的工单内，每条人工消息都会发送。来自机器人的消息——包括 TicketWave 自己——会被跳过。

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

字段	类型	描述
`content`	`string`	原始消息文本。仅包含附件的消息则为空
`author`	`object`	发送者的 `{ id, username }`
`is_staff`	`boolean`	如果发送者拥有已配置的支持角色，则为 `true`

这是请求量最高的事件，远远高于其他事件——繁忙的服务器每条消息都会产生一次请求。只有在你确实需要消息级数据时才订阅它，并确保你的接收端能快速响应。

blacklist.added

与工单无关，因此这个负载没有 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" }
  }
}

测试事件

发送测试事件按钮会发送一条真实的、已签名的请求，其 data 仅为：

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

event 是该端点订阅的第一个类型。如果你想在生产逻辑中跳过测试投递，请检查 data.test。

下一步

示例服务器（在 Express 中处理这些负载）
Webhooks（签名、重试和投递历史）

事件参考

On this page