发送消息
发送消息
环信即时通讯 IM HarmonyOS SDK 通过 ChatManager 类和 ChatMessage 类实现文本、图片、音频、视频和文件等类型的消息的发送。
- 对于单聊,环信即时通讯 IM 默认支持陌生人之间发送消息,即无需添加好友即可聊天。若仅允许好友之间发送单聊消息,你需要 开启好友关系检查。
- 对于群组和聊天室,用户每次只能向所属的单个群组和聊天室发送消息。 关于消息发送控制,详见 单聊、群组聊天 和 聊天室 的 相关文档。
前提条件
开始前,请确保满足以下条件:
发送文本消息
- 发送方调用
ChatMessage#createTextSendMessage方法创建一条消息。
默认情况下,SDK 对单个用户发送消息的频率未做限制。如果你联系了环信商务设置了该限制,一旦在单聊、群聊或聊天室中单个用户的消息发送频率超过设定的上限,SDK 会上报错误,即错误码 509 MESSAGE_CURRENT_LIMITING。
// 创建一条文本消息,`content` 为消息文字内容。
// `conversationId` 为消息接收方,单聊时为对端用户 ID、群聊时为群组 ID,聊天室时为聊天室 ID。
let message = ChatMessage.createTextSendMessage(conversationId, content);
if (!message) {
return;
}
// 会话类型:单聊为 ChatType.Chat,群聊为 ChatType.GroupChat, ChatType.ChatRoom,默认为单聊。
message.setChatType(ChatType.Chat);
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
- 通过
ChatManager#sendMessage将该消息发出。发送消息时可以设置ChatCallback的实例,获取消息发送状态。
// 发送消息时可以设置 `ChatCallback` 的实例,获得消息发送的状态。可以在该回调中更新消息的显示状态。例如消息发送失败后的提示等等。
let callback: ChatCallback = {
onSuccess: (): void => {
// 发送消息成功
},
onError: (code: number, error: string): void => {
// 发送消息失败
},
onProgress: (progress: number): void => {
// 附件上传进度
}
}
message.setMessageStatusCallback(callback);
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送附件消息
除文本消息外,SDK 还支持发送附件类型消息,包括语音、图片、视频和文件消息。
附件消息的发送过程如下:
- 创建和发送附件类型消息。SDK 将附件上传到环信服务器。
- 接收附件消息。SDK 自动下载语音消息,默认自动下载图片和视频的缩略图。若下载图片附件(原图或发送方上传的大图)、视频和文件,需调用
downloadAttachment方法。
消息附件大小和存储限制,详见 消息附件限制说明。
发送语音消息
- 发送语音消息前,在应用层录制语音文件。
- 发送方调用
createVoiceSendMessage方法传入接收方的用户 ID(群聊或聊天室分别为群组 ID 或聊天室 ID)、语音文件的路径和语音时长创建语音消息,然后调用sendMessage方法发送消息。SDK 会将语音文件上传至环信服务器。
// `filePathOrUri` 为语音文件的本地路径或者文件的 URI,`duration` 为语音时长(单位为秒)。
let message = ChatMessage.createVoiceSendMessage(to, filePathOrUri, duration);
if (!message) {
return;
}
// 设置会话类型,即`ChatMessage` 类的 `ChatType` 属性,包含 `Chat`、`GroupChat` 和 `ChatRoom`,表示单聊、群聊或聊天室,默认为单聊。
message.setChatType(ChatType.GroupChat);
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送图片消息
图片消息通常涉及以下三类图片资源:
- 原图:发送方本地选择的原始图片文件,通常用于查看或保存原图。
- 大图:SDK 客户端基于原图进行等比压缩后上传的图片。压缩规则为:若图片短边大于 720 像素,则等比压缩至短边为 720 像素;若短边小于等于 720 像素,则保留原图尺寸,不做放大处理。此类图片通常用于聊天详情页展示。SDK 自 1.14.0 版本起支持大图功能。
- 缩略图:服务端基于原图进行等比压缩后的图片。压缩规则为:默认情况下,若图片短边大于 170 像素,则等比压缩至短边为 170 像素;若短边小于等于 170 像素,则保留原图尺寸,不做放大处理。缩略图的压缩方式和尺寸可在 控制台进行配置。此类图片通常用于会话列表、聊天列表等轻量展示场景。
发送图片消息的流程如下:
获取图片的本地路径或 URI。
调用
ChatMessage#createImageSendMessage创建图片消息。创建消息时,需要传入图片的本地路径或 URI 以及接收方的用户 ID。若为群聊或聊天室消息,则分别传入群组 ID 或聊天室 ID。
根据需要调用
ImageMessageBody#setSendOriginalImage设置发送的图片资源类型:true表示发送原图,false表示发送大图。该方法需要在发送消息前调用。调用
ChatManager#sendMessage发送消息。当开启
ChatOptions#setAutoTransferMessageAttachments(true)时,SDK 会自动上传图片附件;发送非原图图片时,SDK 会先生成大图再上传,服务器自动生成缩略图。
创建和发送图片消息的示例代码如下所示:
// `filePath` 为图片的本地路径或 URI。
let message = ChatMessage.createImageSendMessage(to, filePath);
if (!message) {
return;
}
// 设置是否发送原图:true 表示发送原图,false 表示发送压缩后的大图。
let imageBody = message.getBody() as ImageMessageBody;
imageBody.setSendOriginalImage(false);
// 会话类型,包含 `Chat`、`GroupChat` 和 `ChatRoom`,表示单聊、群聊或聊天室,默认为单聊。
message.setChatType(ChatType.GroupChat);
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
createImageSendMessage 和 setSendOriginalImage 中的关键参数如下表所示:
| 参数 | 类型 | 必填/可选 | 说明 |
|---|---|---|---|
to | string | 必填 | 目标会话 ID。单聊为对端用户 ID,群聊为群组 ID,聊天室为聊天室 ID。 |
filePath | string | 必填 | 图片的本地路径或 URI。 |
isGif | boolean | 可选 | 是否为 GIF 图片,默认为 false。GIF 图片不进行压缩,始终按原图发送。 |
sendOriginalImage | boolean | 必填 | 通过 ImageMessageBody#setSendOriginalImage 设置。true 表示发送原图,false 表示发送大图。 |
发送 GIF 图片消息
发送 GIF 图片消息的过程如下:
- 发送方调用
ChatMessage#createImageSendMessage方法构造 GIF 图片消息体。 - 发送方调用
ChatManager#sendMessage方法发送消息。
// `imageUri` 为图片本地资源标志符
let isGif = true; // 是否为 GIF 图片,默认为 false。
let message = ChatMessage.createImageSendMessage(this.to, this.imageUri, isGif);
if (!message) {
return;
}
// 设置会话类型,即`ChatMessage` 类的 `ChatType` 属性,包含 `Chat`、`GroupChat` 和 `ChatRoom`,表示单聊、群聊或聊天室,默认为单聊。
// message.setChatType(ChatType.GroupChat);
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送视频消息
发送视频消息前,需要准备视频文件、视频时长以及可选的视频首帧缩略图。其中,视频时长和缩略图主要用于消息展示。
发送视频消息的流程如下:
在应用层完成视频文件的选取或录制,并准备视频文件的本地路径或 URI、视频时长和缩略图路径。
调用
ChatMessage#createVideoSendMessage创建视频消息。创建消息时,需要传入视频文件的本地路径或 URI、视频时长以及接收方的用户 ID。若为群聊或聊天室消息,则分别传入群组 ID 或聊天室 ID。缩略图路径为可选参数;如果需要显示视频缩略图,建议在应用层获取视频首帧,并将对应路径作为
imageThumbPath参数传入。调用
ChatManager#sendMessage发送消息。当开启
ChatOptions#setAutoTransferMessageAttachments(true)时,SDK 会自动上传视频附件;如果传入了本地缩略图,SDK 会读取缩略图尺寸并写入消息体。你可以通过ChatMessage#setMessageStatusCallback监听附件上传进度和消息发送结果。
创建和发送视频消息的示例代码如下所示:
// 在应用层获取视频首帧,你需要自行实现 getThumbPath 方法。
let thumbPath = this.getThumbPath(filePath);
let message = ChatMessage.createVideoSendMessage(
to,
filePath,
duration,
thumbPath
);
if (!message) {
return;
}
// 会话类型,包含 `Chat`、`GroupChat` 和 `ChatRoom`,表示单聊、群聊或聊天室,默认为单聊。
message.setChatType(ChatType.GroupChat);
// 可选:监听视频上传进度和发送结果。
message.setMessageStatusCallback({
onSuccess: (): void => {
// 视频消息发送成功
},
onError: (code: number, error: string): void => {
// 视频消息发送失败
},
onProgress: (progress: number): void => {
// 视频附件上传进度
}
});
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
createVideoSendMessage 的关键参数如下表所示:
| 参数 | 类型 | 必填/可选 | 说明 |
|---|---|---|---|
to | string | 必填 | 目标会话 ID。单聊为对端用户 ID,群聊为群组 ID,聊天室为聊天室 ID。 |
filePath | string | 必填 | 视频文件的本地路径或 URI。 |
duration | number | 必填 | 视频时长,单位为秒。 |
imageThumbPath | string | 可选 | 视频首帧缩略图的本地路径。建议由应用层生成,用于消息展示。 |
发送文件消息
- 发送方调用
ChatMessage#createFileSendMessage方法传入接收方的用户 ID(群聊或聊天室分别为群组 ID 或聊天室 ID)和文件的本地路径创建文件消息。 - 发送方调用
sendMessage方法发送文件消息。SDK 将文件上传至环信服务器。
// `fileLocalPathOrUri` 为本地文件路径或者本地文件Uri。
let message = ChatMessage.createFileSendMessage(toChatUsername, fileLocalPathOrUri);
if (!message) {
return;
}
// 如果是群聊,设置 `ChatType` 为 `GroupChat`,该参数默认是单聊(`Chat`)。
message.setChatType(ChatType.GroupChat);
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送位置消息
- 发送方调用
ChatMessage#createLocationSendMessage方法创建位置消息。 - 发送方调用
ChatManager#sendMessage方法发送位置消息
发送位置时,需要集成第三方的地图服务,获取到位置点的经纬度信息。
// `latitude` 为纬度,`longitude` 为经度,`locationAddress` 为具体位置内容。
let message = ChatMessage.createLocationSendMessage(toChatUsername, latitude, longitude, locationAddress);
if (!message) {
return;
}
// 如果是群聊,设置 `ChatType` 为 `GroupChat`,该参数默认是单聊(`Chat`)。
message.setChatType(ChatType.GroupChat);
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送透传消息
透传消息可视为命令消息,通过发送这条命令给对方,通知对方要进行的操作,收到消息可以自定义处理。
具体功能可以根据自身业务需求自定义,例如实现头像、昵称的更新等。另外,以 em_ 和 easemob:: 开头的 action 为内部保留字段,注意不要使用。
提示
- 透传消息发送后,不支持撤回。
- 透传消息不会存入本地数据库中,所以在 UI 上不会显示。
发送透传消息的过程如下:
- 发送方调用
ChatMessage#createSendMessage方法创建透传消息。 - 发送方调用
ChatManager#sendMessage方法发送透传消息。
let action = "action1";
// `action` 可以自定义。
let cmdBody = new CmdMessageBody(action);
let toUsername = "test1";
// 支持单聊、群聊和聊天室,默认为单聊。
let cmdMsg = ChatMessage.createSendMessage(toUsername, cmdBody, ChatType.GroupChat);
if (!cmdMsg) {
return;
}
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(cmdMsg);
发送自定义类型消息
除了几种消息之外,你可以自己定义消息类型,方便业务处理,即首先设置一个消息类型名称,然后可添加多种自定义消息。
- 发送方调用
ChatMessage#createSendMessage方法创建自定义消息。 - 发送方调用
ChatManager#sendMessage方法发送自定义消息。
// `event` 为需要传递的自定义消息事件,比如礼物消息,可以设置:
let event = "gift";
let customBody = new CustomMessageBody(event);
// `params` 类型为 `Map<string, string>`。
customBody.setParams(params);
// 创建一条发送消息,`to` 指另一方环信用户 ID(或者群组 ID,聊天室 ID);
// 如果是群聊,设置 `ChatType` 为 `GroupChat`,该参数默认是单聊(`Chat`)。
let customMessage = ChatMessage.createSendMessage(to, customBody, ChatType.GroupChat);
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(customMessage);
发送合并消息
为了方便消息互动,SDK 支持将多个消息合并在一起进行转发。你可以采取以下步骤进行消息的合并转发:
- 利用原始消息列表创建一条合并消息。
- 发送合并消息。
提示
对于转发合并消息,例如,用户 A 向 用户 B 发送了合并消息,用户 B 将该合并消息转发给用户 C,需要调用转发单条合并消息的 API。详见 转发单条消息。
你可以调用 createCombinedSendMessage 方法创建一条合并消息,然后调用 sendMessage 方法发送该条消息。
创建合并消息时,需要设置以下参数:
| 属性 | 类型 | 描述 |
|---|---|---|
title | String | 合并消息的标题。 |
summary | String | 合并消息的概要。 |
compatibleText | String | 合并消息的兼容文本。 兼容文本起向下兼容不支持消息合并转发的版本的作用。当支持合并消息的 SDK 向不支持合并消息的低版本 SDK 发送消息时,低版本的 SDK 会将该属性解析为文本消息的消息内容。 |
messageIds | Array | 合并消息的原始消息 ID 数组。该数组最多包含 300 个消息 ID。 |
to | String | 消息接收方。该字段的设置取决于会话类型: - 单聊:对方用户 ID; - 群聊:群组 ID; - 聊天室聊天:聊天室 ID。 |
提示
- 合并转发支持嵌套,最多支持 10 层嵌套,每层最多 300 条消息。
- 不论
ChatOptions#setAutoTransferMessageAttachments设置为false或true,SDK 都会将合并消息附件上传到环信服务器。 - 合并消息不支持搜索。
示例代码如下:
let title = "A和B的聊天记录";
let summary = "A:这是A的消息内容\nB:这是B的消息内容";
let compatibleText = "您当前的版本不支持该消息,请升级到最新版本";
let message = ChatMessage.createCombinedSendMessage(title, {summary: summary, compatibleText: compatibleText, messageIds: ["msgId1", "msgId2"]});
let messageCallback: ChatCallback = {
onSuccess: () => {
// 消息发送成功的处理逻辑
},
onError: (code: number, error: string) => {
// 消息发送失败的处理逻辑
}
}
message.setMessageStatusCallback(messageCallback);
ChatClient.getInstance().chatManager()?.sendMessage(message);
更多
上传消息附件至自有服务器
发消息时,若要将消息附件上传至你自己的服务器(而非环信服务器),需执行以下操作:
- 在 SDK 初始化时调用
ChatOptions#setAutoTransferMessageAttachments(false),使 SDK 不再自动上传或下载附件。设置后,ChatManager#sendMessage()将不再处理图片、视频等附件的自动处理与上传逻辑。 - 图片上传到你的服务器后,将附件 URL 填入消息体,然后发送消息。 以图片消息为例,上传后获取其 URL,通过
ImageMessageBody#setRemoteUrl(string)设置到消息体中,然后调用sendMessage()发送消息。
// 1. SDK 初始化时关闭“自动上传附件到环信服务器”
// 注意:ChatOptions 构造参数需要提供 AppKey/AppId(示例仅展示关键点)
let options = new ChatOptions({ appKey: '<YourAppKey>' });
options.setAutoTransferMessageAttachments(false);
ChatClient.getInstance().init(context, options);
// 2. 你的业务:将图片上传到自有服务器,拿到可访问的 URL
// const urlPath = await uploadToYourServerAndGetUrl(...);
// 3. 发送图片消息
export function sendPrivateUrlImg(
toUserId: string,
urlPath: string,
localPathForPreview: string /*可选:用于本地预览/占位*/
) {
// 将远端 URL(你的服务器地址)写入消息体
const body = new ImageMessageBody(localPathForPreview);
body.setRemoteUrl(urlPath); // 图片远程 URL(你的服务器地址)
body.setFileName('IMG_111.png'); // 可选:文件名
// body.setFileLength(10000); // 可选:文件大小(字节),不设置也可以
// 构造图片发送消息(仍建议传一个本地路径用于本地展示;实际下载通过 urlPath 由你自己控制)
const message = ChatMessage.createSendMessage(toUserId, body, ChatType.Chat);
if (!message) {
// localPathForPreview 不可访问时,createImageSendMessage 会返回 undefined
return;
}
// (可选)发送回调
message.setMessageStatusCallback({
onSuccess: () => { /* send success */ },
onError: (code: number, error: string) => { /* send fail */ },
onProgress: (progress: number) => { },
});
// 发送消息
ChatClient.getInstance().chatManager()?.sendMessage(message);
}
提示
接收端收到消息后,可通过 (message.getBody() as ImageMessageBody).getRemoteUrl() 获取你的 URL,然后用你自己的下载/展示逻辑处理(因为你已关闭 SDK 自动附件传输)。
聊天室消息优先级与消息丢弃逻辑
消息优先级:对于聊天室消息,环信即时通讯提供消息分级功能,支持高、普通和低三种优先级,高优先级的消息会优先送达。你可以在创建消息时对指定消息类型或指定成员的消息设置为高优先级,确保这些消息优先送达。这种方式可以确保在聊天室内消息并发量较大或消息发送频率过高的情况下,服务器首先丢弃低优先级消息,将资源留给高优先级消息,确保重要消息(如打赏、公告等)优先送达,以此提升重要消息的可靠性。请注意,该功能并不保证高优先级消息必达。在聊天室内消息并发量过大的情况下,为保证用户实时互动的流畅性,即使是高优先级消息仍然会被丢弃。
消息丢弃逻辑:对于单个聊天室,每秒发送的消息数量默认超过 20 条,则会触发消息丢弃逻辑,即首先丢弃低优先级的消息,优先保留高优先级的消息。若带有优先级的消息超过了 20 条/秒,则按照消息发送时间顺序处理,丢弃后发送的消息。
let message = ChatMessage.createTextSendMessage(conversationId, content);
if (!message) {
return;
}
message.setChatType(ChatType.ChatRoom);
// 聊天室消息的优先级。如果不设置,默认值为 `PriorityNormal`,即“普通”优先级。
message.setPriority(ChatroomMessagePriority.PriorityHigh);
sendMessage(message);
语聊房麦位管理
基于 聊天室自定义属性,实现语聊房的麦位状态管理与多端实时同步。将麦位列表(含用户信息、麦位状态、音量等字段)作为房间属性存储,任何麦位变更通过更新属性触发全房间广播,确保所有客户端状态一致。详见 聊天室自定义属性。
获取发送附件消息的进度
发送附件类型消息时,可以在 onProgress 回调中获取附件上传的进度,以百分比表示,示例代码如下:
// 发送消息时可以设置 `ChatCallback` 的实例,获得消息发送的状态。可以在该回调中更新消息的显示状态。例如,消息发送失败后的提示等等。
let callback: ChatCallback = {
onSuccess: (): void => {
// 发送消息成功
},
onError: (code: number, error: string): void => {
// 发送消息失败
},
onProgress: (progress: number): void => {
// 消息发送的状态,这里只用于附件类型的消息。
}
}
message.setMessageStatusCallback(callback);
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
发送消息前的内容审核
- 内容审核关注消息 body
内容审核服务会关注消息 body 中指定字段的内容,不同类型的消息审核不同的字段,若创建消息时在这些字段中传入了很多业务信息,可能会影响审核效果。因此,创建消息时需要注意内容审核的字段不涉及业务信息,建议业务信息放在扩展字段中。
- 设置发送方收到内容审核替换后的内容
默认情况下,内容审核替换后的内容仅下发至接收方。发送方如需同步接收替换内容,需 联系环信商务开通权限,并在初始化 SDK 时调用 ChatOptions#setUseReplacedMessageContents(true)。开启后,发送方将在消息被审核替换时收到新内容;若开关关闭(默认状态),则发送方仍保留原始发送内容,不会感知替换结果。
消息大小和存储限制
各类消息的大小和存储限制,详见 消息限制说明。
发消息时设置回调路由
自 HarmonyOS SDK 1.15.0 起,支持发消息时为消息配置回调环境标识,使消息可按指定路由触发发送前回调和发送后回调。
回调路由允许你在同一个 App Key 下,将不同消息按回调环境分别投递到不同的回调地址。发送消息时,可以在消息中携带回调环境标识,环信服务器根据该标识匹配控制台中配置的回调路由规则,并将消息回调至对应的发送前回调或发送后回调地址。
提示
目前,该功能仅面向国内 1 区和国内 2 区开放。
适用场景
| 场景 | 说明 |
|---|---|
| 多环境隔离 | 同一 App Key 下区分开发、测试、生产环境,消息分别回调至各自的服务地址。 |
| 灰度发布 | 部分消息回调至新链路验证,其余消息仍走旧链路。 |
| 多业务线分流 | 不同业务模块的消息回调至各自的审核、风控或同步服务。 |
| 降低发送前时延 | 避免消息先统一回调至一个入口,再由业务服务器二次转发。 |
适用范围
| 回调类型 | 生效范围 | 说明 |
|---|---|---|
| 发送前回调 | 仅对 SDK 发送的消息 生效(不支持群组/聊天室的定向消息)。 | 消息下发给目标用户前,你的服务器可判断是否拦截或修改消息内容。 |
| 发送后回调 | 对 SDK 和 REST API 发送的消息 均生效。 | 消息成功发送后,通知你的服务器。 |
工作流程
- 在控制台为发送前回调或发送后回调配置回调路由。
- 客户端发送消息时,通过
ChatMessage#setWebhookEnv设置回调环境标识。 - 环信服务器收到消息后,根据消息中的回调环境值匹配当前阶段的回调地址。
- 命中有效路由后,服务器将回调请求发送到对应地址。
示例代码
发消息时调用 setWebhookEnv 设置回调环境。
回调环境参数 webhookEnv 的说明如下:
| 参数 | 类型 | 是否必需 | 说明 |
|---|---|---|---|
webhookEnv | string | 否 | 回调环境值。回调环境仅支持字母和数字,长度不超过 8 个字符。服务器根据该值匹配控制台中的回调地址。建议与控制台中配置的回调环境保持一致,例如 dev、test、prod。未设置回调环境标识时,消息使用 default 环境;设置了标识但未命中有效路由时,不触发回调。 |
调用 setWebhookEnv 设置回调环境:
// 创建文本消息。
let message = ChatMessage.createTextSendMessage('toUser', 'hello');
if (!message) {
return;
}
// 设置回调环境标识。
message.setWebhookEnv('test');
// 发送消息。
ChatClient.getInstance().chatManager()?.sendMessage(message);
// 读取当前消息的回调环境标识;未设置时返回 undefined。
let webhookEnv = message.getWebhookEnv();
消息中的回调环境字段命中规则
| 场景 | 路由结果 |
|---|---|
| 携带环境值且命中有效路由 | 按该环境值路由至对应的回调地址。 |
| 携带环境值但未命中有效路由 | 不触发回调,控制台中的 default 兜底配置在此场景下 不生效。 |
| 未携带环境值 | 自动路由至 default 环境对应的回调地址。 |
| 同一消息需同时触发发送前与发送后回调 | 两个阶段必须使用 相同的环境值。例如,发送前配置 test -> url1,发送后配置 test -> url2,则消息中携带 test 即可同时生效于两阶段。 |
