事件回调

应用内的用户、好友、群组、消息、聊天室、通话、内容安全和文件发生变化后，IM 服务把变化以事件的形式发送到订阅了它的回调地址。本页列出全部事件类型、触发时机和 data 的字段。请求的公共格式、响应和重试见回调概述，签名校验见验证回调请求。

每个事件的 data 都有 origin 字段，说明事件由谁引起（client / server / platform / system），含义见origin：事件由谁引起，下文各表格不再重复列出。各表格中的时间都是 UTC 时间字符串，用户都以用户名表示，已删除的用户为 null。以后会增加字段和事件类型，请忽略不认识的字段和事件类型。

订阅事件

在控制台为每个回调地址选择要接收的事件，见回调配置。每项写法如下，最多 50 项：

完整的事件类型，如 friend.added；
{前缀}.*，如 group.*，订阅这一类的全部事件，以后这一类新增的事件也会自动订阅。前缀是事件类型中第一个点之前的部分：user.* 包括登录类的 user.session_created 等；friend.* 不包括 friend_request.* 和 blacklist.changed；message.* 包括量很大的消息抄送 message.sent，chatroom.* 包括聊天室的消息抄送 chatroom.message_sent，只需要撤回、编辑或聊天室的管理变化时，请写完整的事件类型。

不认识的类型和前缀，保存时返回 400 invalid_argument，details.reason 为 unknown_event_type，details.event_type 为不认识的那一项。

过滤条件

每个回调地址可以设置以下过滤条件，不满足的事件不发送到这个地址：

过滤条件	默认	说明
不接收由租户服务端引起的事件（`skip_server_initiated`）	关闭	开启后不接收 `origin` 为 `server` 的事件，即你的服务端通过 OpenAPI、你在控制台做的操作，如服务端添加的好友、建的群、发送的消息。例外：撤回事件 `message.recalled`、`chatroom.message_recalled` 照常接收，保存了消息副本的业务必须得知每一次撤回；`presence.changed` 没有来源，不受影响
不接收因账号删除连带产生的事件（`skip_user_deletion_cascade`）	关闭	删除一个用户时，他的每个好友会收到一条 `friend.removed`、他所在的每个群各有一条 `group.members_removed`，`reason` 都是 `user_deleted`。你已经从 `user.status_changed` 得知他被删除，开启后不再逐条接收
消息的会话类型（`message_conversation_types`）	单聊和群聊	只作用于 `message.*` 事件，可以只接收单聊或只接收群聊的消息
接收群提示（`message_include_tips`）	关闭	群提示（如“某某加入了群聊”）是 `type` 为 `tip` 的 `message.sent`，内容与群事件重复，默认不发送

取消订阅、修改过滤条件只影响之后的事件，已经排队的照常发送。

事件一览

类别	事件类型	触发时机
用户	`user.created`	用户注册：客户端注册、服务端或控制台创建
	`user.status_changed`	用户被封禁、解封（包括到期自动解封）或删除
	`user.profile_changed`	用户的昵称、头像或自定义属性被修改
	`user.mute_changed`	设置或解除全局禁言
登录	`user.session_created`	用户在一台设备上登录
	`user.sessions_revoked`	登录会话被吊销：退出、被踢、被挤下线、修改密码、会话过期等
	`user.relogin_required`	要求应用内全部用户重新登录
在线状态	`presence.changed`	用户上线、下线，或在线的平台多了、少了一个（尽力而为）
好友	`friend.added`	成为好友，双方各一个事件
	`friend.removed`	解除好友关系，双方各一个事件
	`friend.updated`	好友的备注或自定义属性被修改
	`friend_request.received`	收到需要同意的好友申请
	`friend_request.declined`	好友申请被拒绝
	`blacklist.changed`	拉黑或移出黑名单
群组	`group.created`	建群
	`group.info_changed`	群资料、设置、全员禁言、群主变化，群被封禁或解封
	`group.dismissed`	群被解散
	`group.members_added`	成员加入，一次操作一个事件
	`group.members_removed`	成员退出、被移出、被拉入群黑名单或账号被删除
	`group.members_updated`	成员的角色、群昵称、成员属性、禁言变化
	`group.request_created`	有新的入群申请或邀请
	`group.request_handled`	入群申请或邀请被同意、拒绝、撤回或自动失效
消息	`message.sent`	消息抄送：每写入一条单聊、群聊消息一个事件
	`message.recalled`	消息被撤回
	`message.edited`	消息被编辑
聊天室	`chatroom.created`	创建聊天室
	`chatroom.info_changed`	聊天室的资料、设置、所有者和管理员变化，被封禁或解封
	`chatroom.dismissed`	聊天室被解散
	`chatroom.members_muted`、`chatroom.members_unmuted`	成员被禁言、解除禁言
	`chatroom.members_kicked`	成员被移出
	`chatroom.members_banned`、`chatroom.members_unbanned`	成员被封禁、解封
	`chatroom.allowlist_changed`	白名单变化
	`chatroom.attributes_changed`	聊天室的属性变化
	`chatroom.message_sent`	聊天室的消息抄送（尽力而为）
	`chatroom.message_recalled`	聊天室的消息被撤回（尽力而为）
音视频	`rtc.call_created`	发起通话
	`rtc.call_answered`	通话接通
	`rtc.member_joined`	成员加入群通话
	`rtc.member_left`	成员离开群通话
	`rtc.call_ended`	通话结束，带时长
独立频道	`rtc_channel.created`	创建频道
	`rtc_channel.updated`	频道资料更新
	`rtc_channel.closing`	频道开始关闭
	`rtc_channel.closed`	频道完成关闭
	`rtc_channel.session_joined`	会话确认入会
	`rtc_channel.session_leaving`	会话开始退出
	`rtc_channel.session_left`	会话完成退出
	`rtc_channel.member_banned`	频道封禁变化
	`rtc_channel.member_unbanned`	频道解除封禁
内容安全	`moderation.item_created`	有新的待审核记录
	`moderation.item_decided`	审核记录有了结论
	`moderation.report_created`	用户举报
	`moderation.violation_recorded`	记下一次违规，可能触发自动处罚
文件	`media.file_uploaded`	文件上传完成
	`media.file_blocked`	文件被屏蔽
	`media.file_unblocked`	文件被解除屏蔽

好友申请被标记为已读、聊天室成员的进入和离开、消息的已读回执和表情回应不提供回调。

用户

user.created

用户注册成功后发送，包括用户在客户端注册、你的服务端调用创建用户和在控制台创建。

字段	类型	说明
`username`	String	用户名
`created_via`	String	创建的入口：`client` 客户端注册，`openapi` 服务端创建，`console` 控制台创建

json

{
  "origin": "server",
  "username": "alice",
  "created_via": "openapi"
}

user.status_changed

用户被封禁、解封（包括封禁到期自动解封）或被删除后发送。封禁和删除时，用户的登录会话一并失效，不再另外发送 user.sessions_revoked。

字段	类型	说明
`username`	String	用户名，删除时为删除前的用户名
`status`	String	变化后的状态：`active` 正常（解封），`disabled` 已封禁，`deleted` 已删除

json

{
  "origin": "server",
  "username": "erin",
  "status": "disabled"
}

user.profile_changed

用户的昵称、头像或自定义属性被修改后发送，包括用户在客户端修改和服务端修改。事件不带修改的内容，需要时用查询用户读取。

字段	类型	说明
`username`	String	用户名
`version`	Number	修改后的资料版本号，比你保存的大时才需要重新读取

json

{
  "origin": "client",
  "username": "bob",
  "version": 2
}

user.mute_changed

设置或解除全局禁言后发送，每个禁言场景一个事件。禁言到期自动解除时不发送。

字段	类型	说明
`username`	String	用户名
`scope`	String	禁言的场景：`chat` 单聊，`group` 群聊，`room` 聊天室
`muted`	Boolean	`true` 设置禁言，`false` 解除禁言
`expires_at`	String	禁言的到期时间；永久禁言和解除禁言时为 `null`

