ZIM SDK 支持单聊消息、群组消息、房间消息等的收发,以及查询历史消息、删除消息等功能。可广泛应用于娱乐社交、电商购物、在线教育、互动直播等多种场景下。
本文档介绍了如何使用 ZIM SDK 的接口,实现各类消息的收发功能与监听消息的状态。
目前 ZIM 支持的消息类型如下:
消息类型 | 说明 | 特性及适用场景 |
---|---|---|
ZIMTextMessage(1) |
文本消息。消息大小不超过 32 KB,单个客户端发送频率限制为 10 次/秒。 |
消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。);一般适用于“单聊”、“群聊”等即时聊天的场景和“房间聊天”的公屏聊天场景。房间解散后,“房间聊天”的消息不存储。
相关接口:sendMessage |
ZIMCommandMessage(2) |
开发者可自定义数据内容的信令消息。消息大小不超过 5 KB,单个客户端发送频率限制为 10 次/秒。 |
支持更高的并发;一般适用于“语聊房”、“在线课堂”等房间内的信令传输,比如上下麦操作、送礼物,发送在线课堂课件等。
相关接口:sendMessage |
ZIMBarrageMessage(20) |
房间内弹幕文本消息。消息大小不超过 5 KB,单个客户端发送频率无限制。 |
专门用于房间内的高频、不可靠、允许丢掉的消息,一般适用于发送“弹幕消息”的场景中。 支持高并发,但不可靠,不保证消息送达。 相关接口:sendMessage |
ZIMImageMessage(11) |
图片消息。支持主流图片格式,包括 JPG、PNG、BMP、TIFF、GIF、WebP,大小不超过 10 MB,单个客户端发送频率限制为 10 次/秒。 |
消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。);一般用于单聊、房间、群聊等即时聊天场景。
相关接口: sendMediaMessage |
ZIMFileMessage(12) |
文件消息。消息内容为文件,格式不限,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。 |
|
ZIMAudioMessage(13) |
语音消息。支持 MP3、M4A 格式的语音文件,时长不超过 300 秒,大小不超过 6 MB,单个客户端发送频率限制为 10 次/秒。 |
|
ZIMVideoMessage(14) |
视频消息。支持 MP4、MOV 格式的视频文件,大小不超过 100 MB,单个客户端发送频率限制为 10 次/秒。仅支持视频编码格式为 H264 和 H265 的视频文件在消息发送成功后获取该视频首帧的宽、高信息。 |
|
ZIMCombineMessage(100) |
合并消息,消息大小无限制,单个客户端发送频率限制为 10 次/秒。 |
消息可靠有序,可存储为历史消息(保存时间请参考 计费说明 - 版本说明 中“历史消息存储天数”。);一般用于单聊、房间、群聊等即时聊天场景。
相关接口:sendMessage |
ZIMCustomMessage(200) |
自定义消息。开发者可自定义消息的类型,并自行完成消息的解析,ZIM SDK 不负责定义和解析自定义消息的具体内容。 |
一般可用于发送投票类型、接龙类型、视频卡片类型等消息。
相关接口: sendMessage |
在实现“收发消息”功能之前,请确保:
普通消息,包含 ZIMTextMessage、ZIMBarrageMessage 等消息类型。
type
(具体请参考 ZIMMessageType)字段,判断消息类型是 Text 还是 Command,然后强转基类为具体的子类(ZIMTextMessage 或 ZIMCommandMessage),然后从 “message” 字段获取消息内容。以客户端 A 向客户端 B 发送消息为例:
conversationType
为 zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER
发送一条单聊消息到客户端 B。目前 ZIM 不支持调用 sendMessage
接口,向自己发送消息(即 toConversationID = 自己的 ID)。如果尝试向自己发送消息,会返回错误 6000001,并提示传入参数错误。
virtual void sendMessage(std::shared_ptr<ZIMMessage> message,
const std::string &toConversationID,
ZIMConversationType conversationType,
const ZIMMessageSendConfig &config,
std::shared_ptr<ZIMMessageSendNotification> notification,
ZIMMessageSentCallback callback) = 0;
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
message | std::shared_ptr<ZIMMessage> | 是 | 发送的单聊消息内容。 |
toConversationID | std::string | 是 | 会话 ID。
|
conversationType | ZIMConversationType | 是 | 会话类型。
|
config | ZIMMessageSendConfig | 是 | 发送消息的高级属性配置,包含如下配置:
|
notification | std::shared_ptr<ZIMMessageSendNotification> | 是 | 发送通知的回调。 |
callback | ZIMMessageSentCallback | 是 | 发送消息操作的结果回调。 |
// 1、创建 ZIM 对象,传入 appID、appSign,目前仅建议一个客户端创建一个zim实例
zim::ZIMAppConfig app_config;
app_config.appID = 12345; //替换为您申请到的 AppID
app_config.appSign = "appSign"; //替换为您申请到的 AppSign
zim_ = zim::ZIM::create(app_config);
// 2、设置 setEventHandler 回调
im_event_handler_ = std::make_shared<CZIMEventHandler>();
zim_->setEventHandler(im_event_handler_);
// 3、登录
zim::ZIMUserInfo user_info;
user_info.userID = user_id;
user_info.userName = user_name;
zim_->login(user_info, [=](zim::ZIMError errorInfo){
// 这里可以获取登录结果返回值,并根据错误码执行用户代码
});
// 4、发送普通消息
zim::ZIMMessage* message = nullptr;
zim::ZIMTextMessage text_message;
text_message.message = "message";
// 设置消息优先级
zim::ZIMMessageSendConfig config;
config.priority = zim::ZIM_MESSAGE_PRIORITY_LOW;
message = &text_message;
// 发送单聊信息
zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER
// 发送群聊信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP
// 发送房间信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_ROOM
auto notification = std::make_shared<zim::ZIMMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) { int i = 0; });
// 5、发送消息
zim_->sendMessage(message, "toConversationID", type, config, notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message,
const zim::ZIMError &errorInfo) { int i = 0; });
// 收到单聊消息的回调
void onReceivePeerMessage(ZIM *zim*,
const std::vector<std::shared_ptr<ZIMMessage>> & messageList,
const std::string &fromUserID) {
//在此编写收到消息后的业务逻辑
}
void onReceiveGroupMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromGroupID*/) {
//在此编写收到消息后的业务逻辑
}
// 收到房间消息的回调
void onReceiveRoomMessage(ZIM * /*zim*/,
const std::vector<std::shared_ptr<ZIMMessage>> & /*messageList*/,
const std::string & /*fromRoomID*/) {
//在此编写收到消息后的业务逻辑
}
ZIM SDK 支持发送多种类型的富媒体消息,包含图片、文件、音频、视频等消息类型,开发者可以通过以下步骤实现富媒体文件消息的收发。
用户登录成功后,调用 sendMediaMessage 接口,指定会话、消息类型(图片、文件、音频、视频)、会话类型(单聊、房间、群组)、以及相关消息配置,向指定会话发送富媒体消息。
UTF-8
编码格式。virtual void sendMediaMessage(std::shared_ptr<ZIMMediaMessage> message,
const std::string &toConversationID,
ZIMConversationType conversationType,
const ZIMMessageSendConfig &config,
std::shared_ptr<ZIMMediaMessageSendNotification > notification,
ZIMMessageSentCallback callback) = 0;
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
message | std::shared_ptr<ZIMMediaMessage> | 是 | 发送的单聊消息内容。使用时,请根据多媒体消息类型,修改 message 的类型。例如,发送图片消息时,请使用 ZIMImageMessage。 |
toConversationID | std::string | 是 | 会话 ID。
|
conversationType | ZIMConversationType * | 是 | 会话类型。
|
config | ZIMMessageSendConfig * | 是 | 发送消息的高级属性配置,包含如下配置:
|
notification | std::shared_ptr<ZIMMediaMessageSendNotification> * | 是 | 消息发送前和发送消息进度的通知回调。 |
callback | ZIMMessageSentCallback | 是 | 发送消息操作的结果回调。 |
// 发送多媒体消息示例 - 单聊 发送图片消息
zim::ZIMMediaMessage *message = nullptr;
auto imageMessage = zim::ZIMImageMessage();
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
// 离线推送标题,需要离线推送时,请填入该字段
pushConfig.title = "win_push_title";
// 离线推送内容,需要离线推送时,请填入该字段
pushConfig.content = "win_push_content";
// 离线推送附加字段,需要离线推送带上额外信息时,可酌情填入该字段
pushConfig.extendedData = "win_push_extended_data";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
// 需要离线推送时赋值;如不需要,可赋值为 nullptr
sendConfig.pushConfig = &pushConfig;
// 需填入 UTF-8 格式的本地路径
imageMessage.fileLocalPath = "D:\\image\\img.jpg";
// 如果此处填入了网络 URL,SDK 则会透传该路径,而不会经过 ZIM 后台服务处理。同时填入网络 URL 与本地路径,SDK 会优先认为用户想要使用网络 URL
imageMessage.fileDownloadUrl = "";
imageMessage.largeImageDownloadUrl = "";
imageMessage.thumbnailDownloadUrl = "";
message = &imageMessage;
auto notification = std::make_shared<zim::ZIMMediaMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) {
int i = 0;
},
[=](const std::shared_ptr<zim::ZIMMediaMessage> &message,
unsigned long long currentFileSize,
unsigned long long totalFileSize) {
int i = 0;
});
zim_->sendMediaMessage(message, receiver_id, zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
sendConfig,notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message, const zim::ZIMError &errorInfo) {
});
// 发送多媒体消息示例 - 单聊 发送文件消息
zim::ZIMMediaMessage *message = nullptr;
auto fileMessage = zim::ZIMFileMessage();
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
// 离线推送标题,需要离线推送时,请填入该字段
pushConfig.title = "win_push_title";
// 离线推送内容,需要离线推送时,请填入该字段
pushConfig.content = "win_push_content";
// 离线推送附加字段,需要离线推送带上额外信息时,可酌情填入该字段
pushConfig.extendedData = "win_push_extended_data";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
// 需要离线推送时赋值;如不需要,可赋值为 nullptr
sendConfig.pushConfig = &pushConfig;
// 需填入 UTF-8 格式的本地路径
fileMessage.fileLocalPath = "D:\\file\\files.zip";
// 如果此处填入了网络 URL,SDK 则会透传该路径,而不会经过 ZIM 后台服务处理。同时填入网络 URL 与本地路径,SDK 会优先认为用户想要使用网络 URL
fileMessage.fileDownloadUrl = "";
message = &fileMessage;
auto notification = std::make_shared<zim::ZIMMediaMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) {
// 开发者可监听此回调,执行消息发送前的逻辑
},
[=](const std::shared_ptr<zim::ZIMMediaMessage> &message,
unsigned long long currentFileSize,
unsigned long long totalFileSize) {
// 开发者可监听此回调,获取资源上传的进度
});
zim_->sendMediaMessage(message, receiver_id, zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
sendConfig,,notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message, const zim::ZIMError &errorInfo) {
auto media_message = std::static_pointer_cast<zim::ZIMFileMessage>(message);
int code = errorInfo.code;
});
// 发送多媒体消息示例 - 单聊 发送音频消息
zim::ZIMMediaMessage *message = nullptr;
auto audioMessage = zim::ZIMAudioMessage();
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
// 离线推送标题,需要离线推送时,请填入该字段
pushConfig.title = "win_push_title";
// 离线推送内容,需要离线推送时,请填入该字段
pushConfig.content = "win_push_content";
// 离线推送附加字段,需要离线推送带上额外信息时,可酌情填入该字段
pushConfig.extendedData = "win_push_extended_data";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
// 需要离线推送时赋值;如不需要,可赋值为 nullptr
sendConfig.pushConfig = &pushConfig;
// 需填入 UTF-8 格式的本地路径
audioMessage.fileLocalPath = "D:\\audio\\audio.mp3";
// 如果此处填入了网络 URL,SDK 则会透传该路径,而不会经过 ZIM 后台服务处理。同时填入网络 URL 与本地路径,SDK 会优先认为用户想要使用网络 URL
audioMessage.fileDownloadUrl = "";
// 音频时长的单位为 秒
audioMessage.audioDuration = 15;
message = &audioMessage;
auto notification = std::make_shared<zim::ZIMMediaMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) {
// 开发者可监听此回调,执行消息发送前的逻辑
},
[=](const std::shared_ptr<zim::ZIMMediaMessage> &message,
unsigned long long currentFileSize,
unsigned long long totalFileSize) {
// 开发者可监听此回调,获取资源上传的进度
});
zim_->sendMediaMessage(message, receiver_id, zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
sendConfig,notification ,
[=](const std::shared_ptr<zim::ZIMMessage> &message, const zim::ZIMError &errorInfo) {
auto media_message = std::static_pointer_cast<zim::ZIMAudioMessage>(message);
int code = errorInfo.code;
});
// 发送多媒体消息示例 - 单聊 发送视频消息
zim::ZIMMediaMessage *message = nullptr;
auto videoMessage = zim::ZIMVideoMessage();
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
// 离线推送标题,需要离线推送时,请填入该字段
pushConfig.title = "win_push_title";
// 离线推送内容,需要离线推送时,请填入该字段
pushConfig.content = "win_push_content";
// 离线推送附加字段,需要离线推送带上额外信息时,可酌情填入该字段
pushConfig.extendedData = "win_push_extended_data";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
// 需要离线推送时赋值;如不需要,可赋值为 nullptr
sendConfig.pushConfig = &pushConfig;
// 需填入 UTF-8 格式的本地路径
videoMessage.fileLocalPath = "D:\\file\\video.mp4";
// 如果此处填入了网络 URL,SDK 则会透传该路径,而不会经过 ZIM 后台服务处理。同时填入网络 URL 与本地路径,SDK 会优先认为用户想要使用网络 URL
videoMessage.fileDownloadUrl = "";
videoMessage.videoFirstFrameDownloadUrl = "";
// 视频时长的单位为 秒
videoMessage.videoDuration = 100;
message = &videoMessage;
auto notification = std::make_shared<zim::ZIMMediaMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) {
// 开发者可监听此回调,执行消息发送前的逻辑
},
[=](const std::shared_ptr<zim::ZIMMediaMessage> &message,
unsigned long long currentFileSize,
unsigned long long totalFileSize) {
// 开发者可监听此回调,获取资源上传的进度
});
zim_->sendMediaMessage(message, receiver_id, zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER,
sendConfig,notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message, const zim::ZIMError &errorInfo) {
auto media_message = std::static_pointer_cast<zim::ZIMVideoMessage>(message);
int code = errorInfo.code;
});
开发者可以通过 ZIMMediaUploadingProgress 回调,接收富媒体消息的上传发送进度的相关通知。
using ZIMMediaUploadingProgress =
std::function<void(const std::shared_ptr<ZIMMessage> &message, long long currentSize,
long long totalSize)>;
其中:
接收方用户登录成功后,根据会话类型(单聊、房间、群组)的相关回调监听(onReceivePeerMessage、onReceiveRoomMessage、onReceiveGroupMessage),接收富媒体消息的相关通知,然后可以调用 downloadMediaFile 接口,下载富媒体消息文件到本地。
下载富媒体消息时,需要指定对应的媒体消息的文件类型。
virtual void downloadMediaFile(ZIMMediaMessage *message, ZIMMediaFileType fileType,
ZIMMediaDownloadingProgress progress,
ZIMMediaDownloadedCallback callback) = 0;
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
message | ZIMMediaMessage * | 是 | 接收到的富媒体文件消息内容。 |
fileType | ZIMMediaFileType | 是 | 接收富媒体消息的文件类型。
|
progress | ZIMMediaDownloadingProgress | 是 | 下载消息进度。 |
callback | ZIMMediaDownloadedCallback | 是 | 下载消息操作的结果回调。 |
// 接收富媒体消息示例 - 单聊
void onReceivePeerMessage(
zim::ZIM *zim, const std::vector<std::shared_ptr<zim::ZIMMessage>> &messageList,
const std::string &fromUserID) {
for (auto &it : messageList) {
// 收到消息时,可通过消息的 Type 进行判断接收到何种类型的消息
if (it->getType() == zim::ZIMMessageType::ZIM_MESSAGE_TYPE_IMAGE) {
// Image message type
auto image_message = std::dynamic_pointer_cast<zim::ZIMImageMessage>(it);
// 下载原图示例如下,如果想下载其他类型,可以换用其他 ZIMMediaFileType
zim_->downloadMediaFile(
image_message.get(), zim::ZIMMediaFileType::ZIM_MEDIA_FILE_TYPE_ORIGINAL_FILE,
[=](const std::shared_ptr<zim::ZIMMessage> &message, unsigned int currentSize,
unsigned int totalSize) {
},
[=](const std::shared_ptr<zim::ZIMMessage> &message,
const zim::ZIMError &errorInfo) {
});
...
} else if (it->getType() == zim::ZIMMessageType::ZIM_MESSAGE_TYPE_FILE) {
// File message type
auto media_message = std::dynamic_pointer_cast<zim::ZIMFileMessage>(it);
...
} else if (it->getType() == zim::ZIMMessageType::ZIM_MESSAGE_TYPE_AUDIO) {
// Audio message type
auto media_message = std::dynamic_pointer_cast<zim::ZIMAudioMessage>(it);
...
} else if (it->getType() == zim::ZIMMessageType::ZIM_MESSAGE_TYPE_VIDEO) {
// Video message type
auto media_message = std::dynamic_pointer_cast<zim::ZIMVideoMessage>(it);
...
}
}
}
开发者可以通过 ZIMMediaMessageSendNotification 的onMediaUploadingProgress
回调,接收富媒体消息的下载进度的相关通知。
using ZIMMediaDownloadingProgress =
std::function<void(const std::shared_ptr<ZIMMessage> &message, unsigned int currentSize,
unsigned int totalSize)>;
其中:
ZIM SDK 支持开发者实现信令类型的消息收发,开发者可以通过 ZIMCommandMessage 对象定义自己的消息类型,例如位置消息等。
信令消息不支持离线推送和本地存储。
以下以向指定用户发送信令消息为例。
// 向指定用户发送信令消息
zim::ZIMMessage *message = nullptr;
zim::ZIMCommandMessage commandMessage;
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
pushConfig.content = "win_push_content";
pushConfig.extendedData = "win_push_extended_data";
pushConfig.title = "win_push_title";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
sendConfig.pushConfig = &pushConfig;
std::vector<uint8_t> uint8Message;
uint8Message.assign(strMessage.begin(), strMessage.end());
commandMessage.message = uint8Message;
message = &commandMessage;
// 发送单聊信息
zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER
// 发送群聊信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP
// 发送房间信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_ROOM
auto notification = std::make_shared<zim::ZIMMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) { int i = 0; });
// 发送消息
zim_->sendMessage(message, "toConversationID", type, config, notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message,
const zim::ZIMError &errorInfo) { int i = 0; });
//用户接收信令消息
void OnReceivePeerMessage(zim::ZIM *zim, const std::vector<std::shared_ptr<zim::ZIMMessage>> &message_list,
const std::string &from_user_id){
for (auto &it : message_list) {
if (it->getType() == zim::ZIM_MESSAGE_TYPE_COMMAND) {
auto commandMessage = std::dynamic_pointer_cast<zim::ZIMCommandMessage>(it);
}
}
}
ZIM SDK 支持开发者实现自定义类型的消息收发,开发者可以通过 ZIMCustomMessage 对象自行定义消息类型,例如投票类型、接龙类型、视频卡片类型等。开发者可以通过以下步骤实现自定义消息的收发。
发送自定义消息使用的接口为 sendMessage,与发送普通消息所用接口相同,开发者可参考 收发普通消息 - 发送消息 了解此接口参数详情。
开发者需要通过 ZIMCustomMessage 对象定义自定义类型消息,包括以下参数:
参数 | 类型 | 是否必填 | 说明 |
---|---|---|---|
message | std::string | 是 | 自定义消息的文本内容,开发者可传入一串特定格式的字符串,如 Json,以定制消息内容。 |
subType | unsigned int | 是 | 具体的自定义类型。值由您定义,取值范围为 [0,200]。消息接收端会根据不同的类型显示不同的样式。 |
searchedContent | std::string | 否 | 自定义消息的检索字段。由于无法通过直接搜索 message 字段来搜索自定义消息,您可把该自定义消息中希望被搜索的内容(如投票的标题等)拼接后放到此参数(长度上线默认为 64 字节),以便后续搜索。 |
以下为用户在单聊会话中发送自定义消息的示例代码:
// 向指定用户发送自定义消息
zim::ZIMMessage *message = nullptr;
zim::ZIMCustomMessage customMessage;
zim::ZIMMessageSendConfig sendConfig;
zim::ZIMPushConfig pushConfig;
pushConfig.content = "win_push_content";
pushConfig.extendedData = "win_push_extended_data";
pushConfig.title = "win_push_title";
sendConfig.priority = zim::ZIM_MESSAGE_PRIORITY_MEDIUM;
sendConfig.pushConfig = &pushConfig;
std::string message = "message";
unsigned int subType = 1;
std::string searchedContent = "searchedContent";
customMessage.message = message;
customMessage.subType = subType;
customMessage.searchedContent = searchedContent;
message = &customMessage;
// 发送单聊信息
zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_PEER
// 发送群聊信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_GROUP
// 发送房间信息
// zim::ZIMConversationType type = zim::ZIMConversationType::ZIM_CONVERSATION_TYPE_ROOM
auto notification = std::make_shared<zim::ZIMMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) { int i = 0; });
// 5、发送消息
zim_->sendMessage(message, "toConversationID", type, config, notification,
[=](const std::shared_ptr<zim::ZIMMessage> &message,
const zim::ZIMError &errorInfo) { int i = 0; });
接收自定义消息的回调接口与接收普通消息的回调接口一致,请参考 收发普通消息 - 接收消息 了解具体接口。
以下为用户在单聊会话中接收自定义消息的示例代码:
// 用户接收自定义消息
void OnReceivePeerMessage(zim::ZIM *zim, const std::vector<std::shared_ptr<zim::ZIMMessage>> &message_list,
const std::string &from_user_id){
for (auto &it : message_list) {
if (it->getType() == zim::ZIM_MESSAGE_TYPE_CUSTOM) {
auto commandMessage = std::dynamic_pointer_cast<zim::ZIMCustomMessage>(it);
}
}
}
@ 消息,是指包含“@ + 用户”内容的消息。被 @ 的用户在收到消息时会强提醒。
@ 消息不属于消息类型。一条消息既可以是文本消息或其他类型消息,同时也是 @ 消息。
在调用 sendMessage 发送消息时,可以通过以下 ZIMMessage 参数(可同时使用)将一条消息设置为 @ 信息:
仅 2.14.0 及以上版本的 ZIM SDK 支持发送消息中带 @ 信息。
// 创建提醒用户列表
std::vector<std::string> mentionArrayList;
// 添加提醒用户(用户可以不在当前会话)
mentionArrayList.push_back("userId1");
mentionArrayList.push_back("userId2");
// message 可以为任何类型消息
message->mentionedUserIDs = mentionArrayList;
// 提醒会话内所有其他用户查看消息
bool isMentionAll = true;
message->isMentionAll = true;
ZIMMessageSendConfig config;
// 设置消息优先级
config.priority = ZIMMessagePriority::LOW;
// 是否强推送给被提醒用户(不管对方是否开启了会话免打扰),默认为 false;
config.isNotifyMentionedUsers = true;
// 以发送单聊信息为例子
ZIMConversationType type = ZIMConversationType::Peer;
zim_->sendMessage(
message, "conv_id", type, config,
std::make_shared<zim::ZIMMessageSendNotification>(
[=](const std::shared_ptr<zim::ZIMMessage> &message) {
if (message) {
// 开发者可以通过该回调,监听消息是否开始准备发送。只有当通过本地基础参数检验的消息才会抛出该回调,否则通过 onMessageSent 回调抛出错误。
}
}),
[=](std::shared_ptr<zim::ZIMMessage> message, zim::ZIMError errorInfo) {
// 开发者可以通过该回调监听消息是否发送成功。
if (errorInfo.code == zim::ZIMErrorCode::ZIM_ERROR_CODE_SUCCESS) {
}
});
接收 @ 消息的回调接口与接收普通消息的回调接口一致,请参考 收发普通消息 - 接收消息 了解具体接口。
收到消息后,开发者可根据业务逻辑实现对应的功能,如高亮等。
当会话内用户被提醒后,可以被动或主动获取 mentionedInfoList。
mentionedInfoList,包含 @ 消息的对应消息 ID,发送者 userID,以及 @ 消息的类型 ZIMMessageMentionedType,开发者可用于实现标记会话等多样业务逻辑。
在用户被提醒时,会收到 onConversationChanged 回调,即可获取当前 ZIMConversation 的最新 mentionedInfoList。
void onConversationChanged(
ZIM * /*zim*/,
const std::vector<ZIMConversationChangeInfo> & /*conversationChangeInfoList*/) {
// conversationChangeInfoList 可拿到收到提醒的会话里面的 mentionInfoList
}
如用 queryConversationList 或者 queryConversation 主动拉取会话,也可获取会话里面的mentionedInfoList,可参考以下示例代码:
std::vector<ZIMMessageMentionedInfo> mentionedInfoList = conversation.mentionedInfoList;
接收 @ 消息后,用户需要清除会话的 mentionedInfoList,才能不再被提醒。
清除会话的 mentionedInfoList 接口与清除会话消息未读数接口相同:
会话内所有用户都可以通过 ZIMMessage 的 mentionedUserIDs 参数获取具体提醒用户列表,可此接口仅能返回 @ 消息发送用户通过 ZIMMessage 的 mentionedUserIDs 参数传入的用户列表。
std::vector<std::string> userIds = message.mentionedUserIDs;
会话内所有用户都可以通过 ZIMMessage 的 isMentionAll 参数,确认消息是否为全员提醒消息。
boolean isMentionAll = message.isMentionAll;
ZIM 支持您通过服务端向 App 所有在线用户发送消息,目标用户通过客户端接收相关消息。
请查看服务单 API 文档 全员推送 文档,实现从服务端向所有用户发送消息。
通过 onBroadcastMessageReceived 回调,即可接收全员推送消息。
示例代码:
// 用户接收全员推送消息
virtual void onBroadcastMessageReceived(ZIM * /*zim*/,
const std::shared_ptr<ZIMMessage> & /*message*/) {}
ZIM SDK 支持实现以下两种形式的消息转发:
具体实现流程,请参考 转发消息。
ZIM SDK 支持用户在会话内的操作转换为 Tips 消息。当相关操作出现后,ZIM SDK 会向会话发送一条 Tips 消息进行通知,详情请参考 接收 Tips 消息。
在一些弱网场景中,可能存在以下场景,即消息发送成功,但由于某些因素(如网络丢包),导致 ZIM SDK 未收到服务端应答。此时,ZIM SDK 会因应答超时而认为消息发送失败,但实际上消息发送成功,导致消息状态混乱。为解决该问题,明确消息最终状态, 2.6.0 或以上版本 SDK 支持开发者监听 onMessageSentStatusChanged 回调,接收消息的状态变化。消息的状态有三种,即 Sending、Success 和 Failed。根据消息状态的变化,开发者可判断消息发送是否成功,并在业务上做相应处理。
// 监听消息状态
void onMessageSentStatusChanged(zim::ZIM *zim, const std::vector<ZIMMessageSentStatusChangeInfo> &messageSentStatusChangeInfoList{
// 开发者可以在这里监听消息状态变更的回调。
}
联系我们
文档反馈