本文主要介绍如何快速将腾讯云即时通信 IM SDK 集成到您的小程序、uni-app 项目中。
V3 用户升级提示:
如果您需要从 V3 SDK(
@tencentcloud/chat) 升级到 V4(@tencentcloud/lite-chat),请您务必参见我们的 V3 升级 V4 指南。如果您需要继续使用 V3 SDK,请参考 集成 SDK。
平台兼容性
微信小程序环境: 兼容原生微信小程序以及 uni-app 打包的微信小程序。
uni-app 打包的 App。
小游戏:抖音小游戏,微信小游戏。
版本介绍
lite-chat | 大小 | 功能概述 |
精简版 | 200 KB | 初始化,事件监听。 登录登出。 支持文本消息收发。 支持自定义消息收发(可自由定制发送内容)。 支持用户资料和用户状态。 |
标准版(默认) | 516 KB | 包含精简版全部功能外 支持获取历史消息,消息操作,合并转发,已读回执,消息扩展等功能。 支持图片消息,视频消息,语音消息,文件消息收发功能。 支持云端消息(Message)搜索、用户(User)搜索、群组(Group)搜索、群成员搜索等功能。 支持会话列表,会话资料,会话操作等功能。 支持群组管理,群成员管理等功能。 支持社群。 支持直播群。 |
完整版 | 609 KB | 包含标准版全部功能外 支持黑名单,好友管理,好友分组等功能。 支持关注和粉丝功能。 支持会话分组。 支持话题。 |
npm 集成
在您的项目中使用 npm 安装相应依赖。
npm install @tencentcloud/lite-chat
// 若同步依赖过程中出现问题,请切换 npm 源后再次重试npm config set registry http://r.cnpmjs.org/
引入 SDK
V4 SDK 允许您根据应用所需功能,按需引入精简版、标准版或完整版,以优化代码体积。
// 标准版 (默认引用,推荐)import TencentCloudChat from '@tencentcloud/lite-chat';// 精简版 (只包含核心聊天和用户管理,体积最小)// import TencentCloudChat from '@tencentcloud/lite-chat/basic';// 完整版 (包含所有社交功能,如好友关系链等)// import TencentCloudChat from '@tencentcloud/lite-chat/professional';
初始化
初始化 SDK 需要执行以下步骤:
1. 准备 SDKAppID。
2. 调用
TencentCloudChat.create 初始化 SDK。3. 监听 SDK 事件。
下面我们将分步骤依次为您详细讲解。
1. 准备 SDKAppID
您必须拥有正确的 SDKAppID,才能进行初始化。
SDKAppID 是腾讯云 IM 服务区分客户账号的唯一标识。我们建议每一个独立的 App 都申请一个新的 SDKAppID。不同 SDKAppID 之间的消息是天然隔离的,不能互通。

2. 调用初始化接口
import TencentCloudChat from '@tencentcloud/lite-chat';let options = {SDKAppID = 0; // 接入时需要将0替换为您的即时通信 IM 应用的 SDKAppID};// 创建 SDK 实例,`TencentCloudChat.create()`方法对于同一个 `SDKAppID` 只会返回同一份实例let chat = TencentCloudChat.create(options); // SDK 实例通常用 chat 表示
参数 options 为 Object 类型,包含的属性值如下:
参数 | 类型 | 说明 |
SDKAppID | Number | 即时通信 IM 应用的 SDKAppID |
fileUploadProxy | String | undefined | 图片、视频、文件上传代理地址(小程序平台不支持使用 IP 地址) |
fileDownloadProxy | String | undefined | 图片、视频、文件下载代理地址(小程序平台不支持使用 IP 地址) |
3. 监听事件
事件名称 | 事件描述 |
SDK 进入 ready 状态时触发,接入侧监听此事件,然后可调用 SDK 发送消息等 API,使用 SDK 的各项功能。 | |
SDK 进入 not ready 状态时触发,此时接入侧将无法使用 SDK 发送消息等功能。 | |
用户被踢下线时触发。 | |
WebSocket 网络状态发生改变。 |
示例:
import TencentCloudChat from '@tencentcloud/lite-chat';let onSdkReady = function(event) {console.log('sdk ready');};chat.on(TencentCloudChat.EVENT.SDK_READY, onSdkReady);
小程序域名配置
在小程序中集成 SDK 时,需要配置相关的域名白名单,请在微信公众平台 > 开发 > 开发管理 > 开发设置 > 服务器域名中进行域名配置。
将以下域名添加到 socket 合法域名:
域名 | 说明 | 是否必须 |
wss://wss.im.tencent.cn | Web IM 业务域名 | 必须 |
wss://wssv6.im.qcloud.com | Web IM 业务域名(v3.4.9 起支持) | 必须 |
wss://${SDKAppID}w4c.my-imcloud.com | v3.4.6起,SDK 支持独立域名,可更好地保障服务稳定性。 例如您的 SDKAppID 是 1400xxxxxx,则独立域名为: wss://1400xxxxxxw4c.my-imcloud.com | 必须 |
wss://wss.tim.qq.com | Web IM 业务域名 | 必须 |
wss://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
将以下域名添加到 request 合法域名:
域名 | 说明 | 是否必须 |
https://web.sdk.qcloud.com | Web IM 业务域名 | 必须 |
https://boce-cdn.my-imcloud.com | Web IM 业务域名 | 必须 |
https://api.im.qcloud.com | Web IM 业务域名 | 必须 |
https://events.im.qcloud.com | Web IM 业务域名 | 必须 |
https://webim.tim.qq.com | Web IM 业务域名 | 必须 |
https://wss.im.qcloud.com | Web IM 业务域名 | 必须 |
https://wssv6.im.qcloud.com | Web IM 业务域名 | 必须 |
https://wss.tim.qq.com | Web IM 业务域名 | 必须 |
https://web.sdk.cloud.tencent.cn | Web IM 业务域名 | 必须 |
https://web.sdk.tencent.cn | Web IM 业务域名 | 必须 |
将以下域名添加到 uploadFile 合法域名:
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起,新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx,则 COS 独立域名为: https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件上传域名 | 必须 |
https://cn.imrich.qcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件上传域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件上传域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件上传域名 | 必须 |
将以下域名添加到 downloadFile 合法域名:
域名 | 说明 | 是否必须 |
https://${SDKAppID}-cn.rich.my-imcloud.com | 从 2024年9月10日起,新增应用默认分配 COS 独立域名。 例如您的 SDKAppID 是 1400xxxxxx,则 COS 独立域名为: https://1400xxxxxx-cn.rich.my-imcloud.com | 必须 |
https://cn.rich.my-imcloud.com | 文件下载域名 | 必须 |
https://cn.imrich.qcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.myqcloud.com | 文件下载域名 | 必须 |
https://cos.ap-shanghai.tencentcos.cn | 文件下载域名 | 必须 |
https://cos.ap-guangzhou.myqcloud.com | 文件下载域名 | 必须 |
相关资源
SDK 更新日志
SDK 接口文档