json

{
  "origin": "server",
  "username": "bob",
  "scope": "chat",
  "muted": true,
  "expires_at": "2026-10-04T20:22:07.207Z"
}

字段	类型	说明
`username`	String	用户名
`session_id`	String	登录会话 ID，与查询登录设备中的相同
`device_id`	String	设备标识
`device_name`	String	设备名称，没有填写时为空字符串
`platform`	String	平台，如 `ios`、`android`、`web`
`login_method`	String	登录方式：`password` 密码登录，`ticket` 凭证登录
`created_at`	String	登录时间，六位微秒，如 `2026-10-04T19:21:11.735215Z`

json

{
  "origin": "client",
  "username": "alice",
  "session_id": "100311275329814528",
  "device_id": "5f0c2a9e-7d1b-4c7e-9a51-2f6d0f3b8c11",
  "device_name": "iPhone 15",
  "platform": "ios",
  "login_method": "password",
  "created_at": "2026-10-04T19:21:11.735215Z"
}

user.sessions_revoked

用户的登录会话被吊销后发送：本人退出、同一设备重新登录、超出设备数被挤下线、被踢下线、修改密码、refresh token 被重复使用、会话过期。封禁、删除用户和要求全部用户重新登录时不逐个发送，分别见 user.status_changed 和 user.relogin_required。

字段	类型	说明
`username`	String	用户名
`session_ids`	Array<String>	被吊销的会话 ID。为空数组时表示这个用户登录时间早于 `revoked_before` 的全部会话，不能把之后才登录的会话一并处理掉
`revoked_before`	String	吊销的界限，六位微秒
`reason`	String	原因：`logout` 本人退出，以及 `replaced`、`device_limit`、`kicked`、`password_changed`、`token_reuse`、`expired`，含义见下线原因
`by_device_name`	String	原因为 `replaced` 或 `device_limit` 时，挤掉这些会话的新设备的名称；其他原因为 `null`
`by_platform`	String	同上，新设备的平台

json

{
  "origin": "client",
  "username": "alice",
  "session_ids": ["100315151017705472"],
  "revoked_before": "2026-10-04T19:36:35.885537Z",
  "reason": "replaced",
  "by_device_name": "iPhone 15 Pro",
  "by_platform": "ios"
}

服务端踢下线全部设备时，session_ids 为空数组：

json

{
  "origin": "server",
  "username": "frank",
  "session_ids": [],
  "revoked_before": "2026-10-04T19:22:07.496243Z",
  "reason": "kicked",
  "by_device_name": null,
  "by_platform": null
}

user.relogin_required

在控制台要求应用内全部用户重新登录后发送一次，不逐个用户发送。

字段	类型	说明
`sessions_revoked_before`	String	登录时间早于它的全部会话都已失效，六位微秒

json

{
  "origin": "server",
  "sessions_revoked_before": "2026-10-04T19:36:25.378490Z"
}

在线状态

presence.changed

用户的在线平台集合变化时发送：从离线到在线、从在线到离线、在线期间多了或少了一个平台（如手机在线时又在电脑上登录）。同一个平台的第二台设备上线、网络切换后同一会话的重连不改变在线的平台，不发送。在线的含义见在线状态。

这个事件是尽力而为的（见尽力而为的事件），也不保证顺序，请按 version 判断新旧，忽略不大于已处理版本的事件。设备异常断网时，服务端最迟约 90 秒（App 在后台时约 6 分钟）才能发现，这段时间内仍为在线。量可能很大，订阅前请确认接收端的处理能力，并开启合并。事件与应用是否开启了客户端的在线状态无关。

字段	类型	说明
`username`	String	用户名
`online`	Boolean	变化后是否在线
`platforms`	Array<String>	变化后在线的平台，按字母排序；离线时为空数组
`version`	Number	版本号，同一个用户的事件按它排序
`last_seen_at`	String	最近离线的时间；在线时为 `null`
`cause`	String	触发变化的方式：`connect` 连接，`disconnect` 断开，`restore` 恢复，`cleanup` 服务端清理失效的连接
`session_id`	String	触发变化的登录会话 ID；`cause` 为 `cleanup` 时为 `null`
`platform`	String	触发变化的设备的平台；`cause` 为 `cleanup` 时为 `null`
`reason`	String	断开的原因，只在 `cause` 为 `disconnect` 时有，如 `client_closed` 客户端主动关闭、`network_error` 网络错误、`idle_timeout` 心跳超时、`connection_replaced` 被同一设备的新连接替换、`session_revoked` 会话被吊销；其他情况为 `null`

json

{
  "origin": null,
  "username": "bob",
  "online": false,
  "platforms": [],
  "version": 1791141956256,
  "last_seen_at": "2026-10-04T19:25:56.256Z",
  "cause": "disconnect",
  "session_id": "100311275719884800",
  "platform": "android",
  "reason": "client_closed"
}

好友

好友和黑名单的事件都站在一个用户（username）的角度描述他的列表的变化，version 是这个用户的好友列表或黑名单变化后的版本号。两人成为好友、解除好友关系时，双方各收到一个事件。相关接口见好友和好友申请。

friend.added

成为好友后，为双方各发送一个事件。

字段	类型	说明
`username`	String	好友列表的所有者
`friend_username`	String	新的好友
`friend_nickname`	String	好友当时的昵称
`friend_avatar_url`	String	好友当时的头像地址
`remark`	String	所有者给好友的备注
`attributes`	Object	好友的自定义属性，没有时为 `null`
`add_source`	String	添加来源，即申请时填写的 `add_source`，没有时为空字符串
`source`	String	好友关系是怎样建立的（站在所有者的角度）：`request_sent` 所有者发出的申请被对方同意；`request_auto` 所有者发送申请时直接成为好友（对方允许任何人添加，或对方已向所有者申请）；`request_accepted` 所有者同意了对方的申请；`auto_accepted` 所有者允许任何人添加，对方的申请被自动通过；`server` 你的服务端或控制台添加
`created_at`	String	好友关系的成立时间，双方相同
`version`	Number	所有者的好友列表的版本号

alice 的申请被 bob 同意后，bob 收到的事件：

json

{
  "origin": "client",
  "username": "bob",
  "friend_username": "alice",
  "friend_nickname": "爱丽丝",
  "friend_avatar_url": "",
  "remark": "爱丽丝",
  "attributes": null,
  "add_source": "search",
  "source": "request_accepted",
  "created_at": "2026-10-04T19:22:42.446Z",
  "version": 1
}

friend.removed

解除好友关系后，为双方各发送一个事件；一方的账号被删除时，为仍在的一方发送。

字段	类型	说明
`username`	String	好友列表的所有者
`friend_username`	String	被移除的好友，可为 `null`
`friend_created_at`	String	这段好友关系的成立时间，与 `friend.added` 的 `created_at` 相同，可以据此区分同两个人前后几段好友关系
`reason`	String	`self` 所有者删除，`peer` 对方删除，`server` 你的服务端或控制台删除，`user_deleted` 对方的账号被删除
`version`	Number	所有者的好友列表的版本号

json

{
  "origin": "client",
  "username": "alice",
  "friend_username": "bob",
  "friend_created_at": "2026-10-04T19:22:42.446Z",
  "reason": "self",
  "version": 4
}

账号被删除连带产生的事件，origin 为 system：

json

{
  "origin": "system",
  "username": "alice",
  "friend_username": "gone",
  "friend_created_at": "2026-10-04T19:26:37.099Z",
  "reason": "user_deleted",
  "version": 6
}

friend.updated

所有者修改好友的备注或自定义属性后发送。

字段	类型	说明
`username`	String	好友列表的所有者
`friend_username`	String	好友
`remark`	String	修改后的备注
`attributes`	Object	修改后的自定义属性，没有时为 `null`
`version`	Number	所有者的好友列表的版本号

json

