提交工单
咨询集成、功能及报价等问题
文档中心
体验 App
SDK 中心
API 中心
常见问题
代码市场
进入控制台
立即注册
登录
即时通讯 中文站 English
- 文档中心
- 即时通讯
- 快速开始
- 实现基本消息收发
实现基本消息收发
更新时间：2024-02-29 18:24
本文介绍如何使用 ZIM SDK 在微信小程序平台快速实现基本的单聊会话消息收发功能。
若开发者需要开发其他平台（如百度、支付宝或字节跳动）的小程序，可参考本文档，唯一区别仅为服务器域名配置，详情请参考 前提条件。
1 方案介绍
ZIM SDK 提供了如下接入方案：
)
在此方案中，您需要通过您自己的业务系统实现以下业务逻辑：
- 搭建客户端的用户管理逻辑，并下发用户 ID 用于客户端登录。
- 鉴权 Token，建议由您的业务后台自行实现，保证鉴权数据安全。
2 前提条件
在使用 ZIM SDK 前，请确保：
- 已在 ZEGO 控制台 创建项目，获取到了接入 ZIM SDK 服务所需的 AppID 和 ServerSecret。ZIM 服务权限不是默认开启的，使用前，请先在 ZEGO 控制台 自助开通 ZIM 服务（详情请参考 项目管理 - 即时通讯），若无法开通 ZIM 服务，请联系 ZEGO 技术支持开通。
- 已获取登录 SDK 所需的 Token，详情请参考 使用 Token 鉴权。
请在 微信公众平台 上进行 服务器域名配置。选择“小程序后台 > 开发 > 开发设置 > 服务器域名”菜单，按照协议分类，将以下
域名地址填写到指定的 “request 合法域名” 或 “socket 合法域名” 或 “uploadFile 合法域名” 或 “downloadFile 合法域名” 中。若开发者需要在其他平台（如百度、支付宝或字节跳动）运行示例源码或开发上述平台的小程序，请在对应平台配置服务器域名。
小程序服务器配置分类 域名 适用SDK版本 描述 socket 合法域名wss://webzim-sh2.zego.im1.2.0 ~ 2.1.5接入域名：ZEGO 服务器的 WebSocket 通信地址。wss://webzim-sh2-bak.zego.imwss://accesshub-wss.zego.im2.2.0 ~ 2.12.0wss://accesshub-wss.coolbcloud.com2.13.0 及以上wss://accesshub-wss.coolccloud.comwss://accesshub-wss.coolgcloud.comwss://accesshub-wss.coolhcloud.comwss://accesshub-wss.coolzcloud.comwss://accesshub-global.coolbcloud.comwss://accesshub-global.coolccloud.comwss://accesshub-global.coolgcloud.comwss://accesshub-global.coolhcloud.comwss://accesshub-global.coolzcloud.comwss://webzim-report.zego.im1.2.0 ~ 2.11.0数据上报：分析 SDK 数据。wss://weblogger-wss.zego.im2.12.0 及以上wss://weblogger-wss.coolbcloud.comwss://weblogger-wss.coolccloud.comwss://weblogger-wss.coolgcloud.comwss://weblogger-wss.coolhcloud.comwss://weblogger-wss.coolzcloud.comrequest 合法域名https://cloud-setting-api.zego.im1.2.0 ~ 2.1.5云控配置：动态修改 SDK 能力。https://cloud-setting-api.zegocloud.comhttps://webzim-detaillog.zego.im1.2.0 ~ 2.11.0日志上报：排查故障，定位问题。https://detaillog-global.zego.im2.12.0 及以上https://detaillog-global.coolbcloud.comhttps://detaillog-global.coolccloud.comhttps://detaillog-global.coolgcloud.comhttps://detaillog-global.coolhcloud.comhttps://detaillog-global.coolzcloud.comhttps://zego-zim-smsh.oss-cn-shanghai.aliyuncs.com2.2.0 ~ 2.11.0文件媒体消息：文件媒体消息的 URL。https://zego-zim-zimsh.oss-cn-shanghai.aliyuncs.comhttps://zimfile-sh2.zego.imhttps://access-zfpxy-global.zego.im2.12.0 及以上https://access-zfpxy-global.coolbcloud.comhttps://access-zfpxy-global.coolccloud.comhttps://access-zfpxy-global.coolgcloud.comhttps://access-zfpxy-global.coolhcloud.comhttps://access-zfpxy-global.coolzcloud.comuploadFile 合法域名https://webzim-detaillog.zego.im1.2.0 ~ 2.11.0日志上报：排查故障，定位问题。https://detaillog-global.zego.im2.12.0 及以上https://detaillog-global.coolbcloud.comhttps://detaillog-global.coolccloud.comhttps://detaillog-global.coolgcloud.comhttps://detaillog-global.coolhcloud.comhttps://detaillog-global.coolzcloud.comhttps://zego-zim-smsh.oss-cn-shanghai.aliyuncs.com2.2.0 ~ 2.11.0文件媒体消息：文件媒体消息的 URL。https://zego-zim-zimsh.oss-cn-shanghai.aliyuncs.comhttps://zimfile-sh2.zego.imhttps://access-zfpxy-global.zego.im2.12.0 及以上https://access-zfpxy-global.coolbcloud.comhttps://access-zfpxy-global.coolccloud.comhttps://access-zfpxy-global.coolgcloud.comhttps://access-zfpxy-global.coolhcloud.comhttps://access-zfpxy-global.coolzcloud.comdownloadFile 合法域名https://zego-zim-smsh.oss-cn-shanghai.aliyuncs.com2.2.0 ~ 2.11.0文件媒体消息：文件媒体消息的 URL。https://zego-zim-zimsh.oss-cn-shanghai.aliyuncs.comhttps://zimfile-sh2.zego.imhttps://access-zfpxy-global.zego.im2.12.0 及以上https://access-zfpxy-global.coolbcloud.comhttps://access-zfpxy-global.coolccloud.comhttps://access-zfpxy-global.coolgcloud.comhttps://access-zfpxy-global.coolhcloud.comhttps://access-zfpxy-global.coolzcloud.com
3 集成 SDK
3.1 （可选）新建项目
此步骤以如何创建新项目为例，如果是集成到已有项目，可忽略此步。
请参考 微信开放文档 - 开始 创建一个微信小程序。
3.2 导入 SDK
使用 npm 集成 SDK。
执行
npm i zego-zim-miniprogram命令安装依赖。- npm 下载包支持 typescript 语言(推荐)。
- 如果在 macOS 或 Linux 系统中执行 npm 命令失败，提示 “permission denied”，请在 npm 命令前加上 sudo 重新执行即可。
导入 SDK。
import { ZIM } from 'zego-zim-miniprogram';
4 实现基本收发消息
以下流程中，我们以客户端 A 和 B 的消息交互为例，实现 1v1 通信功能：
)
4.1 实现流程
请参考 跑通示例源码 获取源码。
1. 导入类文件
请参考 3.2 导入 SDK，选择 “方式二：从官网下载 SDK，手动集成”，导入 SDK 文件。
2. 创建 ZIM 实例
首先我们需要在项目中创建 ZIM 实例，一个实例对应的是一个用户，表示一个用户以客户端的身份登录系统。
例如，客户端 A、B 分别调用 create 接口，传入在 2 前提条件 中获取到的 AppID，创建了 A、B 的实例：
var appID = xxxx;
// 静态同步方法，创建 zim 实例，传入 AppID。
// create 方法仅第一次调用时会创建 ZIM 实例，后续调用会返回 null。
ZIM.create({ appID });
// 通过 getInstance 获取单实例，避免热更新导致 create 多次创建返回 null。
var zim = ZIM.getInstance();3. 监听回调事件
在客户端登录前，开发者可以通过调用 on 接口，自定义 ZIM 中的事件回调，接收到 SDK 异常、消息通知回调等的通知。
// 注册监听“运行时错误信息”的回调
zim.on('error', function (zim, errorInfo) {
console.log('error', errorInfo.code, errorInfo.message);
});
// 注册监听“网络连接状态变更”的回调
zim.on('connectionStateChanged', function (zim, { state, event, extendedData }) {
console.log(state, event, extendedData);
// 当长时间网络连接断开导致SDK内部登出时，需要重新登录
if (state == 0 && event != 0 && event != 4) {
zim.login(userID, config)
}
});
// 注册监听“收到单聊消息”的回调
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
console.log('receivePeerMessage', messageList, fromConversationID);
});
// 注册监听“令牌即将过期”的回调
zim.on('tokenWillExpire', function (zim, { second }) {
console.log('tokenWillExpire', second);
// 可以在这里调用 renewToken 接口来更新 token
// 新 token 生成可以参考上文
zim.renewToken(token)
.then(function({ token }){
// 更新成功
})
.catch(function(err){
// 更新失败
})
});详细的接口介绍，请参考 connectionStateChanged、receivePeerMessage、tokenWillExpire。
4. 登录 ZIM
- 申请 Token
登录 ZIM 需要用于验证身份的 Token，开发者可以直接 ZEGO 控制台 获取临时 Token（有效期为 24 小时）来使用，详情请参考 控制台 - 开发辅助。
临时 Token 仅供调试，正式上线前，请从开发者的业务服务器生成 Token，详情可参考 使用 Token 鉴权。
- 登录 ZIM
创建实例后，客户端 A 和 B 需要登录 ZIM，只有登录成功后才可以开始发送、接收消息、更新 Token 等。
客户端需要使用各自的用户信息和 Token 进行登录。调用 login 接口进行登录，传入 userID 和 ZIMLoginConfig 对象（必须包含 userName 和 Token），等待 Token 鉴权通过后才能登录成功。
- “userID”、“userName” 支持开发者自定义规则生成。建议开发者将 “userID” 设置为一个有意义的值，可将其与自己的业务账号系统进行关联。
- 如果 Token 过期，需要在 tokenWillExpire 即将过期回调接口中，调用 renewToken 接口，更新 Token 后才能正常使用 SDK。
// 登录时，需要开发者 按照 "使用 Token 鉴权" 文档生成 token 即可
// userID 最大 32 字节的字符串。仅支持数字，英文字符 和 '!', '#', '$', '%', '&', '(', ')', '+', '-', ':', ';', '<', '=', '.', '>', '?', '@', '[', ']', '^', '_', '{', '}', '|', '~'。
// userName 最大 256 字节的字符串，无特殊字符限制。
var userID = 'xxxx';
var config = {
userName: 'xxxx',
token = '',
};
zim.login(userID, config)
.then(function () {
// 登录成功
})
.catch(function (err) {
// 登录失败
});5. 发送消息
客户端 A 登录成功后，可以向客户端 B 发送消息。
目前 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 |
以下为发送单聊文本消息为例：客户端 A 可以调用 sendMessage 接口，传入客户端 B 的 userID、消息内容、消息类型 conversationType 等参数，即可发送一条文本消息到 B 的客户端。
- ZIMMessageSentResult 回调，判断消息是否发送成功。
- onMessageAttached 回调，在消息发送前，可以获得一个临时的 ZIMMessage，以便您添加一些业务处理逻辑。例如：在发送消息前，获取到该条消息的 ID 信息。开发者在发送“视频”等内容较大的消息时，可以在消息上传完成前，缓存该消息对象，直到收到 SDK 发送成功通知时，通过比较对象相同来实现发送前 Loading 的效果。
// 发送单聊 `Text` 信息
var toConversationID = ''; // 对方 userID
var conversationType = 0; // 会话类型，取值为 单聊：0，房间：1，群组：2
var config = {
priority: 1, // 设置消息优先级，取值为 低：1（默认），中：2，高：3
};
var messageTextObj = { type: 1, message: '文本消息内容', extendedData: '消息的扩展信息（可选）' };
var notification = {
onMessageAttached: function(message) {
// todo: Loading
}
}
zim.sendMessage(messageTextObj, toConversationID, conversationType, config, notification)
.then(function ({ message }) {
// 发送成功
})
.catch(function (err) {
// 发送失败
});6. 接收消息
客户端 B 登录 ZIM 后，将会收到在 on 回调中设置的 receivePeerMessage 监听接口，收到客户端 A 发送过来的消息。
// 注册监听“收到单聊消息”的回调
zim.on('receivePeerMessage', function (zim, { messageList, fromConversationID }) {
console.log('receivePeerMessage', messageList, fromConversationID);
});7. 退出登录
如果客户端需要退出登录，直接调用 logout 接口即可。
zim.logout();8. 销毁 ZIM 实例
如果不需要 ZIM 实例，可直接调用 destroy 接口，销毁实例。
调用 destroy 后会关闭 web socket 长链接，随后 30 秒内，已登录的用户还是处于在线状态；30 秒后，用户才会被 ZIM 后台判断为处于离线状态。如果想立即使当前用户处于离线状态，在调用 destroy 前请先调用 logout。
zim.destroy();4.2 API 时序图
通过以上的实现流程描述，API 接口调用时序图如下：
)
- 发送消息时，统一使用 sendMessage 接口，并根据消息类型传入对应的 conversationType 取值。
- 接收消息时：
- 单聊消息（Peer 类型），通过 receivePeerMessage 回调接收。
- 房间消息（Room 类型），通过 receiveRoomMessage 回调接收。
- 群组消息（Group 类型），通过 receiveGroupMessage 回调接收。
相关文档
- 如何获取 SDK 的日志信息？
- 如何设置消息的优先级更为合理？
- 什么时候使用自定义消息？
- 如何限制只有好友之间才能互发消息？
- 支持发送消息给自己吗？
- 如果您的小程序应用体积超过 2M，请参考 微信官方文档 - 分包加载 处理。
本篇目录
- 免费试用
- 电话咨询400 1006 604咨询客服微信扫码，24h在线
联系我们
文档反馈
