撤回消息

撤回本人发送的消息。其他成员也会看到这条消息已撤回。

POST /app/sdk/messages/recall

调用方： SDK 客户端　·　认证： IM Token

请求头：Authorization: Bearer <IM Token>。先通过宿主后端获取 Token，再交给 SDK 使用。

请求参数

JSON Body

参数	类型	必填	说明
`conversation_id`	string	是	服务器返回的会话 ID，1–512 字符。
`mid`	string	是	正十进制消息 ID，最多 19 位。

请求示例

bash

curl 'https://example.com/app/sdk/messages/recall' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"conversation_id":"friend_bGluemhvdQ","mid":"8601"}'

使用说明

只能撤回本人有权撤回的消息。当前接口没有撤回时间窗口参数。
消息 ID 和序号保留。正文、媒体、名片和引用内容清空为 null，以返回的 message.status 更新界面。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 data 中。

字段	类型	说明
`code`	integer	0 表示成功；非 0 时查看 msg，不把 data 当成功结果使用。
`msg`	string	成功通常为 ok，失败时为错误说明。
`data`	object	本次请求的业务结果，字段见下表。

data 字段

字段	类型	说明
`event_id`	string \| null	与实时通知对应的事件 ID。没有产生新事件时可为 null；同一事件只处理一次。
`conversation`	Conversation	操作后的会话。
`message`	Message	操作后的完整消息。

返回示例

示例展示字段结构；ID、时间和资料仅作说明，请使用实际回包。

展开完整返回示例

json

{
  "code": 0,
  "msg": "ok",
  "data": {
    "event_id": "evt_6874dbb8db144f18b8532dc4c938156c",
    "conversation": {
      "conversation_id": "friend_bGluemhvdQ",
      "type": "friend",
      "target_id": "linzhou",
      "name": "林舟",
      "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
      "member_count": null,
      "group_role": null,
      "all_muted": false,
      "send_forbidden_until": 0,
      "last_mid": "8601",
      "last_seq": "18",
      "read_seq": "18",
      "peer_read_seq": "17",
      "announcement_updated_at": 0,
      "announcement_unread": false,
      "mention_unread": false,
      "updated_at": 1792301402000,
      "last_message_time": 1792301401000,
      "last_message": {
        "mid": "8601",
        "conversation_seq": "18",
        "sender_id": "chenyue",
        "sender_name": null,
        "type": "text",
        "status": "recalled",
        "text": null,
        "file_name": null,
        "created_at": 1792301401000,
        "updated_at": 1792301402000
      },
      "unread_count": 0,
      "pinned": false,
      "muted": false,
      "state": "chatting",
      "peer": {
        "id": "1025",
        "user_id": "linzhou",
        "username": "linzhou",
        "nickname": "林舟",
        "avatar": "https://example.com/uploads/avatars/linzhou.jpg",
        "signature": "把每一次出发安排妥当",
        "profile_updated_at": 1792301400000
      },
      "peer_presence": {
        "online": true,
        "online_updated_at": 1792301400000
      }
    },
    "message": {
      "mid": "8601",
      "client_message_id": "outing-20261018-01",
      "conversation_id": "friend_bGluemhvdQ",
      "conversation_seq": "18",
      "sender_id": "chenyue",
      "sender": {
        "id": "1024",
        "user_id": "chenyue",
        "username": "chenyue",
        "nickname": "陈悦",
        "avatar": "https://example.com/uploads/avatars/chenyue.jpg",
        "signature": "一起发现沿途的风景",
        "profile_updated_at": 1792301400000
      },
      "type": "text",
      "status": "recalled",
      "text": null,
      "mentions": null,
      "media": null,
      "contact": null,
      "system": null,
      "quote": null,
      "recalled_by": "chenyue",
      "recalled_at": 1792301402000,
      "deleted_at": null,
      "created_at": 1792301401000,
      "updated_at": 1792301402000
    }
  }
}

返回对象字段

数组中的每个对象使用同一套字段。点击名称跳到说明：

会话 · 最后一条消息摘要 · 用户资料 · 在线状态 · 群资料 · 完整消息 · @ 提醒 · 媒体资源 · 用户名片 · 系统消息内容 · 引用消息摘要

会话（Conversation）