{
  "origin": "client",
  "username": "alice",
  "friend_username": "bob",
  "remark": "老鲍",
  "attributes": { "tag": "同事" },
  "version": 3
}

friend_request.received

用户发送或重新发送需要对方同意的好友申请后发送。直接成为好友的申请（对方允许任何人添加，或双方互相申请）不发送这个事件，只发送 friend.added。

字段	类型	说明
`from_username`	String	申请人
`to_username`	String	被申请人
`message`	String	附言，经过内容安全检查后的内容
`add_source`	String	添加来源，没有时为空字符串
`requested_at`	String	申请时间

json

{
  "origin": "client",
  "from_username": "alice",
  "to_username": "bob",
  "message": "我是爱丽丝",
  "add_source": "search",
  "requested_at": "2026-10-04T19:22:42.403Z"
}

friend_request.declined

被申请人拒绝好友申请后发送，重复拒绝不再发送。申请被同意时发送 friend.added。

字段	类型	说明
`from_username`	String	申请人
`to_username`	String	被申请人，即拒绝的人
`handled_at`	String	拒绝的时间

json

{
  "origin": "client",
  "from_username": "carol",
  "to_username": "alice",
  "handled_at": "2026-10-04T19:22:42.604Z"
}

blacklist.changed

用户拉黑别人或把别人移出黑名单后发送。被删除的用户从别人的黑名单中移除时不发送。

字段	类型	说明
`username`	String	黑名单的所有者
`target_username`	String	被拉黑或被移出的用户
`blocked`	Boolean	`true` 拉黑，`false` 移出黑名单
`created_at`	String	拉黑的时间；移出时为 `null`
`version`	Number	所有者的黑名单的版本号

json

{
  "origin": "client",
  "username": "alice",
  "target_username": "dave",
  "blocked": true,
  "created_at": "2026-10-04T19:22:53.474Z",
  "version": 1
}

群组

群组的事件带变化后的版本号：群资料的 info_version 和成员列表的 member_version，请忽略版本号不大于你已处理的事件。operator 为执行操作的用户；为 null 表示由你的服务端、控制台、平台或系统执行，由 origin 区分。相关接口见群组管理和群成员。

group.created

建群后发送。建群时加入的初始成员另有一个 group.members_added（不含群主）。

字段	类型	说明
`group_id`	String	群 ID
`type`	String	群类型：`private` 私有群，`public` 公开群
`owner_username`	String	群主
`created_via`	String	创建的入口：`client`、`openapi`、`console`
`created_at`	String	建群时间

json

{
  "origin": "client",
  "group_id": "100311903108071424",
  "type": "private",
  "owner_username": "alice",
  "created_via": "client",
  "created_at": "2026-10-04T19:23:41.409Z"
}

group.info_changed

修改群资料、群设置、全员禁言，转让群主，以及群被封禁、解封后发送。

字段	类型	说明
`group_id`	String	群 ID
`info_version`	Number	变化后的群资料版本号
`changed`	Array<String>	变化了的字段名，如 `name`、`announcement`、`mute_all`、`owner`、`status`
`group`	Object	变化后完整的群信息，字段与群组对象相同，不含 `self`
`operator`	String	执行操作的用户，可为 `null`

json

{
  "origin": "client",
  "group_id": "100311903108071424",
  "info_version": 2,
  "changed": ["name", "announcement"],
  "group": {
    "group_id": "100311903108071424",
    "type": "private",
    "name": "项目组（二期）",
    "avatar_url": "",
    "description": "",
    "announcement": "周五评审",
    "announcement_updated_at": "2026-10-04T19:24:16.057Z",
    "announcement_updated_by": "alice",
    "attributes": null,
    "owner": "alice",
    "member_invite": "free",
    "join_mode": null,
    "mute_all": false,
    "max_members": 500,
    "max_members_setting": null,
    "member_count": 4,
    "status": "active",
    "disabled_by": null,
    "info_version": 2,
    "member_version": 4,
    "created_at": "2026-10-04T19:23:41.409Z"
  },
  "operator": "alice"
}

group.dismissed

群被解散后发送。

字段	类型	说明
`group_id`	String	群 ID
`info_version`	Number	解散后的群资料版本号
`dismissed_by`	String	谁解散的：`owner` 群主，`tenant` 你的服务端或控制台，`platform` 平台，`system` 系统
`dismissed_at`	String	解散时间

json

{
  "origin": "server",
  "group_id": "100311964139388928",
  "info_version": 2,
  "dismissed_by": "tenant",
  "dismissed_at": "2026-10-04T19:26:39.228Z"
}

group.members_added

成员加入后发送。一次操作（如一次邀请多人）只发送一个事件，members 中列出本次加入的全部成员。

字段	类型	说明
`group_id`	String	群 ID
`member_version`	Number	变化后的成员列表版本号
`member_count`	Number	变化后的群人数
`members`	Array<Object>	加入的成员，每项见下表
`operator`	String	执行操作的用户：邀请人、同意申请的群主或管理员、通过入群链接加入的本人；可为 `null`

members 中的每一项：

字段	类型	说明
`username`	String	成员
`role`	String	角色：`owner`、`admin`、`member`
`joined_via`	String	入群方式：`create` 建群时加入，`invite` 被邀请，`apply` 申请，`link` 入群链接或二维码，`server` 你的服务端或控制台添加
`inviter`	String	邀请人，没有时为 `null`；通过入群链接加入时为生成链接的人
`joined_at`	String	入群时间

json

{
  "origin": "client",
  "group_id": "100311903108071424",
  "member_version": 3,
  "member_count": 3,
  "members": [
    {
      "username": "bob",
      "role": "member",
      "joined_via": "invite",
      "inviter": "carol",
      "joined_at": "2026-10-04T19:23:55.911Z"
    }
  ],
  "operator": "carol"
}

group.members_removed

成员退出、被移出、被拉入群黑名单、账号被删除后发送，一次操作一个事件。

字段	类型	说明
`group_id`	String	群 ID
`member_version`	Number	变化后的成员列表版本号
`member_count`	Number	变化后的群人数
`members`	Array<Object>	离开的成员，每项为 `username` 和 `joined_at`（入群时间，可以据此区分同一个人前后几次入群）
`reason`	String	`left` 主动退出，`removed` 被移出，`blacklisted` 被拉入群黑名单，`user_deleted` 账号被删除
`operator`	String	执行操作的用户，可为 `null`

json

{
  "origin": "client",
  "group_id": "100311903108071424",
  "member_version": 7,
  "member_count": 3,
  "members": [
    { "username": "bob", "joined_at": "2026-10-04T19:23:55.911Z" }
  ],
  "reason": "removed",
  "operator": "alice"
}

group.members_updated

成员的角色、群昵称、成员属性、禁言变化后发送。转让群主时列出新旧两位群主。

字段	类型	说明
`group_id`	String	群 ID
`member_version`	Number	变化后的成员列表版本号
`members`	Array<Object>	变化后的成员信息，每项为 `username`、`role`、`group_nickname`、`attributes`、`muted`、`muted_until`、`joined_via`、`inviter`、`joined_at`，含义与群成员对象相同
`changed`	Array<String>	变化的内容：`role`、`group_nickname`、`attributes`、`mute`
`operator`	String	执行操作的用户，可为 `null`

json

{
  "origin": "client",
  "group_id": "100311903108071424",
  "member_version": 6,
  "members": [
    {
      "username": "bob",
      "role": "member",
      "group_nickname": "",
      "attributes": null,
      "muted": true,
      "muted_until": "2026-10-04T19:34:16.137Z",
      "joined_via": "invite",
      "inviter": "carol",
      "joined_at": "2026-10-04T19:23:55.911Z"
    }
  ],
  "changed": ["mute"],
  "operator": "alice"
}

group.request_created

有新的待处理的入群申请或邀请时发送。直接入群的申请和邀请不发送这个事件，只发送 group.members_added。

