创建消息
创建文本消息
接口
chat.createTextMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话)或TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
receiverList | Array | undefined | - | 定向接收消息的群成员列表(社群和直播群不支持) |
isSupportExtension | Boolean | false | 是否支持消息扩展,true 支持 false 不支持(需要您购买旗舰版套餐) |
payload 的描述如下:
参数 | 类型 | 描述 |
text | String | 消息文本内容 |
返回值
示例
// 发送文本消息,Web 端与小程序端相同// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createTextMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊。如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {text: 'Hello world!'},// 如果您发消息需要已读回执,需购买旗舰版套餐,并且创建消息时将 needReadReceipt 设置为 trueneedReadReceipt: true// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
// 发送群定向消息// 注意:群定向消息不计入会话未读,receiverList 最大支持50个接收者。let message = chat.createTextMessage({to: 'test',conversationType: TencentCloudChat.TYPES.CONV_GROUP,payload: {text: 'Hello world!'},// 如果您需要发群定向消息,需购买旗舰版套餐,并且创建消息时通过 receiverList 指定消息接收者receiverList: ['user0', 'user1']});// 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建@消息
注意
此接口仅用于群聊,且社群和社群下的话题不支持 @ALL。
创建群 @ 消息不支持指定消息接收者。
接口
chat.createTextAtMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话)或TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
text | String | 消息文本内容 |
atUserList | Array | 需要 @ 的用户列表,如果需要 @ALL,请传入 TencentCloudChat.TYPES.MSG_AT_ALL 。 举个例子,假设该条文本消息希望 @ 提醒 denny 和 lucy 两个用户,同时又希望 @ 所有人,atUserList 传 ['denny', 'lucy', TencentCloudChat.TYPES.MSG_AT_ALL] |
返回值
示例
// 发送文本消息,Web 端与小程序端相同// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createTextAtMessage({to: 'group1',conversationType: TencentCloudChat.TYPES.CONV_GROUP,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {text: '@denny @lucy @所有人 今晚聚餐,收到的请回复1',// 'denny' 'lucy' 都是 userID,而非昵称atUserList: ['denny', 'lucy', TencentCloudChat.TYPES.MSG_AT_ALL]},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建图片消息
注意:
1. 在开通 云端审核 功能后,如果您发送的图片消息内容不合规,云端审核超时后 SDK 会触发 MESSAGE_MODIFIED 事件,回调的 message 对象 hasRiskContent 值为 true。
2. v3.3.0起,支持自定义消息审核策略,请参见 customModerationConfigurationID 参数的描述。
3. 支持的图片类型:
jpg
、jpeg
、gif
、png
、bmp
、image
、webp
。接口
chat.createImageMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下表所示:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息的接收方 |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话) 或 TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
onProgress | function | - | 获取上传进度的回调函数 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
customModerationConfigurationID | String | undefined | | 消息自定义审核配置 ID(v3.3.0起支持) 在开通【云端审核】功能后,您可以请前往 控制台 > 云端审核 > 审核配置 > 自定义配置 > 添加自定义配置获取配置 ID。 自定义审核配置流程请参见 云端审核功能。 该字段需要发消息前设置,仅用于控制发消息时的消息审核策略,其值不会存储在漫游和本地。 |
payload 的描述如下:
参数 | 类型 | 描述 |
file | HTMLInputElement | Object | File | 用于选择图片的 DOM 节点(Web)或者 File 对象(Web)或者微信小程序 wx.chooseImage 接口的 success 回调参数。SDK 会读取其中的数据并上传图片 |
返回值
示例
// Web 端发送图片消息示例1 - 传入 DOM 节点// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createImageMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {file: document.getElementById('imagePicker'),},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
// Web 端发送图片消息示例2- 传入 File 对象// 先在页面上添加一个 id 为 "testPasteInput" 的消息输入框// 如 <input type="text" id="testPasteInput" placeholder="截图后粘贴到输入框中" size="30" />document.getElementById('testPasteInput').addEventListener('paste', function(e) {let clipboardData = e.clipboardData;let file;let fileCopy;if (clipboardData && clipboardData.files && clipboardData.files.length > 0) {file = clipboardData.files[0];// 图片消息发送成功后,file 指向的内容可能被浏览器清空,如果接入侧有额外的渲染需求,可以提前复制一份数据fileCopy = file.slice();}if (typeof file === 'undefined') {console.warn('file 是 undefined,请检查代码或浏览器兼容性!');return;}// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createImageMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: {file: file},onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});});
// 小程序端发送图片// 1. 选择图片wx.chooseImage({sourceType: ['album'], // 从相册选择count: 1, // 只选一张,目前 SDK 不支持一次发送多张图片success: function (res) {// 2. 创建消息实例,接口返回的实例可以上屏let message = chat.createImageMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: { file: res },onProgress: function(event) { console.log('file uploading:', event) }});// 3. 发送图片let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}})
// uni-app 发送图片// 微信小程序从基础库 2.21.0 开始, wx.chooseImage 停止维护,请使用 uni.chooseMedia 代替// 1. 选择图片uni.chooseMedia({count: 1,mediaType: ['image'], // 图片sizeType: ['original', 'compressed'], // 可以指定是原图还是压缩图,默认二者都有sourceType: ['album'], // 从相册选择success: function(res) {let message = chat.createImageMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: { file: res },onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}});
创建音频消息
注意:
在开通 云端审核 功能后,如果您发送的音频消息内容不合规,云端异步审核后 SDK 会触发 MESSAGE_MODIFIED 事件,回调的 message 对象 hasRiskContent 值为 true。
接口
chat.createAudioMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息的接收方 |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话) 或 TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
file | Object | 录音后得到的文件信息 |
返回值
示例
// 示例:使用微信官方的 RecorderManager 进行录音// 参考 https://developers.weixin.qq.com/minigame/dev/api/media/recorder/RecorderManager.start.html// 1. 获取全局唯一的录音管理器 RecorderManagerconst recorderManager = wx.getRecorderManager();// 录音部分参数const recordOptions = {duration: 60000, // 录音的时长,单位 ms,最大值 600000(10 分钟)sampleRate: 44100, // 采样率numberOfChannels: 1, // 录音通道数encodeBitRate: 192000, // 编码码率format: 'aac' // 音频格式,选择此格式创建的音频消息,可以在即时通信 IM 全平台(Android、iOS、微信小程序和Web)互通};// 2.1 监听录音错误事件recorderManager.onError(function(errMsg) {console.warn('recorder error:', errMsg);});// 2.2 监听录音结束事件,录音结束后,调用 createAudioMessage 创建音频消息实例recorderManager.onStop(function(res) {console.log('recorder stop', res);// 4. 创建消息实例,接口返回的实例可以上屏const message = chat.createAudioMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {file: res},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 5. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});});// 3. 开始录音recorderManager.start(recordOptions);
// 在 Web 端创建语音消息并发送// 示例:使用第三方库 js-audio-recorder 录制音频// 1. 开始录制let recorder = new Recorder({// 采样位数,支持 8 或 16,默认是16sampleBits: 16,// 采样率,支持 11025、16000、22050、24000、44100、48000,根据浏览器默认值,我的chrome是48000sampleRate: 16000,// 声道,支持 1 或 2, 默认是1numChannels: 1,});let startTs;recorder.start().then(() => {// 开始录音,记录起始时间戳startTs = Date.now();}, (error) => {// 出错了console.log(`${error.name} : ${error.message}`);});// 2. 结束录制recorder.stop();// 3. 计算录音时长,获取 WAV 数据let duration = Date.now() - startTs; // 单位:mslet wavBlob = recorder.getWAVBlob();// 4. blob 数据转成 File 对象let audioFile = new File([wavBlob], 'hello.wav', { type: 'wav' });audioFile.duration = duration;// 5. 创建音频消息let message = chat.createAudioMessage({to: 'user1',conversationType: 'C2C',payload: {file: audioFile}});// 6. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建视频消息
注意:
1. 在开通 云端审核 功能后,如果您发送的视频消息内容不合规,云端异步审核后 SDK 会触发 MESSAGE_MODIFIED 事件,回调的 message 对象 hasRiskContent 值为 true。
2. v3.3.0起,支持自定义消息审核策略,请参见 customModerationConfigurationID 参数的描述。
3. 支持的视频类型:
mp4
、 quicktime
、 mov
。接口
chat.createVideoMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息的接收方 |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话)或 TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
customModerationConfigurationID | String | undefined | |
payload 的描述如下:
参数 | 类型 | 描述 |
file | HTMLInputElement | File | Object | 自定义消息的数据字段 |
返回值
示例
// 小程序端发送视频消息示例:// 接口详情请查阅 https://developers.weixin.qq.com/miniprogram/dev/api/media/video/wx.chooseVideo.html// 1. 调用小程序接口选择视频wx.chooseVideo({sourceType: ['album', 'camera'], // 来源相册或者拍摄maxDuration: 60, // 设置最长时间60scamera: 'back', // 后置摄像头success (res) {// 2. 创建消息实例,接口返回的实例可以上屏let message = chat.createVideoMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {file: res},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'onProgress: function(event) { console.log('file uploading:', event) }})// 3. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}})
// web 端发送视频消息示例// 1. 获取视频:传入 DOM 节点// 2. 创建消息实例const message = chat.createVideoMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: {file: document.getElementById('videoPicker') // 或者用event.target},onProgress: function(event) { console.log('file uploading:', event) }});// 3. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
// uni-app 发送视频// 1. 选择视频uni.chooseVideo({count: 1,sourceType: ['camera', 'album'], // album 从相册选视频,camera 使用相机拍摄,默认为:['album', 'camera']maxDuration: 60, // 设置最长时间60scamera: 'back', // 后置摄像头success: function(res) {let message = chat.createVideoMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: { file: res },onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}})
创建自定义消息
接口
chat.createCustomMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C (端到端会话)或 TencentCloudChat.TYPES.CONV_GROUP (群组会话) |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
data | String | 自定义消息的数据字段 |
description | String | 自定义消息的说明字段 |
extension | String | 自定义消息的扩展字段 |
返回值
示例
// 示例:利用自定义消息实现投骰子功能// 1. 定义随机函数function random(min, max) {return Math.floor(Math.random() * (max - min + 1) + min);}// 2. 创建消息实例,接口返回的实例可以上屏let message = chat.createCustomMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_HIGH,payload: {data: 'dice', // 用于标识该消息是骰子类型消息description: String(random(1,6)), // 获取骰子点数extension: ''}});// 3. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建表情消息
接口
chat.createFaceMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C 或 TencentCloudChat.TYPES.CONV_GROUP |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
index | Number | 表情索引,用户自定义 |
data | String | 额外数据 |
返回值
示例
// 发送表情消息,Web端与小程序端相同。// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createFaceMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {index: 1, // Number 表情索引,用户自定义data: 'tt00' // String 额外数据},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建文件消息
接口
chat.createFileMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C 或 TencentCloudChat.TYPES.CONV_GROUP |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
onProgress | function | - | 获取上传进度的回调函数 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
file | HTMLInputElement | File | Object | 用于选择文件的 DOM 节点(Web)或者 File 对象(Web)或者 Object(uni.chooseFile 接口的 success 回调参数),SDK 会读取其中的数据并上传文件 |
返回值
示例
// Web 端发送文件消息示例1 - 传入 DOM 节点// 1. 创建文件消息实例,接口返回的实例可以上屏let message = chat.createFileMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {file: document.getElementById('filePicker'),},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
// Web 端发送文件消息示例2- 传入 File 对象// 先在页面上添加一个 id 为 "testPasteInput" 的消息输入框// 如 <input type="text" id="testPasteInput" placeholder="截图后粘贴到输入框中" size="30" />document.getElementById('testPasteInput').addEventListener('paste', function(e) {let clipboardData = e.clipboardData;let file;let fileCopy;if (clipboardData && clipboardData.files && clipboardData.files.length > 0) {file = clipboardData.files[0];// 图片消息发送成功后,file 指向的内容可能被浏览器清空,如果接入侧有额外的渲染需求,可以提前复制一份数据fileCopy = file.slice();}if (typeof file === 'undefined') {console.warn('file 是 undefined,请检查代码或浏览器兼容性!');return;}// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createFileMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: {file: file},onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});});
// uni-app 发送文件// 1. 选择文件uni.chooseFile({count: 1,extension:['.zip','.doc'],success: function(res) {let message = chat.createFileMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: { file: res },onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}});
// 手机端微信小程序或 QQ 小程序法发送文件// wx.chooseMessageFile 基础库 2.5.0 开始支持,低版本需做兼容处理// qq.chooseMessageFile 基础库 1.18.0 开始支持,低版本需做兼容处理// 1. 从客户端会话选择文件wx.chooseMessageFile({count: 1,type: 'all', // 从所有文件选择success: (res) => {const message = chat.createFileMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: { file: res },onProgress: function(event) { console.log('file uploading:', event) }});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});}});
创建地理位置消息
接口
chat.createLocationMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C 或 TencentCloudChat.TYPES.TYPES.CONV_GROUP |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
description | String | 地理位置描述信息 |
longitude | Number | 经度 |
latitude | Number | 纬度 |
返回值
示例
// 发送地理位置消息,Web 端与小程序端相同// 1. 创建消息实例,接口返回的实例可以上屏let message = chat.createLocationMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority: TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL,payload: {description: '深圳市深南大道10000号腾讯大厦',longitude: 113.941079, // 经度latitude: 22.546103 // 纬度}});// 2. 发送消息let promise = chat.sendMessage(message);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
创建合并消息
注意
不支持合并已发送失败的消息,如果消息列表内传入了已发送失败的消息,则创建消息接口会报错。
接口
chat.createMergerMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 默认值 | 描述 |
to | String | - | 消息接收方的 userID 或 groupID |
conversationType | String | - | 会话类型,取值 TencentCloudChat.TYPES.CONV_C2C 或 TencentCloudChat.TYPES.CONV_GROUP |
priority | String | TencentCloudChat.TYPES.MSG_PRIORITY_NORMAL | 消息优先级 |
payload | Object | - | 消息内容的容器 |
cloudCustomData | String | '' | 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到) |
payload 的描述如下:
参数 | 类型 | 描述 |
messageList | Array | 合并的消息列表 |
title | String | 合并的标题,例如:"大湾区前端人才中心的聊天记录" |
abstractList | String | 摘要列表,不同的消息类型可以设置不同的摘要信息,例如:文本消息可以设置为:sender: text,图片消息可以设置为:sender: [图片],文件消息可以设置为:sender: [文件] |
compatibleText | String | 兼容文本,低版本 SDK 如果不支持合并消息,默认会收到一条文本消息,文本消息的内容为 ${compatibleText},必填 |
返回值
示例
// 1. 将群聊消息转发到 c2c 会话// message1 message2 message3 是群聊消息let mergerMessage = chat.createMergerMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,payload: {messageList: [message1, message2, message3],title: '大湾区前端人才中心的聊天记录',abstractList: ['allen: 666', 'iris: [图片]', 'linda: [文件]'],compatibleText: '请升级IMSDK到v2.10.1或更高版本查看此消息'},// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 2. 发送消息let promise = chat.sendMessage(mergerMessage);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
下载合并消息
如果发送方发送的合并消息较大,SDK 会将此消息存储到云端,消息接收方查看消息时,需要先把消息从云端下载到本地。
接口
chat.downloadMergerMessage(message);
参数
参数 | 类型 | 描述 |
message | Message | 消息实例 |
返回值
Promise
示例
// downloadKey 存在说明收到的合并消息存储在云端,需要先下载if (message.type === TencentCloudChat.TYPES.MSG_MERGER && message.payload.downloadKey !== '') {let promise = chat.downloadMergerMessage(message);promise.then(function(imResponse) {// 下载成功后,SDK会更新 message.payload.messageList 等信息console.log(imResponse.data);}).catch(function(imError) {// 下载失败console.warn('downloadMergerMessage error:', imError);});}
逐条转发消息
注意
支持单条转发和逐条转发。
接口
chat.createForwardMessage(message);
参数
参数 | 类型 | 描述 |
message | Message | 消息实例 |
示例
let forwardMessage = chat.createForwardMessage({to: 'user1',conversationType: TencentCloudChat.TYPES.CONV_C2C,// 消息优先级,用于群聊// priority:TencentCloudChat.
TYPES.MSG_PRIORITY_NORMAL,payload: message, // 消息实例,已收到的或自己已发出的消息// 消息自定义数据(云端保存,会发送到对端,程序卸载重装后还能拉取到)// cloudCustomData: 'your cloud custom data'});// 2. 发送消息let promise = chat.sendMessage(forwardMessage);promise.then(function(imResponse) {// 发送成功console.log(imResponse);}).catch(function(imError) {// 发送失败console.warn('sendMessage error:', imError);});
发送消息
发送消息的接口,需先调用下列的创建消息实例的接口获取消息实例后,再调用该接口发送消息实例。
创建文本消息
创建 @ 消息
创建图片消息
创建音频消息
创建视频消息
创建自定义消息
创建表情消息
创建文件消息
创建地理位置消息
创建合并消息
创建转发消息
注意
调用该接口发送消息实例,需要 sdk 处于 ready 状态,否则将无法发送消息实例。sdk 状态,可通过监听以下事件得到:
TencentCloudChat.EVENT.SDK_READY
- sdk 处于 ready 状态时触发
TencentCloudChat.EVENT.SDK_NOT_READY
- sdk 处于 not ready 状态时触发。接收推送的单聊、群聊、群提示、群系统通知的新消息,需监听事件 TencentCloudChat.EVENT.MESSAGE_RECEIVED。
本实例发送的消息,不会触发事件 TencentCloudChat.EVENT.MESSAGE_RECEIVED。同账号从其他端(或通过 REST API)发送的消息,会触发事件 TencentCloudChat.EVENT.MESSAGE_RECEIVED。
离线推送仅适用于终端(Android 或 iOS),Web 和 微信小程序不支持。
onlineUserOnly 和 messageControlInfo 不能同时使用。
支持普通社群和话题消息不计未读。
向系统会话发消息,SDK 将返回错误码 2106。
消息包体大小限制为12KB,且不可调整,超出将导致消息发送失败,错误码 80002。
启用好友关系检查后(IM 控制台 > 应用配置 > 功能配置 > 登录与消息 > 好友关系检查),IM 会在发起单聊时检查好友关系,仅允许好友之间发送单聊消息,陌生人发送单聊消息时 SDK 返回错误码 20009。
chat.sendMessage(options);
参数
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 描述 |
message | Message | 消息实例 |
options | Object | 消息发送选项(消息内容的容器),选填 |
options 的描述如下:
参数 | 类型 | 描述 |
onlineUserOnly | Boolean | 消息是否仅发送给在线用户的标识,默认值为 false;设置为 true,则消息既不存漫游,也不会计入未读,也不会离线推送给接收方。适合用于发送广播通知等不重要的提示消息场景。在 AVChatRoom 发送消息不支持此选项 |
offlinePushInfo | Object | |
messageControlInfo | Object | 消息控制配置 |
offlinePushInfo 的描述如下:
参数 | 类型 | 描述 |
disablePush | Boolean | true 关闭离线推送;false 开启离线推送(默认) |
disableVoipPush | Boolean | true 关闭 voip 推送(默认) false 开启 voip 推送(开启 voip 推送需要同时开启离线推送) |
title | String | 离线推送标题,该字段为 iOS 和 Android 共用 |
description | String | 离线推送内容,该字段会覆盖消息实例的离线推送展示文本。若发送的是自定义消息,该 description 字段会覆盖 message.payload.description。如果 description 和 message.payload.description 字段都不填,接收方将收不到该自定义消息的离线推送 |
extension | String | 离线推送透传内容 |
ignoreIOSBadge | Boolean | 离线推送忽略 badge 计数(仅对 iOS 生效),如果设置为 true,在 iOS 接收端,这条消息不会使 App 的应用图标未读计数增加 |
androidOPPOChannelID | String | 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID |
messageControlInfo 的描述如下:
参数 | 类型 | 描述 |
excludedFromUnreadCount | Boolean | true 消息不更新会话 unreadCount(消息存漫游),默认值 false |
excludedFromLastMessage | Boolean | true 消息不更新会话 lastMessage(消息存漫游),默认值 false |
excludedFromContentModeration | Boolean | 消息是否不过内容审核(包含本地审核和云端审核) 只有在开通本地审核或云端审核功能后,excludedFromContentModeration 设置才有效,设置为 true,消息不过内容审核,设置为 false 消息过内容审核。 云端审核开通流程请参见 云端审核 |
返回
Promise
示例
// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。// 离线推送的标题和内容使用默认值。// 离线推送的说明请参考 https://cloud.tencent.com/document/product/269/3604chat.sendMessage(message);
chat.sendMessage(message, {onlineUserOnly: true // 如果接收方不在线,则消息不存入漫游,且不会进行离线推送});
chat.sendMessage(message, {offlinePushInfo: {disablePush: true // 如果接收方不在线,则消息将存入漫游,但不进行离线推送}});
chat.sendMessage(message, {// 如果接收方不在线,则消息将存入漫游,且进行离线推送(在接收方 App 退后台或者进程被 kill 的情况下)。// 接入侧可自定义离线推送的标题及内容offlinePushInfo: {title: '', // 离线推送标题description: '', // 离线推送内容androidOPPOChannelID: '' // 离线推送设置 OPPO 手机 8.0 系统及以上的渠道 ID}});
chat.sendMessage(message, {messageControlInfo: {excludedFromUnreadCount: true, // 消息不更新会话 unreadCount(消息存漫游)excludedFromLastMessage: true // 消息不更新会话 lastMessage(消息存漫游)}});
// 消息不过内容审核chat.sendMessage(message, {messageControlInfo: {excludedFromContentModeration: true,}});
接口限制
功能特性 | 限制项 | 限制说明 |
单聊/群聊/公众号消息 | 内容长度 | 单聊、群聊消息,单条消息最大长度限制为 12K。 |
| 发送频率 | 单聊消息:客户端发送单聊消息无限制;REST API 发送有频率限制,可查看相应接口的文档。 群聊消息:每个群限 40 条/秒(针对所有群类型、所有平台接口)。不同群内发消息,限频互不影响。 |
| 接收频率 | 单聊和群聊均无限制。 |
| 单个文件大小 | 发送文件消息时,SDK 最大支持发送单个文件大小为 100MB。 |
说明:
消息数量超过限制后,后台优先下发优先级相对较高的消息,同等优先级的消息随机排序。如果同一秒内高优先级消息总数超过 40 条/秒,高优先级消息也会被抛弃。
REST API 发送群组消息接口调用限频默认为 200次/秒,与上述 “每个群发送消息限 40 条/秒” 是不同概念,请区分开。