事件回撥

應用內的使用者、好友、群組、訊息、聊天室、通話、內容安全和檔案發生變化後，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`	檔案被解除遮蔽
AI 對話	`ai.message_received`	使用者給啟用中的機器人發了單聊訊息
	`ai.stream_finished`	一條 AI 回覆結束（不論結果）
	`ai.stream_stopped`	使用者點了停止生成

好友申請被標記為已讀、聊天室成員的進入和離開、訊息的已讀回執和表情回應不提供回撥。

使用者

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），除非地址開啟了“接收群提示”；
只推線上的訊息：不儲存，也不抄送；
被內容安全或發訊息前回撥拒絕的訊息：沒有寫入，也不抄送。

機器人開始的 AI 回覆也會抄送一次，此時 type 為 ai、正文的 status 為 streaming；回覆結束時不再傳送 message.edited，最終結果見 ai.stream_finished。

欄位	型別	說明
`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"
}

AI 對話

AI 對話的事件。投遞規則與其他事件不同：機器人配置了回撥地址（endpoint_id）的，這個機器人的三種事件只投遞給這個地址，即使它沒有訂閱；沒有配置的，投遞給訂閱了這個事件的地址。

ai.message_received

使用者給啟用中的機器人發了一條單聊訊息。收到後開始回覆，reply_to_seq 填 message.seq。機器人發出的訊息、群聊訊息不觸發。從使用者發出訊息到你收到這個事件通常在 1 秒以內。

欄位	型別	說明
`bot`	String	機器人的使用者名稱
`from`	String	發訊息的使用者名稱
`conversation_id`	String	單聊會話 ID
`message`	Object	這條訊息，結構同 `message.sent` 的訊息
`context`	Array	這條訊息之前最近的訊息（包括機器人以前的回覆），按時間正序，條數為機器人的 `context_messages`（預設 10）；總大小不超過 48 KB，超出時從最早的開始去掉

json

{
  "origin": "client",
  "bot": "assistant",
  "from": "zhangsan",
  "conversation_id": "1840098765432101",
  "message": {
    "conversation_id": "1840098765432101",
    "conversation_type": "single",
    "seq": 356,
    "message_id": "1840120033445566777",
    "sender": "zhangsan",
    "recipient": "assistant",
    "type": "text",
    "body": { "text": "明天上海天气？" },
    "created_at": "2026-09-28T08:00:00.000Z"
  },
  "context": [
    {
      "conversation_id": "1840098765432101",
      "seq": 355,
      "sender": "zhangsan",
      "type": "text",
      "body": { "text": "你好" },
      "created_at": "2026-09-28T07:59:40.000Z"
    }
  ]
}

示例中的訊息省略了部分欄位。

ai.stream_finished

一條 AI 回覆結束，不論結果：正常結束、使用者停止、超時、生成中斷等。

欄位	型別	說明
`stream_id`	String	流 ID
`client_stream_id`	String	開始時給出的冪等標識，沒有時為 `null`
`bot`、`to`	String	機器人和接收回復的使用者
`conversation_id`	String	會話 ID
`message_seq`	Number	AI 訊息在會話中的序號
`status`	String	`completed`、`stopped` 或 `failed`
`finish_reason`	String	結束原因
`error`	Object	`failed` 時為 `{ "code": "…", "message": "…" }`，否則為 `null`
`last_seq`	Number	最後一段增量的序號
`started_at`、`finished_at`	String	開始和結束時間

json

{
  "origin": "server",
  "stream_id": "1841000000000000123",
  "client_stream_id": "req-7f3a",
  "bot": "assistant",
  "to": "zhangsan",
  "conversation_id": "1840098765432101",
  "message_seq": 358,
  "status": "completed",
  "finish_reason": "stop",
  "error": null,
  "last_seq": 57,
  "started_at": "2026-09-28T08:00:01.000Z",
  "finished_at": "2026-09-28T08:00:09.000Z"
}

ai.stream_stopped

使用者在客戶端點了停止生成。回覆已經以 stopped 結束，收到後儘快中止模型呼叫；之後還會收到 status 為 stopped 的 ai.stream_finished。服務端 SDK 的回撥處理器收到這個事件時自動停止本程序中對應的流。

欄位	型別	說明
`stream_id`	String	流 ID
`client_stream_id`	String	開始時給出的冪等標識，沒有時為 `null`
`bot`、`to`	String	機器人和接收回復的使用者
`conversation_id`	String	會話 ID
`stopped_by`	String	點了停止的使用者名稱
`stopped_at`	String	停止時間

json

{
  "origin": "client",
  "stream_id": "1841000000000000123",
  "client_stream_id": null,
  "bot": "assistant",
  "to": "zhangsan",
  "conversation_id": "1840098765432101",
  "stopped_by": "zhangsan",
  "stopped_at": "2026-09-28T08:00:05.000Z"
}

獨立 RTC 頻道

訂閱 rtc_channel.* 或以下完整事件名。rtc.* 只覆蓋原通話，不包含頻道。rtc_channel.config_changed 是內部配置通知，不提供租戶回撥。

頻道回撥的簽名、過濾、重試和請求體格式與其他事件相同。按事件 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`	可選	會話事件提供的會話身份、角色、原因程式碼與版本；非會話事件不能假設這些欄位存在

以下是 rtc_channel.created 的 data 示例，不是整個回撥請求體：

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

該會話媒體清理完成；與 rtc_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 ​

AI 對話 ​

ai.message_received ​

ai.stream_finished ​

ai.stream_stopped ​

獨立 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

AI 對話

ai.message_received

ai.stream_finished

ai.stream_stopped

獨立 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