字段	类型	说明
`group_id`	String	群 ID
`kind`	String	种类：`application` 用户申请加入公开群，由群主或管理员审批；`invite_review` 普通成员在需要审批的群里邀请他人，由群主或管理员审批；`invitation` 等待被邀请人确认的邀请
`username`	String	要入群的用户
`inviter_username`	String	邀请人；`application` 为 `null`
`message`	String	申请理由或邀请附言
`requested_at`	String	申请或邀请的时间

json

{
  "origin": "client",
  "group_id": "100311964139388928",
  "kind": "application",
  "username": "bob",
  "inviter_username": null,
  "message": "我是鲍勃，想加入",
  "requested_at": "2026-10-04T19:24:05.593Z"
}

group.request_handled

入群申请或邀请被同意、拒绝、撤回或自动失效后发送。同意后入群的，另有 group.members_added。

字段	类型	说明
`group_id`	String	群 ID
`kind`	String	同 `group.request_created`
`username`	String	要入群的用户
`inviter_username`	String	邀请人，可为 `null`
`status`	String	结果：`accepted` 已同意，`declined` 已拒绝，`canceled` 已撤回或失效，`expired` 已过期
`reason`	String	拒绝的理由，没有时为空字符串
`cancel_cause`	String	`status` 为 `canceled` 时的原因：`withdrawn` 被撤回，`joined` 已通过其他途径入群，`blacklisted` 被拉入群黑名单，`group_private` 公开群改为私有群，`not_eligible` 审批时发现不能邀请这个人，`dismissed` 群已解散；其他情况为 `null`
`handled_by_username`	String	处理的人，可为 `null`

json

{
  "origin": "client",
  "group_id": "100311964139388928",
  "kind": "application",
  "username": "bob",
  "inviter_username": null,
  "status": "accepted",
  "reason": "",
  "cancel_cause": null,
  "handled_by_username": "alice"
}

消息

message.sent

消息抄送：订阅 message.sent 后，每写入一条单聊、群聊消息发送一个事件，包括用户在客户端发送的消息、你的服务端和控制台发送的消息、以系统身份发送的群消息，以及系统写入的消息（如通话结束后的通话记录）。以下消息不抄送：

群提示（type 为 tip），除非地址开启了“接收群提示”；
只推在线的消息：不保存，也不抄送；
被内容安全或发消息前回调拒绝的消息：没有写入，也不抄送。

字段	类型	说明
`conversation_id`	String	会话 ID；群聊为群 ID
`conversation_type`	String	`single` 单聊，`group` 群聊
`seq`	Number	消息在会话中的序号
`message_id`	String	消息 ID
`client_msg_id`	String	发送方给出的去重 ID；服务端发送时没有给的，为服务端生成的值
`sender_username`	String	发送者；以系统身份发送的群消息为 `null`
`sender_type`	String	`user` 用户，`system` 系统
`recipient_username`	String	单聊的接收者；群聊为 `null`
`group_id`	String	群聊的群 ID；单聊为 `null`
`type`	String	消息类型，如 `text`、`image`、`custom`、`call`，见消息格式
`body`	Object	消息体；内容不可用时为 `null`
`ext`	Object	扩展字段，没有时为 `null`
`mention_usernames`	Array<String>	被 @ 的成员，没有时为空数组
`mention_all`	Boolean	是否 @ 全体成员
`reply_seq`	Number	引用的消息的序号，没有引用时为 `null`
`need_receipt`	Boolean	是否要求群已读回执
`exclude_from_unread`	Boolean	是否不计入未读数
`via`	String	发送的入口：`client` 客户端，`openapi` 服务端，`console` 控制台，`system` 系统写入
`created_at`	String	消息的写入时间
`content_available`	Boolean	内容是否可用，通常为 `true`；见下文的内容的保留

json

{
  "origin": "client",
  "conversation_id": "100311903108071424",
  "conversation_type": "group",
  "seq": 10,
  "message_id": "100312173556793344",
  "client_msg_id": "c-0003",
  "sender_username": "alice",
  "sender_type": "user",
  "recipient_username": null,
  "group_id": "100311903108071424",
  "type": "text",
  "body": { "text": "明天上午十点评审 @卡罗尔" },
  "ext": null,
  "mention_usernames": ["carol"],
  "mention_all": false,
  "reply_seq": null,
  "need_receipt": false,
  "exclude_from_unread": false,
  "via": "client",
  "created_at": "2026-10-04T19:24:45.886Z",
  "content_available": true
}

事件中的消息是写入时的内容，即经过内容安全替换和发消息前回调改写之后的内容。事件中没有消息的推送选项。通话结束后系统写入的通话记录消息，type 为 call，via 为 system，origin 为 system：

json

{
  "origin": "system",
  "conversation_id": "100312173003145216",
  "conversation_type": "single",
  "seq": 10,
  "message_id": "100315480782274560",
  "client_msg_id": "sys_rtc_100315433877372928",
  "sender_username": "alice",
  "sender_type": "user",
  "recipient_username": "carol",
  "group_id": null,
  "type": "call",
  "body": {
    "call_id": "100315433877372928",
    "call_type": "single",
    "media": "audio",
    "result": "completed",
    "duration_seconds": 2,
    "started_at": "2026-10-04T19:37:43.207Z"
  },
  "ext": null,
  "mention_usernames": [],
  "mention_all": false,
  "reply_seq": null,
  "need_receipt": false,
  "exclude_from_unread": true,
  "via": "system",
  "created_at": "2026-10-04T19:37:54.390Z",
  "content_available": true
}

用好消息抄送

量：消息抄送的量与应用的消息量相同，每分钟 3 万条消息的应用每秒约 500 个事件。请为它单独使用一个回调地址，开启合并（每批事件数设为 50 到 100），按事件 ID 去重后批量写入你的存储。
撤回和编辑：要另外订阅 message.recalled、message.edited。归档消息的业务收到撤回事件后，请处理自己保存的副本：撤回之前已经抄送出去的内容无法收回。
补齐缺口：地址被暂停超过 24 小时、自动停用、积压达到上限，或应用不可用期间，有的消息不会抄送。需要完整归档时，用导出应用的消息按时间段补齐，按 message_id 去重。

内容的保留

投递成功后，投递队列中的消息内容随即清除；投递失败的，24 小时后清除其中的 body 和 ext，只保留 ID 等字段。之后重新投递时，系统按 message_id 查询消息的当前内容：消息已被撤回、擦除或已超过保留期的，body、ext 为 null，mention_usernames 为空数组，content_available 为 false。这样消息被撤回后，内容不会一直留在回调的队列中。message.edited、chatroom.message_sent 同样如此，聊天室的消息清除后无法再查到内容。

message.recalled

消息被撤回后发送，包括发送者、群主和管理员在客户端撤回，你的服务端和控制台撤回，以及内容安全的撤回。撤回事件不受“不接收由租户服务端引起的事件”的影响，你的服务端撤回的同样发送。事件不带消息的内容。

字段	类型	说明
`conversation_id`	String	会话 ID
`conversation_type`	String	`single` 或 `group`
`seq`	Number	被撤回的消息的序号
`message_id`	String	被撤回的消息的 ID
`sender_username`	String	原消息的发送者
`recipient_username`	String	单聊的接收者；群聊为 `null`
`group_id`	String	群聊的群 ID；单聊为 `null`
`recalled_by_username`	String	撤回的用户；服务端、控制台和平台撤回时为 `null`
`recalled_by_role`	String	撤回人的身份：`sender` 发送者本人，`owner` 群主，`admin` 群管理员，`server` 你的服务端或控制台，`platform` 平台
`recalled_at`	String	撤回时间

json

{
  "origin": "client",
  "conversation_id": "100312173003145216",
  "conversation_type": "single",
  "seq": 1,
  "message_id": "100312173024116736",
  "sender_username": "alice",
  "recipient_username": "carol",
  "group_id": null,
  "recalled_by_username": "alice",
  "recalled_by_role": "sender",
  "recalled_at": "2026-10-04T19:25:06.077Z"
}

