消息收发
更新时间: 2024/10/17 10:03:47
消息功能概述
SDK 提供一套完善的消息传输管理服务,包括收发消息,存储消息,上传下载附件,管理最近联系人等。原生支持发送文本,语音,图片,视频,文件,地理位置,提醒等多种类型消息,同时支持用户发送自定义的消息类型。消息功能具体介绍可参考产品介绍的 基础消息功能
NIMMessageType
消息类型
枚举 | 值 | 说明 |
---|---|---|
kNIMMessageTypeText | 0 | 文本类型消息 |
kNIMMessageTypekNIMMessageTypeImageText | 1 | 图片类型消息 |
kNIMMessageTypeAudio | 2 | 声音类型消息 |
kNIMMessageTypeVideo | 3 | 视频类型消息 |
kNIMMessageTypeLocation | 4 | 位置类型消息 |
kNIMMessageTypeNotification | 5 | 系统类型通知(包括入群出群通知等 |
kNIMMessageTypeFile | 6 | 文件类型消息 |
kNIMMessageTypeTips | 10 | 提醒类型消息,Tip内容根据格式要求填入消息结构中的kNIMMsgKeyServerExt字段 |
kNIMMessageTypeRobot | 11 | 智能机器人消(暂不支持) |
kNIMMessageTypeCustom | 100 | 自定义消息 |
kNIMMessageTypeUnknown | 1000 | 未知类型消息,作为默认值 |
NIMMessageFeature
消息类型
枚举 | 值 | 说明 |
---|---|---|
kNIMMessageFeatureDefault | 0 | 默认 |
kNIMMessageFeatureLeaveMsg | 1 | 离线消息 |
kNIMMessageFeatureRoamMsg | 2 | 漫游消息 |
kNIMMessageFeatureSyncMsg | 3 | 默认消息,多端同时登录时,同步到各端的消息 |
kNIMMessageFeatureCustomizedMsg | 4 | 透传消息 |
MessageSetting
消息设置
类型 | 参数 | 说明 |
---|---|---|
BoolStatus | resend_flag_ | 是否是重发消息,第一次发送0,再次重发该消息填 1 |
BoolStatus | need_push_ | 是否需要推送,1:需要,0:不需要 |
BoolStatus | push_need_badge_ | (可选)推送是否要做消息计数(角标) 1:需要,0:不需要 |
BoolStatus | push_need_prefix_ | (可选)推送是否需要前缀 默认 True |
string | push_content_ | 自定义推送文案,长度限制200字节 |
string | push_payload_ | 自定义的推送属性,限制非格式化的json字符串,长度限制2048 |
BoolStatus | server_history_saved_ | (可选)该消息是否存储云端历史,可选,默认填 1,1:需要,0:不需要,如果支持漫游和离线,则必须填1 |
BoolStatus | roaming_ | (可选)该消息是否支持漫游,可选, 默认1,1:需要,0:不需要 |
BoolStatus | self_sync_ | (可选)该消息是否支持发送者多端同步,默认填1, 1:需要,0:不需要 |
BoolStatus | routable_ | (可选)该消息是否抄送,0:不支持,1:支持,默认按照app的路由开关 |
BoolStatus | need_offline_ | (可选)消息是否要存离线,默认填1, 1:需要,0:不需要,如果需要支持漫游,必须填1 |
BoolStatus | anti_spam_enable_ | 是否需要过易盾反垃圾,1:需要,0:不需要 |
string | anti_spam_content_ | (可选)开发者自定义的反垃圾字段,长度限制:5000字符, 格式为json string,{"type" : 1:文本,2:图片,3视频, "data" : "文本内容or图片地址or视频地址"} |
string | local_ext_ | 本地扩展内容,只保存在本地,预留字段 |
string | server_ext_ | 第三方扩展字段, 长度限制1024 |
BoolStatus | is_force_push_ | 群组消息强推开关,强推全员设置true并强推列表为空 |
std::list< std::string > | force_push_ids_list_ | 群组消息强推列表 |
string | force_push_content_ | 群组消息强推文本 |
IMMessage
消息基础内容
类型 | 参数 | 说明 |
---|---|---|
NIMSessionType | session_type_ | 会话类型,详见NIMSessionType |
string | sender_accid_ | 消息发送方id,服务器填写,发送方不需要填写 |
string | receiver_accid_ | 消息接收方id,必填,如给自己发送消息时填写自己id |
NIMClientType | readonly_sender_client_type_ | 消息发送方客户端类型,服务器填写,发送方不需要填写 |
string | readonly_sender_device_id_ | 消息发送方设备id,服务器填写,发送方不需要填写 |
string | readonly_sender_nickname_ | 消息发送方昵称,服务器填写,发送方不需要填写 |
int64_t | timetag_ | 消息时间戳,(毫秒13位UNIX时间戳) |
NIMMessageType | type_ | 消息类型,详见NIMMessageType |
string | client_msg_id_ | 消息uuid,唯一标识,发送方填写 |
int64_t | readonly_server_id_ | 服务器端消息id,服务器填写 |
MessageSetting | msg_setting_ | 消息设置,详见MessageSetting |
string | local_res_path_ | 多媒体消息资源本地绝对路径,SDK本地维护,发送多媒体消息时必填,如果是图片消息,当设置下载缩略图时,此路径为缩略图的本地绝对路径 |
string | local_talk_id_ | 会话id,发送方选填,接收方收到的是消息发送方id |
string | local_res_id_ | 多媒体资源id,发送方选填,接收方收到的是客户端消息id |
NIMMsgLogStatus | status_ | 本地消息状态,详见消息状态类型) |
NIMMsgLogSubStatus | sub_status_ | 本地消息子状态,详见消息子状态类型) |
注意: 漫游消息是指在一端已经收过的消息,在未登录的一端也会下发(服务端最近100个会话)的消息,多端同步是指多个设备平台是同时登录时,一端发送消息,其他端同步收到发出的的消息,离线消息是指 发送给对方消息,如果对方不在线,对方在下次登录时会收到的消息。
消息相关设置说明:
SavedOffline | ServerSaveHistory | Roaming | MultiSync | |
---|---|---|---|---|
离线消息 | 1 | 1 | optional | optional |
漫游消息 | 1 | 1 | 1 | optional |
多端同步消息 | optional | optional | optional | 1 |
发送消息
SDK提供对普通文本消息,图片消息,语音消息,视频消息,文件消息,地理位置消息,提醒消息等等内置消息类型(NIMMessageType)的支持,也可以发送自定义的消息。同时我们也提供了停止发送消息接口,该接口目前主要用于在文件消息上传过程中终止消息发送。
- API 原型
static void SendMsg(const std::string& json_msg, const std::string& json_extension = "", FileUpPrgCallback* pcb = nullptr);
- 参数说明
参数 | 说明 |
---|---|
json_msg | 消息内容,详见IMMessage |
json_extension | 扩展字段,预留 |
pcb | 上传进度回调通知,如果存在图片、音视频文件 等自定上传的附件内容时,会通知上传进度 |
注意事项
一秒内默认最多调用发送消息接口100次。如需上调上限,请在官网首页通过微信、在线消息或电话等方式咨询商务人员。
消息设置
发送消息还提供了以下消息属性设置(对应MessageSetting中的字段):
-
消息支持扩展字段,扩展字段分为服务器扩展字段kNIMMsgKeyServerExt和本地扩展字段kNIMMsgKeyLocalExt,最大长度1024字节。对于服务器扩展字段,该字段会发送到其他端,而本地扩展字段仅在本地有效。对于这两种扩展字段, SDK 都会存储在数据库中。
-
推送文案字段(
kNIMMsgKeyPushContent
,最大长度200字节)和自定义推送属性(kNIMMsgKeyPushPayload
,最大长度2048字节),请注意最大长度的限制。设置了推送文案后,接收方收到消息时,在通知栏提醒中会显示该文案,如果不设置则采用 SDK 默认的文案。 -
是否需要推送字段(
kNIMMsgKeyPushEnable
),0:不需要,1:需要。 -
推送是否要做消息计数字段(
kNIMMsgKeyNeedBadge
),0:不需要,1:需要。 -
推送是否需要推送昵称(
kNIMMsgKeyNeedPushNick
),0:不需要,1:需要。 -
消息是否存储云端(
kNIMMsgKeyHistorySave
),如果设置为0,则通过拉取服务器消息历史的接口无法获取该条消息。0:不需要,1:需要。 -
消息是否支持漫游(
kNIMMsgKeyMsgRoaming
),如果需要,即使某一个客户端收取过这条消息,其他客户端再次登录也会漫游到这条消息。0:不需要,1:需要。 -
消息是否支持多端同步(
kNIMMsgKeyMsgSync
),如果需要,则会在发送一条消息后,将这条消息同步到同时登录的其他客户端。0:不需要,1:需要。
针对群组消息,提供强推属性设置(可以用于实现@功能等):
-
是否强推字段(
kNIMMsgKeyIsForcePush
),0:不需要,1:需要。 -
强推列表字段(
kNIMMsgKeyForcePushList
),推送指定账号id string array json, 如果强推全员不填。 -
强推文本字段(
kNIMMsgKeyForcePushContent
),群组消息强推文本。
反垃圾字段:
-
开发者指定的该条消息反垃圾规则的ID(kMsgTagAntiSpamBusinessId) 规则ID,保持与服务端一致
-
是否需要过易盾反垃圾(kNIMMsgKeyAntiSpamEnable),0:不需要,1:需要。
-
需要过易盾反垃圾的自定义内容(kNIMMsgKeyAntiSpamContent),长度限制5000字符,格式为json string,{"type" : 1:文本,2:图片,3视频,"data" : "文本内容or图片地址or视频地址"}。
-
单条消息是否使用易盾反垃圾(kNIMMsgKeyAntiSpamUsingYiDun), 0:(在开通易盾的情况下)不过易盾反垃圾而是通用反垃圾 其他都是按照原来的规则.
文本消息
首先创建文本消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。
- API 原型
static std::string CreateTextMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const std::string& content, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
content | 文本内容 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳,毫秒 |
- 示例
//以点对消息为例,测试账号test1
Json::FastWriter fw;
std::string content = "这是一条文本消息。";
//消息设置,按需设置
//其他消息设置,其他消息类似
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//如果需要反垃圾
setting.anti_spam_enable_ = 1;
//组装反垃圾内容
Json::Value jx;
jx["type"] = 1;
jx["data"] = content;//如果是图片视频类型,填附件的url
setting.anti_spam_content_ = fw.write(jx);//序列化得到json字符串
//其他设置
...
//创建消息
std::string msg = nim::Talk::CreateTextMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",content,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
图片消息
首先创建图片消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。发送本地图片文件会自动上传。
图片消息的附件内容IMImage
派生自IMFile,其自有字段说明
类型 | 参数 | 字段 |
---|---|---|
int | width_ | 图片宽度 |
int | height_ | 图片高度 |
- API 原型
static std::string CreateImageMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const IMImage& image, const std::string& file_path, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
image | 图片附件内容,详见IMImage |
file_path | 本地图片文件路径,如果文件存在,SDK自动上传 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
IMImage attachment;
attachment.md5_ = "0ca175b9c0f726a831d895e269332461";
attachment.size_ = 409600;
attachment.url_="http://xxxxxx/img.png";//如果发送本地文件,此处填空
attachment.display_name_ = "img";
attachment.file_extension_ = "png";
//设置图片高度和宽度
attachment.width_ = 800;
attachment.height = 600;
//本地文件路径
std::string local_file_path = "c:\\img.png";
//创建消息
std::string msg = nim::Talk::CreateImageMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",attachment,local_file_path,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
语音消息
首先创建语音消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。发送本地语音文件会自动上传。
语音消息的附件内容IMAudio
派生自IMFile,其自有字段说明
类型 | 参数 | 字段 |
---|---|---|
int | duration_ | 语音消息时长 |
- API 原型
static std::string CreateAudioMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const IMAudio& audio, const std::string& file_path, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
audio | 语音附件内容,详见IMAudio |
file_path | 本地文件路径,如果文件存在,SDK自动上传 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
IMAudio attachment;
attachment.md5_ = "0ca175b9c0f726a831d895e269332461";
attachment.size_ = 409600;
attachment.url_="http://xxxxxx/audio.aac";//如果发送本地文件,此处填空
attachment.display_name_ = "audio";
attachment.file_extension_ = "aac";
//设置时长
attachment.duration_ = 8000;//毫秒
//本地文件路径
std::string local_file_path = "c:\\audio.aac";
//创建消息
std::string msg = nim::Talk::CreateAudioeMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",attachment,local_file_path,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
视频消息
首先创建视频消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。发送本地视频文件会自动上传。
视频消息的附件内容IMVideo
派生自IMFile,其自有字段说明
类型 | 参数 | 字段 |
---|---|---|
int | duration_ | 语音消息时长 |
int | width_ | 图片宽度 |
int | height_ | 图片高度 |
- API 原型
static std::string CreateVideoMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const IMVideo& video, const std::string& file_path, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
video | 视频附件内容,详见IMVideo |
file_path | 本地文件路径,如果文件存在,SDK自动上传 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
IMVideo attachment;
attachment.md5_ = "0ca175b9c0f726a831d895e269332461";
attachment.size_ = 409600;
attachment.url_="http://xxxxxx/video.mp4";//如果发送本地文件,此处填空
attachment.display_name_ = "video";
attachment.file_extension_ = "mp4";
//设置时长,图像长宽
attachment.duration_ = 8000;//毫秒
attachment.width_ = 800;
attachment.height = 600;
//本地文件路径
std::string local_file_path = "c:\\video.mp4";
//创建消息
std::string msg = nim::Talk::CreateVideoMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",attachment,local_file_path,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
地理位置
首先创建地理位置息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。
地理位置消息的附件内容NIMLocationMsgInfo
字段说明
类型 | 参数 | 字段 |
---|---|---|
string | description_ | 地理位置描述 |
int | latitude_ | 纬度 |
int | longitude_ | 经度 |
- API 原型
tatic std::string CreateLocationMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const IMLocation& location, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
location | 地理位置附件内容,详见IMLocation |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
IMLocation attachment;
//设置地理名称和经纬度
attachment.description_ = "杭州";
attachment.latitude_ = 30.3;
attachment.longitude_ = 120.2;
//创建消息
std::string msg = nim::Talk::CreateLocationMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",attachment,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
文件消息
首先创建文件消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。
IMFile
文件类型附件基类
类型 | 参数 | 字段 |
---|---|---|
string | md5_ | 文件内容的md5 |
int64_t | size_ | 文件大小,64位整型 |
string | url_ | 文件的http url |
string | display_name_ | 文件名 |
string | file_extension_ | 文件扩展名 |
- API 原型
static std::string CreateFileMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const IMFile& file, const std::string& file_path, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
file | 文件附件内容,详见IMFile |
file_path | 本地文件路径,如果文件存在,SDK自动上传 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
IMFile attachment;
attachment.md5_ = "0ca175b9c0f726a831d895e269332461";
attachment.size_ = 409600;
attachment.url_="http://xxxxxx/文档.doc";//如果发送本地文件,此处填空
attachment.display_name_ = "文档";
attachment.file_extension_ = "doc";
//本地文件路径
std::string local_file_path = "c:\\文档.doc";
//创建消息
std::string msg = nim::Talk::CreateFileMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",attachment,local_file_path,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
提示消息
首先创建提示消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。如果开发者不需要发送到服务器,则可以使用插入本地消息接口,将消息存入数据库,并更新会话类表。
- API 原型
static std::string CreateTipMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const std::string& tip_content, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
receiver_id | 聊天对象的 ID,如果是单聊,为用户帐号,如果是群聊,为群组 ID |
session_type | 会话类型 |
client_msg_id | 客户端消息id,建议uuid |
tip_content | 提示消息内容,自行定义解析 |
msg_setting | 消息属性设置 |
timetag | 当前UNIX时间戳 毫秒 |
- 示例
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
std::string tip_content = "这是提示信息";
//创建消息
std::string msg = nim::Talk::CreateTipMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",tip_content,setting,1520500638234);
//发送消息(或者在某些场景下,用户使用nim::MsgLog::WriteMsglogToLocalAsync直接写入本地数据)
nim::Talk::SendMsg(msg,null);
自定义消息
首先创建自定义消息消息的内容,按需填写必要的消息设置,然后通过SendMsg
接口发送。除SDK 不负责定义和解析自定义消息的具体内容,解释工作由开发者完成。SDK 会将自定义消息存入消息数据库,会和内建消息一并展现在消息记录中。
- 示例
std::string CreateCustomMessage(const std::string& receiver_id, const NIMSessionType session_type, const std::string& client_msg_id, const std::string& content, const std::string& attachment, const MessageSetting& msg_setting, int64_t timetag/* = 0*/)
{
Json::Value values;
values[kNIMMsgKeyToAccount] = receiver_id;
values[kNIMMsgKeyToType] = session_type;
values[kNIMMsgKeyClientMsgid] = client_msg_id;
values[kNIMMsgKeyBody] = content;
values[kNIMMsgKeyAttach] = attachment; //自定义附件内容;
values[kNIMMsgKeyType] = kNIMMessageTypeCustom;//自定义消息
values[kNIMMsgKeyLocalTalkId] = receiver_id;
msg_setting.ToJsonValue(values);
//选填
if (timetag > 0)
values[kNIMMsgKeyTime] = timetag;
Json::FastWriter fw;
return fw.write(values);
}
//以点对消息为例,测试账号test1
//消息设置,按需设置
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
//其他设置
...
//组装附件内容
Json::FastWriter fw;
Json::Value attachment;
attachment["customFiled1"] = "自定义内容1";
attachment["customFiled2"] = 10; //自定义值
std::string contemt = "这是普通文本内容";
//创建消息
std::string msg = CreateCustomMessage("test1",kNIMSessionTypeP2P,"生成自己的唯一uuid",contemt,fw.write(attachment),setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
群组强推消息
向群组发送强推消息,以@提醒指定的人或者所有人,详见MessageSetting
- 示例
//以群为例,测试群账号1222222
Json::FastWriter fw;
std::string content = "这是一条文本消息。";
//消息设置,按需设置
//其他消息设置,其他消息类似
MessageSetting setting;
setting.roaming_ = 1;
setting.need_offline_ = 1;
setting.server_history_saved_ = 1;
...
//强推test1,test2,且为群成员
setting.is_force_push_ = 1;
setting.force_push_ids_list_.push_back("test1");
setting.force_push_ids_list_.push_back("test2");
setting.force_push_content_ = "这是一条强推消息";
//其他设置
...
//创建消息
std::string msg = nim::Talk::CreateTextMessage("1222222",kNIMSessionTypeTeam,"生成自己的唯一uuid",content,setting,1520500638234);
//发送消息
nim::Talk::SendMsg(msg,null);
发送结果通知
通知发送成功、失败,也可以从结果获的是否命中客户端发垃圾标识。
SendMessageArc
参数说明
类型 | 参数 | 说明 |
---|---|---|
string | talk_id_ | 会话id |
string | msg_id_ | 消息id |
NIMResCode | rescode_ | 错误码 |
int64_t | msg_timetag_ | 消息时间戳 |
bool | client_anti_spam_hit_ | 是否命中客户端反垃圾,1:是, 0:否 |
- API 原型
static void RegSendMsgCb(const SendMsgAckCallback& cb, const std::string& json_extension = "");
- 示例
//监听事件
nim::Talk::RegSendMsgCb([&](const nim::SendMessageArc& ack)
{
...
});
//取消监听
nim::Talk::RegSendMsgCb(nullptr);
停止发送消息
取消发送消息,目前支持文件类型消息,在文件上传过程中可以终止发送。如果文件已经上传完成,则无法中断。
- API 原型
public static void StopSendMessage(NIMIMMessage message, ReportUploadProgressDelegate action = null);
- 参数说明
参数 | 说明 |
---|---|
message | 所要终止发送的消息结构 |
action | 预留,暂不使用 |
- 示例
//需要中断的消息唯一uuid,必填
std::string clientMsgId = "uuid";
//中断发送
nim::Talk::StopSendMsg(clientMsgId, kNIMMessageTypeFile);
消息接收
开发者在登陆SDK之前需要提前注册消息接收的事件监听。消息接收包括在线消息的接收,也包括离线、同步、漫游消息等的接收。如果接收到多媒体消息,SDK 默认会在后台自动下载附件。如果是语音消息,直接下载文件,如果是图片消息,下载缩略图文件,可以通过下载接口去获取原图。
消息解析
图片、文件、语音、视频、地理位置等等内置的消息提供了解析的支持,其他自定义的消息及附件内容需要开发者自行解析使用。
1. 解析消息内容
- API 原型
static bool ParseIMMessage(const std::string& json_msg, IMMessage& msg);
- 参数说明
参数 | 说明 |
---|---|
json_msg | 传入消息内容的json 无格式化字串 |
msg | 输出消息内容,详见IMMessage |
2. 解析接收消息
同解析消息内容区别在于,此函数解析kNIMMsgKeyLocalRescode
字段,kNIMMsgKeyLocalMsgFeature
字段,kNIMMsgKeyLocalReceiveMsgContent
,而ParseIMMessage
解析的是kNIMMsgKeyLocalReceiveMsgContent
所承载的实际消息内容。
- API 原型
static bool ParseReceiveMessage(const std::string& json_msg, IMMessage& msg);
- 参数说明
参数 | 说明 |
---|---|
json_msg | 传入消息内容的json 无格式化字串 |
msg | 输出消息内容,详见IMMessage |
3. 解析图片消息附件
- API 原型
static bool ParseImageMessageAttach(const IMMessage& msg, IMImage& image);
- 参数说明
参数 | 说明 |
---|---|
msg | 消息内容,详见IMMessage |
image | 输出图片附件内容,详见IMImage |
4. 解析文件消息附件
- API 原型
static bool ParseFileMessageAttach(const IMMessage& msg, IMFile& file);
- 参数说明
参数 | 说明 |
---|---|
msg | 消息内容,详见IMMessage |
file | 输出图片附件内容,详见IMFile |
5. 解析语音消息附件
- API 原型
static bool ParseAudioMessageAttach(const IMMessage& msg, IMAudio& audio);
- 参数说明
参数 | 说明 |
---|---|
msg | 消息内容,详见IMMessage |
audio | 输出图片附件内容,详见IMAudio |
6. 解析视频消息附件
- API 原型
static bool ParseVideoMessageAttach(const IMMessage& msg, IMVideo& video);
- 参数说明
参数 | 说明 |
---|---|
msg | 消息内容,详见IMMessage |
video | 输出图片附件内容,详见IMVideo |
7. 解析地理位置消息附件
- API 原型
static bool ParseLocationMessageAttach(const IMMessage& msg, IMLocation& location);
- 参数说明
参数 | 说明 |
---|---|
msg | 消息内容,详见IMMessage |
location | 输出图片附件内容,详见IMLocation |
在线消息接收
建议注册全局回调,SDK只存储一个cb
,注册多次回调会导致覆盖,以最后一次注册的回调为准。
- API 原型
static void RegReceiveCb(const ReceiveMsgCallback& cb, const std::string& json_extension = "");
- 参数说明
参数 | 说明 |
---|---|
cb | 异步通知回调 |
json_extension | 扩展字段,预留 |
- 示例
//监听事件
nim::Talk::RegReceiveCb([&](const IMMessage& msg) {
//for test;
switch (msg.type_)
{
case kNIMMessageTypeFile:
{
IMFile file;
if (nim::Talk::ParseFileMessageAttach(msg, file))
{
...
}
}
break;
case kNIMMessageTypeImage:
{
IMImage img;
if (nim::Talk::ParseImageMessageAttach(msg, img))
{
...
}
}
break;
case kNIMMessageTypeAudio:
{
IMAudio audio;
if (nim::Talk::ParseAudioMessageAttach(msg, audio))
{
...
}
}
break;
case kNIMMessageTypeVideo:
{
IMVideo video;
if (nim::Talk::ParseVideoMessageAttach(msg, video))
{
...
}
}
break;
case kNIMMessageTypeLocation:
{
IMLocation location;
if (nim::Talk::ParseLocationMessageAttach(msg, location))
{
...
}
}
break;
default:
{
std::string attach = msg.attach_;
if (!attach.empty())
{
...
}
}
break;
}
});
//取消监听
nim::Talk::RegReceiveCb(nullptr);
离线同步漫游消息接收
接收批量消息,如离线,漫游,同步的批量消息。如果在注册了接收消息回调的同时也注册了该批量接口,当有批量消息时,会改走这个接口通知应用层,例如登录后接收到的离线消息等,必须在登录之前注册事件监听。
- API 原型
public static void RegReceiveBatchMessagesCb(ReceiveBatchMesaagesDelegate cb)
- 参数说明
参数 | 说明 |
---|---|
cb | 批量消息的回调 |
- 示例
//监听事件
nim::Talk::RegReceiveMessagesCb([&](const std::list<IMMessage>& msgs) {
for (auto msg : msgs)
{
...
}
});
//取消监听
nim::Talk::RegReceiveMessagesCb(nullptr);
过滤群通知消息
注册接收群通知是否需要过滤的回调。如果在此回调中返回true,则SDK认为此通知已被处理,SDK将不再通过接收消息通道下发,也不会保存本地数据库。
- API 原型
public static void RegTeamNotificationFilterCb(TeamNotificationFilterDelegate action);
- 参数说明
参数 | 说明 |
---|---|
action | 过滤群通知消息的回调 |
- 示例
bool filterTeamNotify = true;
//监听事件
nim::Talk::RegTeamNotificationFilter([&](const IMMessage& msg)->bool
{
//如果设置处理过滤了通知消息,返回true,否则返回false;
if (filterTeamNotify)
{
...
return true;
}
return false;
});
//取消监听
NIM.TalkAPI.RegTeamNotificationFilterCb(null);
转发消息
用户通过构造API获取新的消息对象,然后调用发送消息接口。
- API 原型
static std::string CreateRetweetMessage(const std::string& src_msg_json, const std::string& client_msg_id, const NIMSessionType retweet_to_session_type, const std::string& retweet_to_session_id, const MessageSetting& msg_setting, int64_t timetag = 0);
- 参数说明
参数 | 说明 |
---|---|
src_msg_json | 接收到的消息内容,内容同IMMessage |
client_msg_id | 生成的新的消息uuid |
retweet_to_session_id | 转发的对方id,个人账号或者群id |
retweet_to_session_type | 会话类型,0:点对点消息 1: 群消息 |
msg_setting | 消息设置,详见消息设置说明 |
timetag | 当前的时间戳(毫秒) |
- 示例
//假设srcMsg已经发送或者收到的消息内容。
std:string srcMsg;
//按需进行消息设置
MessageSetting msgSetting;
msgSettting.ServerSaveHistory = true;
...
//通过srcMsg生成一个新的消息。
int64_t timeNow = 1520500638234;//当前UNIX时间戳 毫秒
string sessionid = "1222222";
string clientMsgID = "uuid2";//生成新的唯一uuid;
NIMSessionType sessionType = kNIMSessionTypeTeam;
std::string newMsg = nim::Talk::CreateRetweetMessage(srcMsg,clientMsgID,sessionType,sessionid,msgSettting,timeNow);
nim::Talk::SendMsg(newMsg,null);
消息撤回
用户通过发送消息发的消息或者群主、管理员可以通过该接口执行撤回操作(不支持聊天室消息),撤回操作一般有时限限制(该限制为全局的APP设置),超过限制返回508。 开发者通过注册撤回消息通知回调,接收其他端的撤回消息的通知,收到通知后SDK会标记主动在消息历史中标记该条消息为删除状态,同时开发者根据自身需求,删除界面上显示的消息,甚至插入一条提示,IM Demo有开发示例。
RecallNotification
参数说明
类型 | 参数 | 说明 |
---|---|---|
NIMSessionType | session_type_ | 会话类型 0:点对点消息 1 :群消息 |
string | from_id_ | 消息发送方ID |
string | to_id_ | 消息接收方ID |
string | msg_id_ | 消息唯一id |
string | notify_ | 自定义通知文案 |
int64_t | notify_timetag_ | 撤回操作的时间戳(毫秒) |
NIMMessageFeature | notify_feature_ | 撤回消息的类型,详见NIMMessageFeature |
bool | msglog_exist_ | 撤回的消息本地是否存在,比如对方离线时发一条消息又撤回,对方上线收到离线撤回通知该tag为false |
int64_t | msglog_timetag_ | 要撤回的消息的时间戳(毫秒)(毫秒) |
string | from_nick_ | 要撤回消息的发送者昵称 |
主动撤回消息
撤回已发送成功的消息,此功能依赖本地历史记录,需要通过消息id查询本地消息记录,如果无法从本地找到消息记录,将无法撤回。
- API 原型
static void RecallMsg(const IMMessage& msg, const std::string& notify, const RecallMsgsCallback& cb, const std::string& json_extension = "");
- 参数说明
参数 | 说明 |
---|---|
msg | 需要撤回的消息 |
notify | 自定义通知 |
cb | 撤回消息的回调通知 |
json_extension | 通知扩展,预留 |
- 示例
//自己组装,目前是通过msgId撤回,
IMMessage assembleMsg;
assembleMsg.client_msg_id_ = "撤回消息的uuid"; //目前只用到了消息id;
nim::Talk::RecallMsg(assembleMsg,"这是一条撤回通知", [&](NIMResCode code, const std::list<RecallMsgNotify>& notifications) {
...
});
消息撤回的通知
通知用户消息已被撤回,该通知支持离线。
- API 原型
static void RegRecallMsgsCallback(const RecallMsgsCallback& cb, const std::string& json_extension = "");
- 参数说明
参数 | 说明 |
---|---|
cb | 消息撤回的通知的回调 |
json_extension | 通知扩展,预留 |
- 示例
//监听事件
nim::Talk::RegRecallMsgsCallback([&](const NIMResCode code, const std::list<RecallMsgNotify>& notifications)
{
for (auto msg : notifications)
{
...
}
});
//取消监听
nim::Talk::RegRecallMsgsCallback(nullptr);
已读回执
网易云信提供点对点消息的已读回执。注意:此功能仅对 P2P 消息中有效。
在会话界面中调用发送已读回执的接口并传入最后一条消息,即表示这之前的消息都已读,对端将收到此回执。
发送消息已读回执的一般场景:
1. 进入 P2P 聊天界面(如果没有收到新的消息,反复进入调用发送已读回执接口, SDK 会自动过滤,只会发送一次给网易云信服务器)。
2. 处于聊天界面中,收到当前会话新消息时。
发送已读回执
- API 原型
static void SendReceiptAsync(const std::string& json_msg, const MessageStatusChangedCallback& cb);
- 参数说明
参数 | 说明 |
---|---|
json_msg | 收到的消息内容 |
cb | 发送消息已读会之后,消息状态变化的回调通知 |
- 示例
//假设 msg为需要发送已读回执的消息。
nim::MsgLog::SendReceiptAsync(msg, [&](const nim::MessageStatusChangedResult& result) {
for (auto r : result.results_)
{
...
}
});
监听已读回执通知
已读回执也是消息状态的变化,可查阅全局消息状态变更通知
监听全员广播通知
接收全员广播通知。分单个通知和批量全员广播通知,一般而言,批量通知是登陆时下发的离线广播、同步广播、漫游广播通知等。
BroadcastMessage
广播通知参数说明
类型 | 参数 | 说明 |
---|---|---|
int64_t | id_ | 通知消息id |
string | from_id_ | 发送者账号,可能为空 |
int64_t | time_ | 通知消息UNIX时间戳,毫秒 |
string | body_ | 通知内容 |
1. 单条全员广播通知 接收广播消息回调 , 建议全局注册,统一接受回调后分发消息到具体的会话。
- API 原型
static void RegReceiveBroadcastMsgCb(const ReceiveBroadcastMsgCallback& cb, const std::string& json_extension = "");
- 参数说明
参数 | 说明 |
---|---|
cb | 通知的回调 |
json_extension | 扩展字段,预留 |
- 示例
//监听事件
nim::Talk::RegReceiveBroadcastMsgCb([&](const BroadcastMessage& msg)
{
//处理广播通知
...
});
//取消监听
nim::Talk::RegReceiveBroadcastMsgCb(nullptr);
2. 批量全员广播通知
接收批量广播消息回调。如果在注册了接收消息回调的同时也注册了该批量接口,当有批量消息时,会改走这个接口通知应用层,例如登录后接收到的离线消息等。
- API 原型
static void RegReceiveBroadcastMsgsCb(const ReceiveBroadcastMsgsCallback& cb, const std::string& json_extension = "");
- 参数说明
参数 | 说明 |
---|---|
cb | 批量消息的回调 |
json_extension | 扩展字段,预留 |
- 示例
//监听事件
nim::Talk::RegReceiveBroadcastMsgsCb([&](const std::list<nim::BroadcastMessage> msgs)
{
//处理广播通知
for (auto msg : msgs)
{
...
}
});
//取消监听
nim::Talk::RegReceiveBroadcastMsgsCb(nullptr);
从消息附件中获取本地路径
从消息的中获取附件(图片、语音、视频等)的本地路径。如果预下载的是缩略图,且没下载过原图,此获得的路径文件可能不存在,需要开发者调用nim::NOS::FetchMedia
去下载。如果全局设置预加载的是缩略图,则开发者若想下载原图,在传入消息内容前,先将local_res_path_
字段设为空或者自定义的保存路径。
- API 原型
static std::string GetAttachmentPathFromMsg(const IMMessage& msg);
- 参数说明
参数 | 说明 |
---|---|
msg | 所要获取的消息内容 |
- 示例
//假设msg为需要获取的消息
std::string filePath = nim::Talk::GetAttachmentPathFromMsg(msg);
//下载原图
msg.local_res_path_ = ""; //此处置空 或者设置为自定义的保存路径;
nim::Talk::FetchMedia(msg,[&](NIMResCode res_code, const std::string& file_path, const std::string& call_id, const std::string& res_id){
//通知完成
...
},[&](int64_t completed_size, int64_t file_size){
//通知进度
...
});
获取图片缩略图
网易云信 IM SDK 目前默认收到图片消息后会提前下载原图缓存到本地,如果开发者想控制下载图片的质量,可以通过初始化SDK时设置kNIMPreloadImageQuality
来控制图片质量,设置kNIMPreloadImageResize
来控制图片长宽, IM Demo开发范例中默认下载原图,所以开发者如果想基于IM Demo工程源码开发,需要在图片预览环节或者其他需要显示原图的地方自行下载原图。
以下但不限于以下场景下开发者可以自行下载缩略图:
- 对图片尺寸有特殊要求
- 聊天室接收图片消息
目前SDK提供两种获取缩略图方案:
-
基于修改图片质量
当用户收到图片消息时,附件
kNIMMsgKeyAttach
(聊天室消息为kNIMChatRoomMsgKeyAttach
)内容解析出来会带有图片下载地址,通过拼接下载接口参数获取指定质量的图片: http(s)://?imageView&quality=N;http(s)://xxx为图片下载地址;N为图片质量,范围为0-100。 -
基于长宽对图片进行 内缩略 (原图等比例缩略,缩略后的图片“一边等于请求长度,另一边小于等于请求长度”)
当用户收到图片消息时,附件kNIMMsgKeyAttach(聊天室消息为kNIMChatRoomMsgKeyAttach)内容解析出来会带有图片下载地址,通过拼接下载接口参数获取缩略图: http(s)://xxx?imageView&thumbnail=XxY;http(s)://xxx为图片下载地址;X为宽度,Y为高度,中间为小写x,宽度和高度取值范围0-4096。
几种参数变化: 1、XxY:普通缩略(内缩略) 2、Xx0:限定宽度,高度自适应(内缩略) 3、0xY:限定高度,宽度自适应(内缩略)
目前IM Demo工程在消息显示图片的时候对图片进行了压缩处理,开发者可以参考bubble_image.cpp