消息功能概述

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