message.edited

消息被编辑后发送，带编辑后的完整内容。

字段	类型	说明
`conversation_id`、`conversation_type`、`seq`、`message_id`、`client_msg_id`、`sender_username`、`recipient_username`、`group_id`、`type`		同 `message.sent`
`body`	Object	编辑后的消息体
`ext`	Object	编辑后的扩展字段，没有时为 `null`
`edited_at`	String	编辑时间
`edit_count`	Number	这条消息被编辑的次数
`via`	String	编辑的入口：`openapi` 或 `console`
`content_available`	Boolean	同 `message.sent`

json

{
  "origin": "server",
  "conversation_id": "100312173003145216",
  "conversation_type": "single",
  "seq": 2,
  "message_id": "100312173946863616",
  "client_msg_id": "c-0004",
  "sender_username": "alice",
  "recipient_username": "carol",
  "group_id": null,
  "type": "text",
  "body": { "text": "这条消息已被编辑" },
  "ext": null,
  "edited_at": "2026-10-04T19:25:06.125Z",
  "edit_count": 1,
  "via": "openapi",
  "content_available": true
}

聊天室

聊天室的管理事件中，operator 为执行操作的用户（你的服务端、平台和系统为 null），operator_role 为执行者的身份：owner 所有者，admin 管理员，member 成员，server 你的服务端或控制台，platform 平台，system 系统。聊天室的接口见聊天室管理。成员进入和离开聊天室不发送事件。

chatroom.created

创建聊天室后发送。

字段	类型	说明
`room_id`	String	聊天室 ID
`name`	String	名称
`avatar_url`	String	头像地址
`owner_username`	String	所有者，没有时为 `null`
`max_members`	Number	人数上限
`listed`	Boolean	是否出现在聊天室列表中
`created_via`	String	创建的入口：`client`、`openapi`、`console`
`created_by_username`	String	在客户端创建的用户；服务端和控制台创建时为 `null`
`created_at`	String	创建时间

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "name": "发布会直播间",
  "avatar_url": "",
  "owner_username": "alice",
  "max_members": 1000,
  "listed": true,
  "created_via": "openapi",
  "created_by_username": null,
  "created_at": "2026-10-04T19:25:42.214Z"
}

chatroom.info_changed

聊天室的资料、设置、全员禁言、所有者和管理员变化，以及被封禁、解封后发送。

字段	类型	说明
`room_id`	String	聊天室 ID
`info_version`	Number	变化后的资料版本号
`changed`	Array<String>	变化了的字段名
`room`	Object	变化后的聊天室信息，字段与聊天室对象相同，不含人数、`self` 等只在接口中返回的字段
`operator`、`operator_role`	String	执行者，见上文

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "info_version": 2,
  "changed": ["announcement"],
  "room": {
    "room_id": "100312409813549056",
    "name": "发布会直播间",
    "description": "",
    "avatar_url": "",
    "announcement": "九点开始",
    "announcement_updated_at": "2026-10-04T19:26:12.514Z",
    "announcement_updated_by": null,
    "owner": "alice",
    "admins": [],
    "max_members": 1000,
    "mute_all": false,
    "listed": true,
    "status": "active",
    "disabled_by": null,
    "info_version": 2,
    "attributes_version": 1,
    "created_at": "2026-10-04T19:25:42.214Z"
  },
  "operator": null,
  "operator_role": "server"
}

chatroom.dismissed

聊天室被解散后发送。

字段	类型	说明
`room_id`	String	聊天室 ID
`dismissed_by`	String	`owner` 所有者，`tenant` 你的服务端或控制台，`platform` 平台
`operator`	String	解散的用户，可为 `null`
`dismissed_at`	String	解散时间

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "dismissed_by": "tenant",
  "operator": null,
  "dismissed_at": "2026-10-04T19:26:26.838Z"
}

聊天室成员的变化

chatroom.members_muted、chatroom.members_unmuted、chatroom.members_kicked、chatroom.members_banned、chatroom.members_unbanned 在成员被禁言、解除禁言、移出、封禁、解封后发送，一次操作一个事件；chatroom.allowlist_changed 在白名单变化后发送。

字段	类型	说明
`room_id`	String	聊天室 ID
`members`	Array<Object>	涉及的成员，每项有 `username`；`members_muted` 另有 `muted_until`（禁言到期时间，永久为 `null`），`members_banned` 另有 `expires_at`（封禁到期时间，永久为 `null`）。`allowlist_changed` 没有这个字段
`added`、`removed`	Array<Object>	只有 `allowlist_changed` 有：加入、移出白名单的用户，每项有 `username`
`reason`	String	只有 `members_muted`、`members_banned` 有：禁言、封禁的原因
`operator`、`operator_role`	String	执行者，见上文

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "members": [
    { "username": "carol", "muted_until": "2026-10-04T19:36:12.225Z" }
  ],
  "reason": "刷屏",
  "operator": null,
  "operator_role": "server"
}

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "added": [{ "username": "dave" }],
  "removed": [],
  "operator": null,
  "operator_role": "server"
}

chatroom.attributes_changed

聊天室的属性被设置或删除后发送。

字段	类型	说明
`room_id`	String	聊天室 ID
`attributes_version`	Number	变化后的属性版本号
`set`	Object	设置的属性，键为属性名，值为对象：`value` 属性值，`owner_username` 设置它的用户（服务端设置的为 `null`），`auto_delete` 设置者离开时是否自动删除，`updated_at` 设置时间
`removed`	Array<String>	删除的属性名
`reason`	String	`set` 设置，`removed` 删除，`auto_deleted` 设置者离开后自动删除，`owner_deleted` 设置者的账号被删除
`operator`、`operator_role`	String	执行者，见上文

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "attributes_version": 1,
  "set": {
    "stage": {
      "value": "q&a",
      "owner_username": null,
      "auto_delete": false,
      "updated_at": "2026-10-04T19:26:12.470Z"
    }
  },
  "removed": [],
  "reason": "set",
  "operator": null,
  "operator_role": "server"
}

chatroom.message_sent

聊天室的消息抄送：每条推送出去的聊天室消息一个事件，包括客户端、服务端和控制台发送的消息。这个事件是尽力而为的，见尽力而为的事件；被丢弃的低优先级消息和被拒绝的消息不抄送。origin 按发送的入口：客户端为 client，服务端和控制台为 server，系统为 system。

字段	类型	说明
`room_id`	String	聊天室 ID
`message_id`	String	消息 ID
`client_msg_id`	String	发送方给出的去重 ID
`sender`	String	发送者；系统消息为 `null`
`sender_type`	String	`user` 或 `system`
`sender_role`	String	发送者在聊天室中的身份，如 `owner`、`admin`、`member`
`type`	String	消息类型
`body`	Object	消息体
`ext`	Object	扩展字段，没有时为 `null`
`priority`	String	优先级：`high`、`normal`、`low`
`via`	String	发送的入口：`client`、`openapi`、`console`、`system`
`created_at`	String	发送时间
`content_available`	Boolean	内容是否可用，见内容的保留

json

{
  "origin": "client",
  "room_id": "100312409813549056",
  "message_id": "100312464125591552",
  "client_msg_id": "r-0001",
  "sender": "bob",
  "sender_type": "user",
  "sender_role": "member",
  "type": "text",
  "body": { "text": "大家好" },
  "ext": null,
  "priority": "normal",
  "via": "client",
  "created_at": "2026-10-04T19:25:55.163Z",
  "content_available": true
}

chatroom.message_recalled

聊天室的消息被撤回后发送，尽力而为；不受“不接收由租户服务端引起的事件”的影响。事件不带消息的内容。

字段	类型	说明
`room_id`	String	聊天室 ID
`message_id`	String	被撤回的消息的 ID
`recalled_by`	String	撤回的用户；服务端、平台和系统撤回时为 `null`
`role`	String	撤回人的身份：`sender` 发送者本人，`owner`，`admin`，`server`，`platform`
`recalled_at`	String	撤回时间
`sender`	String	原消息的发送者；系统消息，或消息已不在聊天室最近的消息中时为 `null`