字段	类型	说明
`conversation_id`	string	会话 ID。读取消息、发送消息和修改会话状态时直接使用此值。
`type`	string	friend 表示单聊，group 表示群聊。
`target_id`	string	单聊为对方的外部 user_id；群聊为公开 group_id。
`name`	string	当前账号看到的会话名称，可能已应用个人备注。
`avatar`	string	会话头像地址。
`member_count`	integer \| null	群成员数；单聊为 null。
`group_role`	string \| null	本人在群中的角色：owner 群主、admin 管理员、member 成员；单聊为 null。
`all_muted`	boolean	群是否开启全员禁言；单聊为 false。
`send_forbidden_until`	integer	本人禁言到期时间；0 表示没有单独禁言，Unix 毫秒时间戳。
`last_mid`	string	最新消息 ID；没有消息时为 "0"。
`last_seq`	string	最新消息序号；没有消息时为 "0"。
`read_seq`	string \| null	本人已读到的消息序号。未提供个人状态的共享事件可为 null。
`peer_read_seq`	string \| null	单聊对方已读到的序号；群聊为 null。
`announcement_updated_at`	integer	群公告更新时间；单聊为 0，Unix 毫秒时间戳。
`announcement_unread`	boolean	本人是否有未读群公告；单聊为 false。
`mention_unread`	boolean	是否存在尚未读到的群内 @ 提醒；单聊为 false。
`updated_at`	integer	会话最后更新时间，Unix 毫秒时间戳。
`last_message_time`	integer	最新消息时间；没有消息时为 0，Unix 毫秒时间戳。
`last_message`	LastMessage \| null	最后一条消息摘要；没有消息时为 null。
`unread_count`	integer	本人未读消息数，范围 0–100；100 表示至少 100 条。
`pinned`	boolean	本人是否置顶。
`muted`	boolean	本人是否开启免打扰。
`state`	string	chatting 表示显示在会话列表，hidden 表示隐藏。
`peer`	User	仅单聊返回，对方完整资料；群聊不返回此字段。
`peer_presence`	Presence \| null	单聊对方在线状态；群聊或暂时没有状态时为 null。
`group`	Group	仅群聊返回，完整群资料；单聊不返回此字段。

最后一条消息摘要（LastMessage）

字段	类型	说明
`mid`	string	消息 ID。
`conversation_seq`	string	这条消息在当前会话中的序号。
`sender_id`	string \| null	发送者的外部 user_id；系统消息为 null。
`sender_name`	string \| null	群消息发送者的显示名；单聊中可为 null。
`type`	string	text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。
`status`	string	normal 正常、recalled 已撤回、deleted 已被当前账号删除。
`text`	string \| null	文字或摘要文本；没有文本、已撤回或已删除时为 null。
`file_name`	string \| null	文件名称；非文件消息或内容已清除时为 null。
`created_at`	integer	发送时间，Unix 毫秒时间戳。
`updated_at`	integer	消息最后更新时间，Unix 毫秒时间戳。

用户资料（User）

字段	类型	说明
`id`	string	IM 内部用户 ID，以十进制字符串返回。调用用户相关接口时使用下面的 user_id。
`user_id`	string	宿主系统提供的用户 ID，例如 chenyue；用于识别同一个人。
`username`	string \| null	可用于精确搜索的账号；没有设置时为 null。
`nickname`	string	显示昵称。
`avatar`	string	头像地址。
`signature`	string	个性签名；未设置时为空字符串。
`profile_updated_at`	integer	公开资料最后更新时间，Unix 毫秒时间戳。

在线状态（Presence）

字段	类型	说明
`online`	boolean	当前是否在线。
`online_updated_at`	integer	在线状态最后更新时间，Unix 毫秒时间戳。

群资料（Group）

字段	类型	说明
`group_id`	string	公开群 ID，群相关请求使用这个值。
`owner_id`	string	群主的外部 user_id。
`name`	string	群名称。
`avatar`	string	群头像地址。
`avatar_custom`	boolean	是否由用户上传头像；false 表示服务器生成的组合头像。
`announcement`	string \| null	群公告正文；没有公告时为 null。
`announcement_author_id`	string \| null	最近一次公告发布者的外部 user_id；没有公告时可为 null。
`announcement_author_name`	string \| null	公告发布者的显示名；没有公告时可为 null。
`announcement_updated_at`	integer	公告更新时间；尚未设置时为 0，Unix 毫秒时间戳。
`status`	string	群状态：active 正常、disabled 停用、dissolved 已解散。
`all_muted`	boolean	是否开启全员禁言。
`join_approval_required`	boolean	扫码加入是否需要群主或管理员审批。
`member_count`	integer	当前成员人数。
`unread_mode`	string	未读计算方式：fanout 按成员累计；sequence 按消息序号计算。客户端使用返回的未读数即可。
`last_mid`	string	最新消息 ID；还没有消息时为 "0"。
`last_seq`	string	最新消息在群内的序号；没有消息时为 "0"。
`last_message_at`	integer	最近一条消息的发送时间；没有消息时为 0，Unix 毫秒时间戳。
`conversation_updated_at`	integer	群会话内容最后更新时间，Unix 毫秒时间戳。
`created_at`	integer	建群时间，Unix 毫秒时间戳。
`updated_at`	integer	群资料最后更新时间，Unix 毫秒时间戳。

完整消息（Message）

