发送消息

发送文字、图片、语音、视频、文件或用户名片。图片等媒体先上传，再将返回的 media 原样带入。

POST /app/sdk/messages/send

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

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

请求参数

JSON Body

参数	类型	必填	说明
`conversation_id`	string	是	服务器返回的会话 ID，1–512 字符。
`client_message_id`	string	是	客户端为本次发送生成的唯一 ID，1–128 字符，不含控制字符。网络重试时保持不变。
`type`	string	是	text 文字、image 图片、voice 语音、video 视频、file 文件、contact 名片。
`text`	string	条件	type=text 必填。非空文字，UTF-8 内容最多 20000 字节。
`mentions`	object \| null	否	仅文字消息可使用。群内 @ 指定成员或所有人；无提醒时省略或 null。
`mentions.type`	string	条件	有 mentions 时必填。users 指定成员；all 所有人。
`mentions.user_ids`	string[]	条件	mentions.type=users 必填。1–50 个不重复的外部 user_id，每项 1–64 字符。不能 @ 自己；目标必须是有效群成员。
`media`	object	条件	媒体类型必填。上传接口返回的完整 media。只允许当前服务器认可的资源，不能自行填写任意外链。
`media.url`	string	条件	媒体类型必填。原资源地址。发送媒体消息时原样使用上传接口给出的地址。1–2048 字符。
`media.thumbnail_url`	string \| null	条件	媒体类型必填。必须保留此字段。图片需要缩略图 URL；语音和文件为 null；视频为封面 URL 或 null。非空时 1–2048 字符。
`media.mime_type`	string	条件	媒体类型必填。资源的 MIME 类型，例如 image/webp。1–255 字符。
`media.file_name`	string \| null	条件	文件消息必填。服务器规范化的文件名，非空时 1–255 字符。其他媒体类型可为 null，直接复用上传结果。
`media.size`	integer	条件	媒体类型必填。资源大小，单位为字节。非负整数。
`media.width`	integer \| null	条件	图片必填。图片必须有像素尺寸，静态展示图最长边 1920，GIF 保留源图时最多 8000；视频两项同时为有效尺寸或同时为 null，语音和文件为 null。直接复用上传结果。
`media.height`	integer \| null	条件	图片必填。图片必须有像素尺寸，静态展示图最长边 1920，GIF 保留源图时最多 8000；视频两项同时为有效尺寸或同时为 null，语音和文件为 null。直接复用上传结果。
`media.duration_ms`	integer \| null	条件	语音必填。语音时长，至少 1000 毫秒，不能超过当前 voice.max_duration_ms。图片和文件为 null；视频可为正整数或 null，当前上传返回 null。
`contact_user_id`	string	条件	type=contact 必填。名片目标的外部 user_id，1–64 字符。昵称和头像由服务器生成。
`quote_mid`	string	否	引用的同会话消息 ID，正十进制字符串，最多 19 位。

标有条件的必填项，只在相应操作或配置下需要提交。

请求示例

bash

curl 'https://example.com/app/sdk/messages/send' \
  -H "Authorization: Bearer $POPOIM_TOKEN" \
  -H 'Content-Type: application/json' \
  --data '{"conversation_id":"friend_bGluemhvdQ","client_message_id":"outing-20261018-01","type":"text","text":"秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅"}'

群内 @ 成员

json

{
  "conversation_id": "group_6284173029",
  "client_message_id": "outing-20261018-02",
  "type": "text",
  "text": "林舟，请帮忙确认大巴座位。",
  "mentions": {
    "type": "users",
    "user_ids": [
      "linzhou"
    ]
  }
}

发送图片

json

{
  "conversation_id": "group_6284173029",
  "client_message_id": "outing-20261018-03",
  "type": "image",
  "media": {
    "url": "https://example.com/uploads/resources/2026/10/ab590ea121b24453bf932153ad276ef5.webp",
    "thumbnail_url": "https://example.com/uploads/resources/2026/10/c132a69a9c87430abf9df99e59988e12.webp",
    "mime_type": "image/webp",
    "file_name": "coast-sunset.jpg",
    "size": 186240,
    "width": 1080,
    "height": 1920,
    "duration_ms": null
  }
}

发送用户名片

json

{
  "conversation_id": "group_6284173029",
  "client_message_id": "outing-20261018-04",
  "type": "contact",
  "contact_user_id": "linzhou"
}

使用说明

只提交当前类型需要的内容：文字用 text，媒体用 media，名片用 contact_user_id。例如图片消息不附带 text。
@ 所有人使用 {"type":"all"}，只有群主和管理员可以发送；此时不传 user_ids。
同一次发送重试请保留 client_message_id 和原内容，收到返回后以服务器给出的 mid、conversation_seq 和 message 为准。

返回参数

成功响应的最外层字段如下。下面所有业务字段都位于 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": 1792301401000,
      "last_message_time": 1792301401000,
      "last_message": {
        "mid": "8601",
        "conversation_seq": "18",
        "sender_id": "chenyue",
        "sender_name": null,
        "type": "text",
        "status": "normal",
        "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
        "file_name": null,
        "created_at": 1792301401000,
        "updated_at": 1792301401000
      },
      "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": "normal",
      "text": "秋日海岸出游的集合时间已确认，周六 8:30 公司楼下见 🌅",
      "mentions": null,
      "media": null,
      "contact": null,
      "system": null,
      "quote": null,
      "recalled_by": null,
      "recalled_at": null,
      "deleted_at": null,
      "created_at": 1792301401000,
      "updated_at": 1792301401000
    }
  }
}

返回对象字段

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

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

会话（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）

错误处理