json

{
  "origin": "server",
  "room_id": "100312409813549056",
  "message_id": "100312464125591552",
  "recalled_by": null,
  "role": "server",
  "recalled_at": "2026-10-04T19:26:26.811Z",
  "sender": "bob"
}

音视频

通话的事件可以用于统计通话时长、计费和对账。通话的说明见音视频通话。单聊通话和群通话都有 rtc.call_created、rtc.call_answered 和 rtc.call_ended；群通话中每个成员加入和离开另有 rtc.member_joined、rtc.member_left。每个通话恰好有一个 rtc.call_ended。

rtc.call_created

发起通话后发送。

字段	类型	说明
`call_id`	String	通话 ID
`type`	String	`single` 单聊通话，`group` 群通话
`group_id`	String	群通话的群 ID；单聊通话为 `null`
`media`	String	`audio` 语音，`video` 视频
`initiator_username`	String	发起人
`invitees`	Array<Object>	被邀请的人，每项为 `username` 和 `state`（此时为 `ringing`）
`ext`	Object	发起时带的扩展字段，没有时为 `null`
`created_at`	String	发起时间
`ring_expires_at`	String	单聊通话振铃的截止时间，到时没有接听则通话结束；群通话为 `null`

json

{
  "origin": "client",
  "call_id": "100315526282084352",
  "type": "group",
  "group_id": "100311903108071424",
  "media": "video",
  "initiator_username": "alice",
  "invitees": [
    { "username": "carol", "state": "ringing" },
    { "username": "dave", "state": "ringing" }
  ],
  "ext": null,
  "created_at": "2026-10-04T19:38:05.238Z",
  "ring_expires_at": null
}

rtc.call_answered

第一个被邀请的人接听、通话接通后发送一次。

字段	类型	说明
`call_id`、`type`、`group_id`、`media`		同 `rtc.call_created`
`answered_at`	String	接通时间
`answered_by_username`	String	接听的人

json

{
  "origin": "client",
  "call_id": "100315433877372928",
  "type": "single",
  "group_id": null,
  "media": "audio",
  "answered_at": "2026-10-04T19:37:52.114Z",
  "answered_by_username": "carol"
}

rtc.member_joined

群通话中有成员加入后发送（发起人除外）。

字段	类型	说明
`call_id`	String	通话 ID
`group_id`	String	群 ID
`username`	String	加入的成员
`role`	String	`invitee` 被邀请的人，`joiner` 没有被邀请、主动加入的群成员
`joined_at`	String	加入时间
`joined_count`	Number	加入后通话中的人数

json

{
  "origin": "client",
  "call_id": "100315526282084352",
  "group_id": "100311903108071424",
  "username": "carol",
  "role": "invitee",
  "joined_at": "2026-10-04T19:38:16.412Z",
  "joined_count": 2
}

rtc.member_left

群通话中有成员离开后发送。通话结束时仍在通话中的成员不发送，见 rtc.call_ended 的 members。

字段	类型	说明
`call_id`	String	通话 ID
`group_id`	String	群 ID
`username`	String	离开的成员
`left_at`	String	离开时间
`leave_reason`	String	离开的原因：`hangup` 挂断，`connection_lost` 连接中断，`removed` 被移出通话，`removed_from_group` 被移出群，`session_revoked` 登录会话失效，`user_unavailable` 用户不可用，`app_unavailable` 应用不可用
`joined_ms`	Number	这个成员在通话中的累计时长，毫秒
`joined_count`	Number	离开后通话中的人数

json

{
  "origin": "client",
  "call_id": "100315526282084352",
  "group_id": "100311903108071424",
  "username": "dave",
  "left_at": "2026-10-04T19:38:17.512Z",
  "leave_reason": "hangup",
  "joined_ms": 1048,
  "joined_count": 2
}

rtc.call_ended

通话结束后发送，每个通话恰好一次，带时长和每个成员的情况。

字段	类型	说明
`call_id`、`type`、`group_id`、`media`、`initiator_username`、`ext`、`created_at`		同 `rtc.call_created`
`answered_at`	String	接通时间；没有接通为 `null`
`ended_at`	String	结束时间
`end_reason`	String	结束的原因：`completed` 正常结束，`canceled` 发起人取消，`rejected` 被拒绝，`busy` 对方忙，`no_answer` 无人接听，`connection_lost` 连接中断，`server_ended` 你的服务端或控制台结束，`platform_ended` 平台结束，`user_unavailable`、`group_unavailable`、`app_unavailable` 用户、群、应用不可用，`service_disabled` 媒体服务不可用，`max_duration` 超过最长时长
`ended_by_username`	String	结束通话的用户，可为 `null`
`ended_via`	String	结束的入口：`client`、`openapi`、`console`、`platform`、`system`
`duration_ms`	Number	通话时长：从接通到结束，毫秒；没有接通为 0
`participant_ms`	Number	全部成员在通话中的时长之和，毫秒
`billable_minutes`	Number	计费的分钟数
`peak_joined`	Number	同时在通话中的最多人数
`joined_members`	Number	加入过通话的人数
`invited_members`	Number	被邀请的人数
`members`	Array<Object>	每个成员：`username`；`role`（`initiator`、`invitee`、`joiner`）；`state` 最终状态（`left` 已离开、`declined` 拒绝、`busy` 忙、`missed` 未接、`canceled` 已取消等）；`joined_platform` 加入时的平台；`first_joined_at` 第一次加入的时间；`left_at` 离开时间；`leave_reason` 离开原因（含 `ended` 通话结束）；`joined_ms` 在通话中的累计时长；`media_joined_at` 连上媒体服务的时间。没有加入过的成员，时间类字段为 `null`

json

{
  "origin": "client",
  "call_id": "100315526282084352",
  "type": "group",
  "group_id": "100311903108071424",
  "media": "video",
  "initiator_username": "alice",
  "ext": null,
  "created_at": "2026-10-04T19:38:05.238Z",
  "answered_at": "2026-10-04T19:38:16.412Z",
  "ended_at": "2026-10-04T19:38:18.556Z",
  "end_reason": "completed",
  "ended_by_username": "alice",
  "ended_via": "client",
  "duration_ms": 2144,
  "participant_ms": 5336,
  "billable_minutes": 3,
  "peak_joined": 3,
  "joined_members": 3,
  "invited_members": 2,
  "members": [
    {
      "username": "alice",
      "role": "initiator",
      "state": "left",
      "joined_platform": "ios",
      "first_joined_at": "2026-10-04T19:38:05.238Z",
      "left_at": "2026-10-04T19:38:18.556Z",
      "leave_reason": "ended",
      "joined_ms": 2144,
      "media_joined_at": null
    },
    {
      "username": "carol",
      "role": "invitee",
      "state": "left",
      "joined_platform": "macos",
      "first_joined_at": "2026-10-04T19:38:16.412Z",
      "left_at": "2026-10-04T19:38:18.556Z",
      "leave_reason": "ended",
      "joined_ms": 2144,
      "media_joined_at": null
    },
    {
      "username": "dave",
      "role": "invitee",
      "state": "left",
      "joined_platform": "web",
      "first_joined_at": "2026-10-04T19:38:16.464Z",
      "left_at": "2026-10-04T19:38:17.512Z",
      "leave_reason": "hangup",
      "joined_ms": 1048,
      "media_joined_at": null
    }
  ]
}

内容安全

内容安全的事件让你的服务端得知新的待审核内容、审核结论、用户举报和违规，例如据此通知审核人员、警告违规的用户。事件不带被审核的内容和命中的词，需要时按 item_id 用内容安全的接口读取。各字段的含义见内容安全。

涉及用户的对象（target_type 为 user、user_profile、group_member、group_request、friend_request）没有 target_id，改用 target_username 和 target_group_id 表示；其他对象（消息、群、聊天室、文件等）的 target_id 为对象的 ID。