字段	类型	说明
`mid`	string	服务器分配的消息 ID。
`client_message_id`	string \| null	发送时提交的去重 ID；只有原发送者能看到，其他用户为 null。
`conversation_id`	string	消息所属会话 ID。
`conversation_seq`	string	消息在该会话中的递增序号。用于前后翻页，不能用 mid 代替。
`sender_id`	string \| null	发送者的外部 user_id；系统消息为 null。
`sender`	User \| null	发送者资料；系统消息为 null。
`type`	string	text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片、system 系统消息、unsupported 暂不支持的类型。
`status`	string	normal 正常、recalled 已撤回、deleted 已被当前账号删除。
`text`	string \| null	文字正文；其他类型或内容已清除时为 null。
`mentions`	Mentions \| null	群文字消息的 @ 提醒；无提醒或内容已清除时为 null。
`media`	Media \| null	图片、语音、视频、文件的资源信息；其他类型或内容已清除时为 null。
`contact`	ContactCard \| null	名片内容；其他类型或内容已清除时为 null。
`system`	SystemMessage \| null	系统提示内容；非系统消息或内容已清除时为 null。
`quote`	Quote \| null	引用消息的展示摘要；没有引用或内容已清除时为 null。
`recalled_by`	string \| null	撤回者的外部 user_id；未撤回或已删除时为 null。
`recalled_at`	integer \| null	撤回时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
`deleted_at`	integer \| null	当前账号删除此消息的时间，Unix 毫秒时间戳；尚未发生或不适用时为 null。
`created_at`	integer	发送时间，Unix 毫秒时间戳。
`updated_at`	integer	消息最后更新时间，Unix 毫秒时间戳。

@ 提醒（Mentions）

字段	类型	说明
`type`	string	all 表示所有人；users 表示指定成员。
`user_ids`	string[]	仅 type=users 时返回，目标成员的外部 user_id 列表；type=all 时不返回。

媒体资源（Media）

字段	类型	说明
`url`	string	原资源地址。发送媒体消息时原样使用上传接口给出的地址。
`thumbnail_url`	string \| null	图片缩略图或视频封面地址；没有缩略图时为 null。
`mime_type`	string	资源的 MIME 类型，例如 image/webp。
`file_name`	string \| null	原文件名称；不适用时为 null。
`size`	integer	资源大小，单位为字节。
`width`	integer \| null	图片或视频宽度，单位为像素；不适用或未提供时为 null。
`height`	integer \| null	图片或视频高度，单位为像素；不适用或未提供时为 null。
`duration_ms`	integer \| null	媒体时长，单位为毫秒；不适用或尚未解析时为 null。当前视频上传结果的此项为 null。

用户名片（ContactCard）

字段	类型	说明
`user_id`	string	名片所属用户的外部 user_id。
`nickname`	string	名片昵称。
`avatar`	string \| null	名片头像地址；没有头像时可为 null。

系统消息内容（SystemMessage）

字段	类型	说明
`code`	string	系统事件类型，例如群成员变化。
`text`	string	可直接展示的说明文本。
`params`	object	随事件类型变化的补充信息；没有统一固定字段。展示提示时优先使用 text。

引用消息摘要（Quote）

字段	类型	说明
`mid`	string	被引用消息 ID。
`sender_id`	string	原发送者的外部 user_id。
`sender_name`	string	原发送者显示名。
`type`	string	原消息类型：text、image、voice、video、file、contact。
`preview`	string \| null	最多 160 字的展示摘要。文字消息有文本；文件或名片可有摘要；图片、语音、视频为 null。

错误处理

先检查 HTTP 状态，再检查 code。业务失败可能仍为 HTTP 200；非 0 的 code 都不能当成功。完整错误码见请求约定。

返回消息接口列表 · HTTP 请求约定

用户预置与 Token

首页与会话

消息

上传与下载

用户、好友与申请

群与成员

搜索

音视频通话

随附宿主账号

设备与推送

举报与诊断

撤回消息

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

会话（Conversation）

最后一条消息摘要（LastMessage）

用户资料（User）

在线状态（Presence）

群资料（Group）

完整消息（Message）

@ 提醒（Mentions）

媒体资源（Media）

用户名片（ContactCard）

系统消息内容（SystemMessage）

引用消息摘要（Quote）

错误处理

撤回消息 ​

请求参数 ​

JSON Body ​

请求示例 ​

使用说明 ​

返回参数 ​

data 字段 ​

返回示例 ​

返回对象字段 ​

会话（Conversation） ​

最后一条消息摘要（LastMessage） ​

用户资料（User） ​

在线状态（Presence） ​

群资料（Group） ​

完整消息（Message） ​

@ 提醒（Mentions） ​

媒体资源（Media） ​

用户名片（ContactCard） ​

系统消息内容（SystemMessage） ​

引用消息摘要（Quote） ​

错误处理 ​

撤回消息

请求参数

JSON Body

请求示例

使用说明

返回参数

data 字段

返回示例

返回对象字段

会话（Conversation）

最后一条消息摘要（LastMessage）

用户资料（User）

在线状态（Presence）

群资料（Group）

完整消息（Message）

@ 提醒（Mentions）

媒体资源（Media）

用户名片（ContactCard）

系统消息内容（SystemMessage）

引用消息摘要（Quote）

错误处理