moderation.item_created

你的审核队列中有新的审核记录时发送：内容命中了送审的词库、第三方审核建议人工审核、事后审核自动处置了内容，或者用户举报。同一个对象已有未处理的记录时，新的命中和举报归到原来的记录上，不再发送。origin 总是 system。

字段	类型	说明
`item_id`	String	审核记录 ID
`scene`	String	场景，如 `message`、`chatroom_message`、`user_profile`、`group_profile`、`media_upload`；举报产生的记录为 `report`
`target_type`	String	对象的类型：`message`、`chatroom_message`、`user_profile`、`group_profile`、`group_member`、`group_request`、`friend_request`、`chatroom_profile`、`chatroom_attribute`、`file`、`user`、`group`、`chatroom`
`target_id`	String	对象的 ID，涉及用户的对象没有这个字段
`target_username`	String	涉及的用户，可为 `null`
`target_group_id`	String	涉及的群，可为 `null`
`conversation_id`	String	消息所在的会话，其他为 `null`
`author_username`	String	内容的作者，可为 `null`
`source_types`	Array<String>	进入审核的原因：`word_list` 词库，`provider` 第三方审核，`url_rejected` 外部地址无法审核，`report` 用户举报，`escalation` 转交
`categories`	Array<String>	命中的类别
`suggestion`	String	第三方审核的建议：`review`、`block`；没有时为 `null`
`status`	String	记录的状态：`pending` 待处理，`auto_violation` 已自动处置、等待确认
`auto_actions`	Array<String>	已经自动执行的处置，如 `recall_message`、`block_file`
`report_count`	Number	举报的次数
`created_at`	String	创建时间

用户的消息命中了送审的词库：

json

{
  "origin": "system",
  "item_id": "100318924263915520",
  "scene": "message",
  "target_type": "message",
  "target_id": "100318922028351488",
  "target_username": null,
  "target_group_id": null,
  "conversation_id": "100318921969631232",
  "author_username": "bob",
  "source_types": ["word_list"],
  "categories": ["ad"],
  "suggestion": "review",
  "status": "pending",
  "auto_actions": [],
  "report_count": 0,
  "created_at": "2026-10-04T19:51:35.391Z"
}

用户被举报：

json

{
  "origin": "system",
  "item_id": "100318971017822208",
  "scene": "report",
  "target_type": "user",
  "target_username": "bob",
  "target_group_id": null,
  "conversation_id": null,
  "author_username": "bob",
  "source_types": ["report"],
  "categories": ["ad"],
  "suggestion": null,
  "status": "pending",
  "auto_actions": [],
  "report_count": 1,
  "created_at": "2026-10-04T19:51:46.529Z"
}

moderation.item_decided

审核记录有了结论或被改判后发送。平台审核的记录只在平台确认违规时发送。origin：你的审核人员（控制台）或你的服务端作出的为 server，平台审核人员作出的为 platform。

字段	类型	说明
`item_id`	String	审核记录 ID
`queue`	String	`tenant` 你的审核队列，`platform` 平台的审核队列
`target_type`、`target_id`、`target_username`、`target_group_id`、`author_username`		同 `moderation.item_created`
`previous_status`	String	作出结论之前的状态
`decision`	String	结论：`violation` 违规，`no_violation` 无违规
`actions`	Array<String>	执行的处置：`recall_message`、`recall_chatroom_message`、`remove_chatroom_attribute`、`block_file`、`unblock_file`、`clear_profile`、`mute_user`、`disable_user`、`disable_group`、`disable_chatroom`
`decided_by_type`	String	作出结论的一方：`account` 控制台的成员，`app` 你的服务端，`platform_admin` 平台
`decided_at`	String	作出结论的时间

json

{
  "origin": "server",
  "item_id": "100318924263915520",
  "queue": "tenant",
  "target_type": "message",
  "target_id": "100318922028351488",
  "target_username": null,
  "target_group_id": null,
  "author_username": "bob",
  "previous_status": "pending",
  "decision": "violation",
  "actions": ["recall_message"],
  "decided_by_type": "app",
  "decided_at": "2026-10-04T19:51:46.604Z"
}

处置本身另有对应的事件，如撤回消息有 message.recalled，禁言有 user.mute_changed。

moderation.report_created

用户在客户端举报，或你的服务端代用户举报后发送。origin：客户端举报为 client，服务端代用户举报为 server。

字段	类型	说明
`report_id`	String	举报 ID
`item_id`	String	举报归入的审核记录 ID
`reporter_username`	String	举报人
`target_type`	String	举报的对象：`message`、`user`、`group`、`chatroom`、`chatroom_message`
`target_id`	String	对象的 ID；举报用户时没有这个字段
`target_username`	String	举报用户时为被举报的用户，可为 `null`
`target_group_id`	String	涉及的群，可为 `null`
`reason`	String	举报原因，如 `ad`、`fraud`、`abuse`
`via`	String	`client` 客户端，`openapi` 服务端
`created_at`	String	举报时间

json

{
  "origin": "server",
  "report_id": "100318971017822209",
  "item_id": "100318971017822208",
  "reporter_username": "carol",
  "target_type": "user",
  "target_username": "bob",
  "target_group_id": null,
  "reason": "ad",
  "via": "openapi",
  "created_at": "2026-10-04T19:51:46.530Z"
}

moderation.violation_recorded

记下用户的一次违规后发送，带这次触发的自动处罚，可以据此通知或警告用户。origin：发送前、保存前被拒绝和事后审核自动处置的为 system，你的审核人员确认的为 server，平台确认的为 platform。

字段	类型	说明
`username`	String	违规的用户
`scene`	String	场景
`category`	String	违规的类别
`source`	String	怎样发现的：`sync` 发送前、保存前被拒绝，`async` 事后审核自动处置，`review` 审核人员确认
`authority`	String	按谁的规则：`tenant` 你的规则，`platform` 平台的规则
`item_id`	String	对应的审核记录；发送前被拒绝的没有审核记录，为 `null`
`penalties`	Array<Object>	这次触发的自动处罚，没有时为空数组。每项为 `kind`（`mute_user` 全局禁言，`disable_user` 封禁）、`scopes`（禁言的场景，封禁为空数组）、`duration_seconds`（时长，永久为 `null`）
`created_at`	String	记下违规的时间

用户发送的消息被词库拒绝，触发了“违规 1 次禁言单聊 10 分钟”的规则：

json

{
  "origin": "system",
  "username": "bob",
  "scene": "message",
  "category": "fraud",
  "source": "sync",
  "authority": "tenant",
  "item_id": null,
  "penalties": [
    { "kind": "mute_user", "scopes": ["chat"], "duration_seconds": 600 }
  ],
  "created_at": "2026-10-04T19:51:34.896Z"
}

自动处罚另有对应的 user.mute_changed 或 user.status_changed 事件，origin 为 system。

文件

文件事件的接口和字段含义见文件概述。url、thumbnail_url 是文件地址，只有本应用的用户和你的服务端能换取下载地址。

media.file_uploaded

文件完成上传后发送，包括客户端、服务端和控制台上传的文件。origin 按上传的入口：客户端为 client，服务端和控制台为 server。

字段	类型	说明
`file_id`	String	文件 ID
`purpose`	String	用途：`attachment`、`user_avatar`、`group_avatar`、`group_file`
`kind`	String	类型：`image`、`voice`、`video`、`file`
`content_type`	String	识别出的格式，如 `image/png`
`size`	Number	大小，字节
`width`、`height`	Number	图片的宽高；其他类型为 `null`
`sha256`	String	图片和头像的 SHA-256；其他类型为 `null`
`name`	String	文件名，可为 `null`
`url`	String	文件地址（头像为公开地址）
`thumbnail_url`	String	缩略图地址，没有时为 `null`
`owner_username`	String	所属用户，可为 `null`
`group_id`	String	群文件所属的群；其他为 `null`
`via`	String	上传的入口：`client`、`openapi`、`console`
`created_at`	String	创建上传的时间
`completed_at`	String	完成上传的时间

json

{
  "origin": "server",
  "file_id": "100312819781599232",
  "purpose": "attachment",
  "kind": "image",
  "content_type": "image/png",
  "size": 154,
  "width": 64,
  "height": 48,
  "sha256": "6c8107d3712cc2d23a40f2ee38b2030027b46b01a1060510e87ad991f606813b",
  "name": "pic.png",
  "url": "https://im.example.com/media/v1/f/100312819781599232/xHa5BkJq8pYxZQwoRIgq2Q",
  "thumbnail_url": "https://im.example.com/media/v1/f/100312819781599232/xHa5BkJq8pYxZQwoRIgq2Q/thumb",
  "owner_username": "alice",
  "group_id": null,
  "via": "openapi",
  "created_at": "2026-10-04T19:27:19.958Z",
  "completed_at": "2026-10-04T19:27:20.532Z"
}

media.file_blocked

文件因违规被屏蔽后发送，见违规文件的屏蔽。

字段	类型	说明
`file_id`、`purpose`、`kind`、`owner_username`、`group_id`		同 `media.file_uploaded`
`blocked_by`	String	屏蔽方：`system` 内容安全的处置（自动处置，或审核人员确认违规后屏蔽），`platform` 平台管理员
`rule_source`	String	依据的规则：`tenant` 你的应用的规则，`platform` 平台的规则
`reason`	String	屏蔽的原因
`blocked_at`	String	屏蔽时间

json

{
  "origin": "platform",
  "file_id": "100312819781599232",
  "purpose": "attachment",
  "kind": "image",
  "owner_username": "alice",
  "group_id": null,
  "blocked_by": "platform",
  "rule_source": "platform",
  "reason": "违规图片",
  "blocked_at": "2026-10-04T19:27:57.911Z"
}

media.file_unblocked

文件被解除屏蔽后发送。

字段	类型	说明
`file_id`、`purpose`、`kind`、`owner_username`、`group_id`		同 `media.file_uploaded`
`unblocked_by`	String	解除方：`system`（如审核记录被改判为无违规）或 `platform`
`status`	String	解除后的状态：`active` 恢复可用，`deleted` 文件已失去归属，没有恢复
`unblocked_at`	String	解除时间

json

{
  "origin": "platform",
  "file_id": "100312819781599232",
  "purpose": "attachment",
  "kind": "image",
  "owner_username": "alice",
  "group_id": null,
  "unblocked_by": "platform",
  "status": "active",
  "unblocked_at": "2026-10-04T19:27:57.950Z"
}

独立 RTC 频道

订阅 rtc_channel.* 或以下完整事件名。rtc.* 只覆盖原通话，不包含频道。rtc_channel.config_changed 是内部配置通知，不提供租户回调。

频道回调沿用既有签名、过滤、重试与事件 envelope。以 event_id 去重；不保证到达顺序，频道资料用 version、成员用 session_version / members_version，各版本不能混用。需要完整状态时，通过频道管理或会话管理重新查询授权范围内的数据。回调不提供票据、媒体 Token、设备信息或管理处置说明。各类事件的公共字段见下表。

公共频道 data 字段

字段	类型	含义
channel_id、channel_uid	String	业务 ID 和唯一资源 ID
generation、version、members_version	Integer	媒体代次、频道资料版本、成员版本
occurred_at	String	变化发生时间
origin	String	沿用公共来源值
session_id、username、role、reason、session_version	可选	会话事件提供的会话身份、角色、原因代码与版本；非会话事件不能假设这些字段存在

以下为事件目录中 created 的 data 示例，不是整个回调 envelope：

json

{"channel_id":"demo","channel_uid":"10001","generation":1,"version":1,"members_version":1,"occurred_at":"2026-10-09T01:00:00.000Z","origin":"system"}

rtc_channel.created

频道创建成功；不会自动创建 IM 群或发起呼叫。

rtc_channel.updated

名称、ext 或期限实际改变时产生；同值修改不会增加资料版本。

rtc_channel.closing

已经拒绝新加入，媒体清理仍在进行；不能视为所有成员已离线。

rtc_channel.closed

关闭清理完成；频道 ID 不可复用。

rtc_channel.session_joined

媒体连接已被服务端确认为入会；不表示用户已开启麦克风或摄像头。

rtc_channel.session_leaving

开始移出、主动退出或超时收尾，授权已停止，但席位可能仍在清理。

rtc_channel.session_left

该会话媒体清理完成；与 channel.closed 是不同终态。

rtc_channel.member_banned

发生频道封禁变化。当前回调不保证提供目标 username；有需核对的成员时查询封禁列表和会话接口，勿根据缺失字段猜测目标。

rtc_channel.member_unbanned

解除频道封禁；不恢复旧票据或已结束会话。当前回调不保证提供目标 username，需重新读取相关封禁状态。

事件回调 ​

订阅事件 ​

过滤条件 ​

事件一览 ​

用户 ​

user.created ​

user.status_changed ​

user.profile_changed ​

user.mute_changed ​

登录 ​

user.session_created ​

user.sessions_revoked ​

user.relogin_required ​

在线状态 ​

presence.changed ​

好友 ​

friend.added ​

friend.removed ​

friend.updated ​

friend_request.received ​

friend_request.declined ​

blacklist.changed ​

群组 ​

group.created ​

group.info_changed ​

group.dismissed ​

group.members_added ​

group.members_removed ​

group.members_updated ​

group.request_created ​

group.request_handled ​

消息 ​

message.sent ​

用好消息抄送 ​

内容的保留 ​

message.recalled ​

message.edited ​

聊天室 ​

chatroom.created ​

chatroom.info_changed ​

chatroom.dismissed ​

聊天室成员的变化 ​

chatroom.attributes_changed ​

chatroom.message_sent ​

chatroom.message_recalled ​

音视频 ​

rtc.call_created ​

rtc.call_answered ​

rtc.member_joined ​

rtc.member_left ​

rtc.call_ended ​

内容安全 ​

moderation.item_created ​

moderation.item_decided ​

moderation.report_created ​

moderation.violation_recorded ​

文件 ​

media.file_uploaded ​

media.file_blocked ​

media.file_unblocked ​

独立 RTC 频道 ​

公共频道 data 字段 ​

rtc_channel.created ​

rtc_channel.updated ​

rtc_channel.closing ​

rtc_channel.closed ​

rtc_channel.session_joined ​

rtc_channel.session_leaving ​

rtc_channel.session_left ​

rtc_channel.member_banned ​

rtc_channel.member_unbanned ​

事件回调

订阅事件

过滤条件

事件一览

用户

user.created

user.status_changed

user.profile_changed

user.mute_changed

登录

user.session_created

user.sessions_revoked

user.relogin_required

在线状态

presence.changed

好友

friend.added

friend.removed

friend.updated

friend_request.received

friend_request.declined

blacklist.changed

群组

group.created

group.info_changed

group.dismissed

group.members_added

group.members_removed

group.members_updated

group.request_created

group.request_handled

消息

message.sent

用好消息抄送

内容的保留

message.recalled

message.edited

聊天室

chatroom.created

chatroom.info_changed

chatroom.dismissed

聊天室成员的变化

chatroom.attributes_changed

chatroom.message_sent

chatroom.message_recalled

音视频

rtc.call_created

rtc.call_answered

rtc.member_joined

rtc.member_left

rtc.call_ended

内容安全

moderation.item_created

moderation.item_decided

moderation.report_created

moderation.violation_recorded

文件

media.file_uploaded

media.file_blocked

media.file_unblocked

独立 RTC 频道

公共频道 data 字段

rtc_channel.created

rtc_channel.updated

rtc_channel.closing

rtc_channel.closed

rtc_channel.session_joined

rtc_channel.session_leaving

rtc_channel.session_left

rtc_channel.member_banned

rtc_channel.member_unbanned