www.ksyuwei.cnwww.ksyuwei.cn


www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

www.ksyuwei.cn

简介

腾讯是国内最早也是最大的即时通信开发商,QQ 和微信已经成为每个互联网用户必不可少的应用。顺应行业数字化转型的趋势,腾讯将高并发、高可靠的即时通信能力进行开放,您可以轻易地根据腾讯提供的 SDK 将即时通信功能集成到 App 中,来满足您业务的各种需求。
针对开发者的不同阶段需求及不同场景,即时通信 IM 团队提供了一系列解决方案,包括:Android、iOS、Windows、Web 的 SDK 组件、服务端集成 REST API 接口第三方回调接口 等。利用这些组件和能力,开发者可以简单快捷地构建高可靠且稳定的即时通信产品,随心所想,触达全球。

架构介绍

即时通信 IM 提供全球接入、单聊、群聊、消息推送、资料关系链托管、帐号鉴权等全方位解决方案,并提供完备的 App 接入、后台管理接口。

业务介绍

接入服务

接入服务为即时通信 IM 提供覆盖全球的高连通、高可靠、强安全的网络连接通道,自研多重最优寻址算法,具有全网调度能力,使用智能兼容技术穿透网关策略,长连接多路复用,传输层协议优化,通道加密等,让业务不必关心网络细节,即可安全地与业务后台实现简单可靠的通讯。

单聊

单聊即 1V1 聊天,提供包括文字、表情、地理位置、图片、语音、短视频及自定义消息的能力,可实现红包、对话机器人、消息回执、消息撤回等特殊功能,除此之外还提供离线消息、漫游消息等服务。详细可参阅 单聊消息 文档。

群聊

多人聊天服务,内置私有群、公开群、聊天室、音视频聊天室和在线成员广播大群五种群组形态,能够适应各种群组需求的场景。

  1. 私有群:适用于较为私密的聊天场景,群组资料不公开,只能通过邀请的方式加入,类似于微信群。

  2. 公开群:适用于公开群组,具有较为严格的管理机制、准入机制,类似于 QQ 群。

  3. 聊天室:群成员可以随意进出,组织较为松散,成员可以获取到本人进入聊天室前的聊天消息。

  4. 音视频聊天室:与聊天室类似,但群成员人数无上限,并且在 Web 端支持以游客身份接收聊天消息。

  5. 在线成员广播大群:成员人数无上限,在 Web 端支持以游客身份接收群消息,适用于向 App 全体在线成员推送消息的场景。

群组具备高度可定制性,包括自定义群组形态、自定义字段、自定义群组 ID、自定义事件回调等。App 可以根据自己的需求进行深度定制。详细可参阅 群组系统 文档。

注意:

音视频聊天室和在线成员广播大群的群成员人数没有上限,但如果预估群成员人数会超过1万人,请提前 联系腾讯云客服 或商务工作人员,申请服务资源。

资料关系链托管

提供资料、关系链托管的一套整体解决方案,可存储用户的资料(例如昵称、头像、自定义资料字段)、好友列表、黑名单等。即时通信 IM 资料关系链托管服务提供高达12份的备份服务,多机房异地部署,提高服务质量及容灾效果。详细可参阅 资料管理关系链管理 文档。

帐号鉴权

提供安全的非对称加密 ECDSA-SHA256 和哈希加密 HMAC-SHA256(推荐使用 HMAC-SHA256),开发者可直接使用 App 自有帐号快速集成即时通信 IM 服务,省去帐号映射的繁琐工作。通过简单的 SDK 集成,便捷的接口调用,完成用户帐号(UserID)与密码(UserSig)的鉴权。详细可参阅 登录鉴权 文档。

管理与监控

除了基础的即时通信功能之外,即时通信 IM 还提供了方便且易用的管理控制台。您可通过控制台完成应用创建,下载即时通信 IM SDK,查询应用配置信息完成应用联调,集成即时通信功能;同时,控制台还为您提供了后台消息下发、用户管理、群组管理和数据统计等功能。详细可参阅 控制台指南 文档。

高级功能

REST API

REST API 是一个 HTTP 管理接口,主要功能是为 App 后台提供一个后台管理入口。目前即时通信 IM 支持的 REST API 参阅 REST API 接口简介 文档。

除了 REST API,即时通信 IM 控制台也可实现简单的数据管理、单发/群发消息等功能,开发者可以在即时通信 IM 控制台进行数据管理、查看及测试。相比之下,REST API 接口较为原始,但可以提供功能更为强大的管理能力。

第三方回调

所谓 第三方回调,即即时通信 IM 会在某一事件发生之前或者之后,向 App 的后台服务器发送请求,App 后台可以据此进行必要的数据同步,或者干预事件的后续处理流程。
即时通信 IM 提供种类丰富的回调接口,目前回调功能完全免费。详细请参阅 回调命令列表 文档。

社交沟通

即时通信 IM 为应用于社交沟通提供能力支持,可实现单聊、群聊、弹幕等多种聊天模式,支持文字、图片、语音、短视频等多种消息类型,实时消息推送满足消息到达率的要求,并可支持实时音视频通话,有效提升用户粘性与活跃度。
示例场景:应用内聊天
推荐功能:消息管理、群组管理
客户案例:QQ、微信

互动直播

即时通信 IM 提供直播聊天室互动能力,聊天室无人数上限,支持亿级消息并发,轻松实现弹幕、 送礼和点赞等多消息类型,管理灵活,轻松打造良好的直播聊天互动体验;提供弹幕内容审核能力,保证您的直播免受恐爆、涉政、色情类文字信息的干扰。
示例场景:直播
推荐功能:聊天室
客户案例:斗鱼、NOW 直播

智能客服

即时通信 IM 满足商家与用户多场景沟通的需要,为客户提供专属客服服务,提升服务效率,与智能机器人相结合,可有效降低人力成本,沉淀客户价值。
示例场景:线上商城客服
推荐功能:在线客服
客户案例:阳光约车

物联网通信

即时通信 IM 提供人与物,物与物协同通信,携手共进引领 5G 通信时代潮流。
示例场景:智能设备与 App 端通信
推荐功能:语音、图片、视频消息
客户案例:优必选机器人

企业通讯

即时通信 IM 为企业客户提供解决方案,可覆盖桌面和移动端,设备无缝切换,实现企业沟通和办公的高效协同。
示例场景:企业内部通信
推荐功能:即时通信
客户案例:百世快递

系统消息通知

即时通信 IM 提供在线推送与离线推送服务,让系统消息精准到达。
示例场景:App 系统通知
推荐功能:消息推送
客户案例:货拉拉

游戏交流

即时通信 IM 可为游戏客户端提供大厅、小队、全服等多种聊天室类型,支持文字、语音、表情、短视频等多种消息类型,可通过自定义消息轻松实现游戏内道具赠送、交易等业务场景;同时,即时通信 IM 支持全球业务,我们已经在海外数十个国家部署专用服务器,为您的即时通信全球化提供强大动力。
示例场景:大厅群聊
推荐功能:多种群组类型、全球接入
客户案例:王者荣耀助手、腾讯游戏助手

平台支持

以下平台都支持互通,且能跨终端全平台服务。

平台SDK 及兼容性Demo源码UI 组件
Android兼容支持 JDK 1.6 和 Android SDK version 14 以上系统支持支持支持
iOS兼容 iOS 8.0 以上版本支持支持支持
Mac兼容 OS X 10.10 以上版本支持支持-
Windows包含C 、C++ ,兼容 Windows 7、Windows 8/8.1、Windows 10;全面支持32位和64位程序接入---
Web支持 IE 9+,Chrome 7+,FireFox 3.6+,Opera 12+ 和 Safari 6+支持--
小程序支持支持--

全球接入

功能类型功能描述
全球接入简介即时通信 IM 提供覆盖全球的高连通、高可靠、强安全的网络连接通道,自研多重最优寻址算法,具有全网调度能力,终端在海外登录时,IM SDK 会访问就近接入点或加速点
中国华南、华北、华东、香港等
海外亚洲:日本、韩国、新加坡、印度、泰国、马来西亚、越南、菲律宾、阿联酋
欧洲:德国、英国、法国、俄罗斯、意大利、挪威、西班牙
北美洲:美国、加拿大、墨西哥
南美洲:巴西
大洋洲:澳大利亚
非洲:南非

帐号功能

功能类型功能描述
帐号导入批量导入帐号
帐号禁用UserSig 失效
帐号删除批量删除帐号
用户在线状态管理在线和离线状态(以用户登录为前提)

多端登录

功能类型功能描述
单端登录仅允许 Windows、Web、Android 或 iOS 单端登录
双端登录(默认状态)允许 Windows、Android 或 iOS 单端登录,同时允许与 Web 端同时在线
三端登录允许 Android 或 iOS 单端登录,同时允许与 Windows 和 Web 端同时在线
多端同时在线允许 Windows、Web、Android 或 iOS 多端或全端同时在线登录
说明:

您可以登录 即时通信 IM 控制台,单击目标应用所在行的【应用配置】,在【功能配置】页配置多端登录。

消息类型

功能类型功能描述
文本消息消息内容是普通文本
图片消息消息内容为图片 URL 地址、尺寸、图片大小等信息
表情消息表情消息为开发者自定义
语音消息语音数据需要提供时长信息,以秒为单位
地理位置消息消息内容为地理位置标题、经度、纬度信息
文件消息消息内容为文件的 URL 地址、大小、格式等信息,格式不限,最大支持28M
短视频消息消息内容为语音文件的 URL 地址、时长、大小、格式等信息,最大支持28M
自定义消息开发者自定义的消息类型,例如红包消息、石头剪刀布等形式的消息
系统通知消息包含内置的系统通知消息和开发者自定义系统通知消息

消息功能

功能类型功能描述
消息下载App 管理员可以通过该接口获取 App 中某天某小时的所有单发或群组消息记录
离线消息用户登录后退到后台,当有用户给其发消息时,即时通信 IM 支持离线推送
漫游消息在新设备登录时,将服务器记录的漫游消息进行同步,默认保存7天,可付费延长
多端同步多终端消息同步,可同时收到消息
历史消息支持本地历史消息和云端历史消息
消息撤回撤回投递成功的消息,默认撤回 2 分钟内的消息。撤回操作仅支持单聊和群聊消息,不支持音视频聊天室(AVChatRoom)和在线成员广播大群(BChatRoom)的撤回
已读回执查看点对点会话中对方的已读未读状态
消息转发将消息转发给其他用户或群组
@功能群内 @ 消息与普通消息没有本质区别,仅是在被 @ 的人在收到消息时,需要在 UI 上做特殊处理
正在输入可以通过在线消息实现
离线推送支持苹果 APNs、小米推送、华为推送、魅族推送、OPPO 推送、vivo 推送
消息删除使用消息的 remove 方法可以在本地删除消息
红包功能红包消息与@消息类似,可以通过 TIMCustomElem 来实现

资料功能

功能类型功能描述
设置用户资料用户设置自己的昵称、验证方式、头像、性别、年龄、签名、位置等资料
获取用户资料用户查看自己、好友及陌生人资料
按字段获取用户资料按照特定字段获取用户资料
自定义用户资料最大20个自定义用户资料字段

关系链功能

功能类型功能描述
查找好友可通过用户帐号 ID 查找好友
申请添加好友要选择默认是否需要申请理由,目前是默认不需要
添加好友发送添加好友请求
删除好友成为好友后可以删除好友
获取所有好友获取所有好友,默认只拉取基本资料
同意/拒绝好友收到请求加好友请求的系统通知后,可以通过或者拒绝
添加用户到黑名单把任意用户拉黑,如果此前是好友关系会解除好友关系
移除黑名单把用户从黑名单中移除
获取黑名单列表拉取用户黑名单列表
好友备注成为好友后可以给好友备注
设置好友自定义资料最多20个好友自定义字段
创建好友分组创建分组时,可以同时指定添加的用户,同一用户可以添加到多个分组
删除好友分组删除好友分组
添加好友到某分组将好友添加到好友分组
从某分组删除好友将好友从好友分组中删除
重命名好友分组重命名好友分组
获取指定好友分组信息获取指定的好友分组
获取所有好友分组获取所有分组信息,另外,通过获取所有好友也可以获取分组信息
关系链资料存储SDK 可以对关系链资料进行存储
好友资料变更系统通知好友资料变更可以收到系统通知
关系链变更系统通知关系链变更可以收到系统通知

群组功能

功能类型私有群
(Private)
公开群
(Public)
聊天室
(ChatRoom)
音视频聊天室
(AVChatRoom)
在线成员广播大群
(BChatRoom)
成员上限200人2000人6000人无上限无上限
群资料修改群成员群管理员
群主
App 管理员
群管理员
群主 
App 管理员
群主 
App 管理员
App 管理员
成员列表全部可见全部可见全部可见展示 300 人
解散群组App 管理员群主 
App 管理员
群主
App 管理员
群主 
App 管理员
App 管理员
申请加群不支持允许允许允许允许
加群审批不支持需审批无审批无审批无审批
邀请加群被邀请人无需审批不支持不支持不支持不支持
群主退群支持不支持不支持不支持不支持
设置管理员不支持支持支持不支持不支持
移出成员群主 
App 管理员
群管理员
群主
App 管理员
群管理员
群主
App 管理员
不支持不支持
是否支持查看入群前历史消息不支持不支持支持不支持不支持
成员变更全员全员全员
群组激活消息激活不需要不需要不需要不需要
成员禁言不支持支持支持支持不支持
未读计数支持支持不支持不支持不支持
导入群支持支持支持不支持不支持

即时通信 IM 控制台

您可以在腾讯云 即时通信 IM 控制台 根据您的需求对您的应用进行配置。

功能类型功能描述
创建应用新建应用
下载 SDK下载客户端的 SDK
应用配置可进行应用配置
统计分析运营数据查看
查看 Crash错误上报
回调配置第三方回调
功能配置增加自定义字段和在线实例
开发者辅助工具在网页端生成 UserSig

数据统计

即时通信 IM 控制台的 统计分析 功能有各类维度的数据统计,为您提供运营数据。

统计类型功能描述
活跃用户数与服务器产生连接交互的去重用户数
新增注册数新增注册 ID 数量
累计注册数查看所有注册用户数
上行消息数可以选择时间查看上行消息数
发送消息人数可以选择时间查看发送消息人数
最高同时在线人数可以选择时间查看在线同时在线人数
单聊上行消息数可以选择时间查看单聊上行消息数
单聊发消息人数可以选择时间查看单聊发消息人数
群聊上行消息数可以选择时间查看群组中上行消息数
群聊发消息人数可以选择时间查看群组中发消息的人数
发消息群组数可以选择时间查看发消息群组数
新增群组数可以选择时间查看新增群组数
累计群组数可以选择时间查看累计群组数
导出数据可以选择时间导出数据

登录鉴权简介

即时通信 IM 的前身是 QQ 的即时通信系统,我们抽离 QQ 的通用模块,并将其整合成适合终端接入的 IM SDK 及后台服务。
您可以把 IM SDK 理解为一个没有用户交互界面的 QQ,把 IM SDK 集成到您的 App 里,就相当于把一个 QQ 的内核集成在您的 App 内部。
QQ 可以用来收发消息,但前提是您必须先登录才能使用。登录 QQ 用的是 QQ 号和密码,登录 IM SDK 需要使用您指定的用户名(UserID)和密码(UserSig)。

  • UserID:旧称为 Identifier,用户登录即时通信 IM 时使用的用户名,即您 App 里的用户 ID。
    例如,App 里有一个用户,该用户的 ID 是27149 ,那么您可以用27149作为登录即时通信 IM 的 UserID。

  • UserSig:用户登录即时通信 IM 时使用的密码,其本质是 App Server 用密钥对 UserID 等信息加密后的数据。具体生成方法请参见 生成 UserSig

App 登录流程

推荐的 App 登录即时通信 IM 流程如下:

注意:


  • 即时通信 IM 后台完全信赖 UserSig,为避免数据和业务受影响,请务必确保私钥的安全。

  • 即时通信 IM 后台 SDK 默认接口生成的 UserSig 有效期为180天,可以使用含有效期参数的接口自行设定有效期,开发者需要在 UserSig 过期前到开发者后台获取新的 UserSig。

  • 用于生成 UserSig 的即时通信 IM 后台 SDK 详细请参阅 生成 UserSig

App 管理员

即时通信 IM 的部分服务需要管理员权限,例如调用 REST API 接口、解散群以及全员推送等。App 管理员是对 App 具有最高管理权限的角色,与普通帐号相比,其区别如下:

  • 读取权限更高。例如,获取 App 内部的所有群组、获取任意群组的任意资料。

  • 操作权限更高。例如,给任意用户发消息、在任意群组中增删成员。

设置 App 管理员仅能通过登录控制台操作,具体操作请参见 配置帐号管理员

概念介绍

在线

在线,是指客户端和即时通信 IM 服务端保持有顺畅的 TCP 网络连接,客户端可以发消息给即时通信 IM 服务端,也可以收到来自即时通信 IM 服务端推送的消息。

App 启动后,客户端和即时通信 IM 服务端建立 TCP 长连接,即时通信 IM 服务端保存客户端的在线信息,例如客户端的网络链路,客户端的平台版本等。App 长连接建立成功后,在运行过程中,IM SDK 会定时发送心跳来确认用户的在线状态。iOS 或 Android 客户端和即时通信 IM 的 TCP 连接断开后,还可以收到消息的离线推送,但此时处于不在线的状态。

说明:

心跳:IM SDK 每隔2分钟发一个心跳包给服务器,以确认用户的在线状态。

上线

上线,是指 App 客户端和即时通信 IM 服务端建立 TCP 长连接的动作。

下线

下线,包括以下两种场景:

  1. App 客户端退出登录。

  2. 即时通信 IM 服务端检测到与 App 客户端的 TCP 长连接断开。服务端依赖心跳包超时来进行判断,当客户端和服务端之间持续 400 秒没有心跳包时,即时通信 IM 服务端认为该用户异常下线(Android 版本较多出现此情况)。

    注意:

    在线、上线、下线这几个概念,唯一的判断标准是客户端与即时通信 IM 后台是否保持网络连接。对于 iOS 或 Android 平台,即使用户不在线,仍然可以收到消息的离线推送。


查询用户在线状态

App 后台可以通过 REST API:获取用户在线状态 来查询一批用户的在线状态。
IM SDK 暂时无法获取用户的在线状态。

用户在线状态变更通知

即时通信 IM 可以把用户上下线的事件通知给 App 后台,参见 状态变更回调 文档。

多端登录

互踢

默认情况,IM SDK 在同时登录多个终端(如同时登录 PC、Android)时,会进行互踢,只有最后一个登录的设备可以在线,之前登录的都会被踢下线,详细互踢逻辑可以参考以下文档:

同时在线

即时通信 IM 支持在 控制台 修改同时在线策略,通过配置可以做到 PC 端和手机端同时在线,或者 PC、iOS 和 Android 都可以同时在线。开启同时在线登录不同终端后不会互踢,但是两个相同终端(例如两个 iOS 端登录)仍然会互踢。

资料系统简介

即时通信 IM 开放了用户资料托管能力,提供资料相关的一整套完整解决方案。如果您想让每个用户都有自己的资料,并且轻松实现资料的设置和拉取功能,那么您可以选择即时通信 IM 的资料托管服务:

  • 即时通信 IM 提供资料的存储能力,确保您的数据具备异地容灾、多地部署和自动扩容/缩容的能力,帮助您从服务器宕机、多拷贝主从复制和扩容缩容等复杂处理流程中得到完全地解放。

  • 即时通信 IM 提供业界通用的业务处理流程,帮助您在用户资料的业务逻辑上彻底地解放。

  • 即时通信 IM 提供专业的运营流程和运营团队,全年99.99%的稳定服务质量,帮助您为用户提供具有稳定口碑的服务。

  • 即时通信 IM 提供简单易用的服务接口和快捷接入的帮助指引,全程为您提供星级服务。

使用即时通信 IM 的资料托管服务,可以得到以下能力:

  • 标配资料字段的存储、读写能力。

  • 自定义资料字段的存储、读写能力。

资料字段

资料是用来描述用户属性的一组数据,即时通信 IM 资料系统支持标配资料字段和自定义资料字段。资料字段有如下特性:

  • 资料字段通过 Key-Value 来表示。

  • Key 为 String 类型,其命名仅支持英文大小写字母、数字、下划线。

  • Value 有以下几种类型:
    a. uint32_t 类型的整数(自定义资料字段不支持)。
    b. uint64_t 类型的整数(自定义资料字段不支持)。
    c. string 类型的字符串(string 的长度不得超过500字节)。
    d. bytes 类型的一段 buffer(buffer 的长度不得超过500字节)。

  • 支持配置每个 Key 的读权限和写权限,资料字段的读写权限如下:

权限名称权限类型备注
读权限App 可读
App 管理员可读
可选择读权限的一个或多个类型
写权限App 可写
App 管理员可写
可选择写权限的一个或多个类型

标配资料字段

目前即时通信 IM 支持的标配资料字段如下:

字段名称类型描述更新时有 Push备注
Tag_Profile_IM_Nickstring昵称长度不得超过500个字节
Tag_Profile_IM_Genderstring性别Gender_Type_Unknown:没设置性别
Gender_Type_Female:女性
Gender_Type_Male:男性
Tag_Profile_IM_BirthDayuint32生日推荐用法:20190419
Tag_Profile_IM_Locationstring所在地长度不得超过16个字节,推荐用法如下:
App 本地定义一套数字到地名的映射关系
后台实际保存的是4个 uint32_t 类型的数字
其中第一个 uint32_t 表示国家
第二个 uint32_t 用于表示省份
第三个 uint32_t 用于表示城市
第四个 uint32_t 用于表示区县 
Tag_Profile_IM_SelfSignaturestring个性签名长度不得超过500个字节
Tag_Profile_IM_AllowTypestring加好友验证方式AllowType_Type_NeedConfirm:需要经过自己确认才能添加自己为好友
AllowType_Type_AllowAny:允许任何人添加自己为好友
AllowType_Type_DenyAny:不允许任何人添加自己为好友 
Tag_Profile_IM_Languageuint32语言
Tag_Profile_IM_Imagestring头像URL长度不得超过500个字节
Tag_Profile_IM_MsgSettingsuint32消息设置标志位:
Bit0:置0表示接收消息,置1则不接收消息 
Tag_Profile_IM_AdminForbidTypestring管理员禁止加好友标识AdminForbid_Type_None:默认值,允许加好友
AdminForbid_Type_SendOut:禁止该用户发起加好友请求
Tag_Profile_IM_Leveluint32等级通常一个 UINT-8 数据即可保存一个等级信息
您可以考虑拆分保存,从而实现多种角色的等级信息
Tag_Profile_IM_Roleuint32角色通常一个 UINT-8 数据即可保存一个角色信息
您可以考虑拆分保存,从而保存多种角色信息

自定义资料字段

自定义资料字段是各 App 根据各自业务需要而设置的用户数据。通过自定义资料,各 App 可以将一些额外数据附加到用户资料上,并通过现有接口进行读写操作。

自定义资料字段的申请

App 管理员可以通过即时通信 IM 控制台>【应用配置】>【功能配置】 申请自定义资料字段,申请提交后,自定义资料字段将在5分钟内生效。
申请自定义资料字段时,需要为每一个自定义资料字段提交如下资料:

自定义资料字段的命名规范

自定义资料字段的命名规则如下:

  • 自定义资料字段的名称包括前缀和关键字两部分。

  • 自定义资料字段的前缀是:Tag_Profile_Custom。

  • 关键字:必须是英文字母,且长度不得超过8字节,建议用一个英文单词或该英文单词的缩写。

  • 示例:某 App 要申请的自定义字段的关键字是 Test,则自定义资料字段的名称是:Tag_Profile_Custom_Test。


关系链系统简介

即时通信 IM 开放了用户关系链托管能力,提供关系链相关的一整套完整解决方案。如果您不希望自行开发或维护 App 内用户之间的好友关系,并且轻松玩转加删好友等一系列功能,那么您可以选择即时通信 IM 的关系链托管服务:

  • 即时通信 IM 提供关系链的存储能力,并确保您的数据具备异地容灾、多地部署和自动扩容缩容的能力,帮助您从服务器宕机、多拷贝主从复制和扩容缩容等复杂处理流程中得到完全地解放。

  • 即时通信 IM 提供业界通用的业务处理流程,帮助您在用户关系链的逻辑上彻底地解放。

  • 即时通信 IM 提供专业的运营流程和运营团队,全年 99.99% 的稳定服务质量,帮助您为用户提供具有稳定口碑的服务。

  • 即时通信 IM 提供简单易用的服务接口和快捷接入的帮助指引,全程为您提供星级服务。

关系链是一组用于描述用户和其他用户关系的数据,即时通信 IM 目前支持的关系链有好友表和黑名单两种。

关系链字段

即时通信 IM 关系链系统支持标配关系链字段和自定义关系链字段,关系链字段有如下特性:

  • 关系链字段通过 Key-Value 形式表示。

  • Key 为 String 类型,其命名仅支持英文大小写字母、数字、下划线。

  • Value 有以下几种类型:
    a. uint64_t 类型的整数(自定义关系链字段不支持)。
    b. string 类型的字符串(string 的长度不得超过 500 字节)。
    c. bytes 类型的一段 buffer(buffer 的长度不得超过 500 字节)。
    d. string 类型的字符串数组(每个 string 的长度都不得超过 500 字节,仅供好友表的 Tag_SNS_IM_Group 字段使用)。

好友表

即时通信 IM 的好友列表最多允许添加3000个好友。
好友表支持标配好友字段和自定义好友字段。

标配好友字段

目前即时通信 IM 支持的标配好友字段如下:

字段名称类型描述
Tag_SNS_IM_GroupArray好友分组:
1. 最多支持 32 个分组;
2. 不允许分组名为空;
3. 分组名长度不得超过 30 个字节;
4. 同一个好友可以有多个不同的分组
Tag_SNS_IM_Remarkstring好友备注:
1. 备注长度最长不得超过 96 个字节
Tag_SNS_IM_AddSourcestring加好友来源:
1. 加好友来源字段包含前缀和关键字两部分;
2. 加好友来源字段的前缀是:AddSource_Type_ ;
3. 关键字:必须是英文字母,且长度不得超过 8 字节,建议用一个英文单词或该英文单词的缩写;
4. 示例:加好友来源的关键字是 Android,则加好友来源字段是:AddSource_Type_Android 
Tag_SNS_IM_AddWordingstring加好友附言:
1. 加好友附言的长度最长不得超过 256 个字节

自定义好友字段

自定义好友字段是各 App 根据各自业务需要而设置的好友数据。通过自定义好友字段,各 App 可以将一些额外数据附加到好友上,并通过现有的接口进行读写操作。
App 管理员可以通过即时通信 IM 控制台 >【应用配置】>【功能配置】申请自定义好友字段,申请提交后,自定义好友字段将在5分钟内生效。

自定义好友字段的命名规则如下:

  • 自定义好友字段的名称分为以下两部分:前缀、关键字。

  • 自定义好友字段的前缀是:Tag_SNS_Custom。

  • 关键字:必须是英文字母,且长度不得超过 8 字节,建议用一个英文单词或该英文单词的缩写。

  • 示例:某 App 要申请的自定义好友字段的关键字是 Test,则自定义关系字段的名称是:Tag_SNS_Custom_Test。

申请自定义好友字段时,需要为每一个自定义好友字段提交如下资料:

  • 自定义好友字段的名称(Key)。

  • 自定义好友字段的类型(Value):详情可参见 关系链字段

添加好友

即时通信 IM 支持的加好友模式有:批量加好友、一回合加好友和两回合加好友,详情可参见 添加好友

双向好友:用户 A 的好友表中有用户 B,B 的好友表中也有 A。
单向好友:用户 A 的好友表中有用户 B,但 B 的好友表中却没有 A。
加好友验证方式:每个用户都可以选择自己以哪种方式被其他用户添加为好友,详情可参见 标配资料字段 中的加好友验证方式字段。
一回合加好友:如果帐号 A 设置的加好友验证方式是 AllowType_Type_AllowAny,那么任何人添加 A 为好友都可以直接添加成功,这种一个请求就添加好友成功的场景称作一回合加好友。
两回合加好友:如果帐号 A 设置的加好友验证方式是 AllowType_Type_NeedConfirm,那么任何人添加 A,A 都会收到一个请求加好友验证消息,这是第一个回合,然后 A 对这个请求加好友验证消息进行同意操作时,这是第二个回合,这种需要验证的加好友场景就被称为两回合加好友。

删除好友

即时通信 IM 支持单向删除好友和双向删除好友等两种好友删除模式。

删除模式DeleteType描述
单向删除好友Delete_Type_Single只将 To_Account 从 From_Account 的好友表中删除,但不会将 From_Account 从 To_Account 的好友表中删除
双向删除好友Delete_Type_Both将 To_Account 从 From_Account 的好友表中删除,同时将 From_Account 从 To_Account 的好友表中删除

即时通信 IM 也支持批量删除好友,更多信息可参见 删除好友

拉取好友

即时通信 IM 支持以下三种拉好友模式:不带好友的增量拉取模式、全量分页拉取模式以及带好友拉取模式。详情可参见 拉取好友

校验好友

即时通信 IM 支持以下两种好友校验模式:单向校验好友关系、双向校验好友关系。

校验模式CheckType描述
单向校验好友关系CheckResult_Type_Single只会检查 From_Account 的好友表中是否有 To_Account,不会检查 To_Account 的好友表中是否有 From_Account
双向校验好友关系CheckResult_Type_Both既会检查 From_Account 的好友表中是否有 To_Account,也会检查 To_Account 的好友表中是否有 From_Account

单向校验好友关系时可能的结果有:

Relation描述
CheckResult_Type_NoRelationFrom_Account 的好友表中没有 To_Account,但无法确定 To_Account 的好友表中是否有 From_Account
CheckResult_Type_AWithBFrom_Account 的好友表中有 To_Account,但无法确定 To_Account 的好友表中是否有 From_Account

双向校验好友关系时可能的结果有:

Relation描述
CheckResult_Type_BothWayFrom_Account 的好友表中有 To_Account,To_Account 的好友表中也有 From_Account
CheckResult_Type_AWithBFrom_Account 的好友表中有 To_Account,但 To_Account 的好友表中没有 From_Account
CheckResult_Type_BWithAFrom_Account 的好友表中没有 To_Account,但 To_Account 的好友表中有 From_Account
CheckResult_Type_NoRelationFrom_Account 的好友表中没有 To_Account,To_Account 的好友表中也没有 From_Account

校验好友的其他相关信息可参见 校验好友

黑名单

每个用户都有一份黑名单,用于保存被该用户屏蔽的帐号。
用户 A 将用户 B 加入黑名单后,A 与 B 之间的好友关系会被解除(如果有),且 A 与 B 之间无法再发起加好友请求。
即时通信 IM 的黑名单列表默认允许添加 1000 条黑名单帐号,如对黑名单列表的大小有特殊要求,请联系腾讯云客服。

添加黑名单

即时通信 IM 支持批量添加黑名单,详情可参见:添加黑名单

删除黑名单

即时通信 IM 支持批量删除黑名单,详情可参见:删除黑名单

拉取黑名单

即时通信 IM 支持通过分页模式拉取全量黑名单,详情可参见:拉取黑名单

校验黑名单

即时通信 IM 支持以下两种黑名单校验模式:单向校验黑名单关系、双向校验黑名单关系。

校验模式CheckType描述
单向校验黑名单关系BlackCheckResult_Type_Single只会检查 From_Account 的黑名单中是否有 To_Account,不会检查 To_Account 的黑名单中是否有 From_Account
双向校验黑名单关系BlackCheckResult_Type_Both既会检查 From_Account 的黑名单中是否有 To_Account,也会检查 To_Account 的黑名单中是否有 From_Account

单向校验黑名单关系时可能的结果有:

Relation描述
BlackCheckResult_Type_AWithBFrom_Account 的黑名单中有 To_Account,但无法确定 To_Account 的黑名单中是否有 From_Account
BlackCheckResult_Type_NOFrom_Account 的黑名单中没有 To_Account,但无法确定 To_Account 的黑名单中是否有 From_Account

双向校验黑名单关系时可能的结果有:

Relation描述
BlackCheckResult_Type_BothWayFrom_Account 的黑名单中有 To_Account,To_Account 的黑名单中也有 From_Account
BlackCheckResult_Type_AWithBFrom_Account 的黑名单中有 To_Account,但 To_Account 的黑名单中没有 From_Account
BlackCheckResult_Type_BWithAFrom_Account 的黑名单中没有 To_Account,但 To_Account 的黑名单中有 From_Account
BlackCheckResult_Type_NOFrom_Account 的黑名单中没有 To_Account,To_Account 的黑名单中也没有 From_Account

校验黑名单的其他相关信息可参见校验黑名单

应用场景

  • App 内双人聊天
    单聊消息适用于 App 内双人聊天,类似 QQ 好友、微信好友的聊天方式。

  • App 管理员发送消息
    单聊消息可以由 App 管理员在后台发送消息,也可以模拟其他用户身份发送消息。

  • App 管理员模拟系统消息
    通过 App 管理员在后台发送消息,可以模拟系统消息,以系统消息的形式给用户下达通知,App 端收到 App 管理员的自定义消息可做特殊处理。

即时通信 IM 提供完善的单聊消息能力,同时,我们也提供针对单聊消息的权限控制及扩展能力,帮助客户实现获取消息记录、多终端同步、离线消息推送及携带发送者资料等能力。

单聊消息类型

功能类型功能描述
文本消息消息内容是普通文本
表情消息表情消息为开发者自定义
地理位置消息消息内容为地理位置标题、经度、纬度信息
图片消息消息内容为图片的 URL 地址、尺寸、图片大小等信息,最大支持大小为28M的图片
语音消息消息内容为语音文件的 URL 地址、大小、时长等信息,最大支持大小为28M的语音文件
文件消息消息内容为文件的 URL 地址、大小、格式等信息,格式不限,最大支持大小为28M的文件
短视频消息消息内容为短视频文件的 URL 地址、时长、大小、格式等信息,最大支持大小为28M的短视频文件
自定义消息开发者自定义的消息类型,例如红包消息、石头剪刀布等形式的消息
系统通知消息包含内置的系统通知消息和开发者自定义系统通知消息

单聊消息能力

单聊消息能力功能描述应用场景
发送单聊消息可通过 SDK 和 REST API 发送单聊消息App 内双人聊天
App 管理员发送消息
App 管理员模拟系统消息
接收单聊消息可通过 SDK 接收单聊消息接收在线消息
接收离线消息
查询历史消息

单聊消息权限控制

单聊消息权限控制功能描述应用场景
App 内任意两个用户之间发送单聊消息支持任意两个陌生人发送消息陌生人发送消息
App 管理员发送单聊消息App 内管理员可以给任意用户发送单聊消息App管理员模拟其他用户发送消息 
App 管理员模拟系统消息
只允许给好友发送消息支持仅好友发送消息好友发送消息
拒绝来自某人的消息可通过黑名单拒绝来自某用户的消息解除好友关系 
拒绝某人消息

单聊消息扩展能力

单聊消息扩展能力功能描述应用场景
获取聊天记录可通过 SDK 或 REST API 获取历史消息获取实时聊天记录 
定期下载消息记录
多终端同步支持单聊消息多终端同步用户多终端消息同步
单聊消息离线推送支持 Apple、华为、小米、OPPO、vivo 和魅族等品牌手机离线推送消息离线推送
单聊消息中携带发送者资料可实现消息中携带发送者资料展示发送者昵称、头像等

单聊离线消息处理流程

单聊消息离线及漫游处理流程:

  1. 用户 A 调用 sendMessage 给用户 B 发送消息,用户 B 处于下线状态。


    • 把用户 A 添加进用户 B 的最近联系人,缓存大小为100条。

    • 把消息存入离线缓存中,缓存大小30K,时间限制7天。

    • 把消息存入漫游服务器中,时间限制7天。

  2. 用户 B 调用 login 接口登录即时通信 IM。

  3. SDK 自动拉取离线缓存中的消息,通过 OnNewMessage 抛出。

  4. SDK 自动拉取最近联系人,通过 OnNewMessage 接口抛出。

  5. 同步消息过程完成,通过 OnRefresh 接口通知用户已完成消息同步。

  6. 用户调用 getMessage,如果本地消息不完整,SDK 自动拉取漫游服务器。

离线消息存储

即时通信 IM 支持离线消息缓存,即当用户不在线时,下次登录仍会拉取到离线消息。离线消息默认保存7天,如果用户7天内未登录,再次登录时将不能获取到7天前的离线消息。每个用户的离线消息缓存有空间限制,如果超出,将按照时间顺序逐条删除(最早的消息将会最先被删除)。这些被删除的离线消息不会被计入未读计数,但这些消息仍会存到消息漫游中。每个用户的缓存空间最大为30K,最大离线消息条数根据每条消息空间占用情况有上下浮动,其中每条消息的类型、文本长短等因素都会影响到该条消息占用的空间大小。

默认情况下,一个终端通过 SDK 把离线消息拉取到本地后,即时通信 IM 服务器便会删除这些离线消息。如果需要支持多终端,或更换终端后仍想拉取未读的离线消息,需要用户自行管理这些离线消息。禁用 SDK 自动已读上报功能后,只有用户显式调用已读上报接口时,即时通信 IM 服务器才会删除这些离线消息,否则这些离线消息将在到期后自动删除。如果用户没有显式调用已读上报接口,更换终端后,仍然可以拉取到未读的离线消息。

漫游消息存储

即时通信 IM 支持消息漫游,即用户更换终端的情况下,也可以获取到跟其他用户或者某个群的聊天记录。
默认情况下,单聊消息和群聊消息有7天漫游,超过漫游时长的消息会被删除。即时通信 IM 支持在控制台修改消息漫游时长,延长消息漫游时长是增值服务,具体计费说明请参考 价格说明

不同版本的 SDK 支持延长历史消息存储时长的消息类型不同,详情如下表所示。

SDK 版本文本自定义类消息图片文件短语音短视频富媒体消息
Android 4.X 版本
Android 3.X 版本×××××
Android 2.X 版本×××××
iOS 4.X 版本
iOS 3.X 版本×××××
iOS 2.X 版本×××××
PC SDK 2.X 版本×××××
Web 与小程序 SDK 2.X 版本
Web 与小程序 SDK 1.X 版本×××××
说明:

建议您升级至最新版本的 SDK,以便获得更好的用户体验。

最近联系人消息

最近联系人消息类似 QQ 的最近联系人列表中,可展示最近跟用户联系过的用户以及最后一条消息。

客户端默认情况下会在登录时通过 SDK 拉取最近联系人消息,如果本地之前没有存储过,会通过 onNewMessage 回调取得。

使用最近联系人,登录时会消耗一些流量,获取服务器中相关联系人的最后一条消息。如果不需要此功能,可通过 SDK 实现禁用,最近联系人默认存储最近100个联系人,但是保存时长跟最近联系人中的最后一条消息保存时间一致,例如默认如果超过7天跟联系人没有消息,最后一条消息过期后便无法在最近联系人中获取到此用户。

App 本地存储

默认情况下,SDK 内部会对收到的消息进行存储,无需用户进行存储。用户可调用接口获取本地消息(无网络操作),另外,通过 getMessage 接口,也会获取本地消息,如果本地消息存在断层,会通过漫游消息补全。
SDK 默认不会删除用户消息,但我们提供本地消息删除的能力满足您特殊的需要。

注意:

使用本地存储会消耗磁盘以及 CPU 性能,在不需要存储的场景(如直播场景,更注重消息处理性能,也不关心历史消息),可选择禁用本地存储。

应用场景

在 App 退后台或者进程被 kill 的情况下,有新消息需要提醒用户时,可使用离线推送功能,在 iOS 端会有 APNs 推送,Android 端则需要用户注册离线消息回调。

iOS APNs 推送

推送格式说明

上图为一条单聊消息和一条群聊消息的示例。
iOS APNs 推送格式详细说明可参考 推送格式说明

基本接口说明

支持 APNs 必须调用以下接口,具体请参考 iOS APNs 事件上报

  • 设置 Token。

  • 切后台上报未读。

  • 切前台通知。

Ext 扩展设置

有时应用需要根据情况设置推送的 Ext 扩展字段,方便用户点击跳转等操作,可以填写到 TIMCustomElem 中的 Ext 字段,推送时即时通信 IM 后台会把该字段填入 Ext,请参考 自定义离线消息属性 定制扩展字段。

设置推送声音

有时应用需要根据情况设置单条消息的推送声音,方便特别提醒某类消息,可以把声音填写到 TIMCustomElem 中的 sound 字段,推送时即时通信 IM 后台会把该字段填入 Ext,请参考 设置自定义推送提示音 。

Android 离线推送

Android 在1.8.0以后版本支持服务和进程分离,如果 App 进程被 kill,服务仍然存活,可以收到离线推送功能。具体配置以及设置过程,可参考 Android 离线推送 文档。

后台发送消息

后台发送消息时,对于 iOS 端您可以参考 推送格式 设置 APNs 推送的展示形式,对于 Android 端您可以参考 离线推送 OfflinePushInfo 进行设置。

应用场景

群内收发消息

群成员在群内收发消息,类似 QQ 群、微信群的聊天方式。

App 管理员发送消息

群聊消息可以由 App 管理员在后台发送消息,也可以模拟其他用户身份发送消息(即使 App 管理员或发送者不是群成员,消息依然会下发)。

App 管理员模拟系统消息

通过 App 管理员在后台发送消息,可以模拟系统消息,以系统消息的形式给指定的群内在线成员,App 端收到 App 管理员的自定义消息可做特殊处理。

群消息的 SEQ 机制

即时通信 IM 会为每个群维护一个消息 SEQ。SEQ 的初始值为 1。群内每产生一条普通消息,即时通信 IM 后台会将当前 SEQ 的值作为该消息的 SEQ,并且将该 SEQ 自增 1。
群组 ID + SEQ,相当于是一条消息的唯一标识。

注意:

即时通信 IM 只会为普通消息产生 SEQ,不会为系统消息产生 SEQ;

群聊消息类型

消息类型描述
文本消息消息内容是普通文本
图片消息消息内容为图片 URL 地址、尺寸、图片大小等信息
表情消息表情消息是由开发者自定义
语音消息语音数据需要提供时长信息,以秒为单位
地理位置消息消息内容为地理位置标题、经度、纬度信息
文件消息消息内容为文件的 URL 地址、大小、格式等信息,格式不限,最大支持28M
短视频消息消息内容为语音文件的 URL 地址、时长、大小、格式等信息,最大支持28M
自定义消息开发者自定义的消息类型,例如红包消息、石头剪刀布等形式的消息
系统通知消息包含内置的系统通知消息和开发者自定义系统通知消息

群聊消息能力

类型功能描述应用场景
发送群普通消息群成员可以通过 IM SDK 接口发送消息。App 管理员无需加入群组,即可调用 REST API 在任意群组中发送消息。群成员在群内发送消息,App 管理员向任意群组发送消息
发送群系统消息App 管理员无需加入群组,即可调用 REST API 在群组中发送系统通知。该系统通知,只有群内在线成员才会收到该消息,不具备漫游能力。App 管理员群内部分或者全部在线成员推送一条时效性较高的提醒
群消息离线推送支持 Apple、华为、小米、OPPO、vivo、魅族等品牌手机离线推送群聊消息离线推送
接收群在线消息群成员可以通过 IM SDK 接收群聊在线消息在线群成员实时接收群消息
群成员获取离线/历史消息群成员通过 IM SDK 接口查询历史消息群成员上线接收离线消息,群成员查看群聊天记录
App 后台获取群消息App 管理员可通过 REST API 下载 App 在某一段时间内产生所有的消息;App 管理员亦可通过 REST API,获取任意群的聊天记录;App 后台可以通过群内发言之后回调,实时获取群消息。App 定期备份消息记录的场景;App 需要快速获取指定群组历史消息的场景;App 需要实时获取群消息的场景
消息删除可通过 REST API 将历史消息删除,确保该消息不被传播群内恶意信息删除
群聊消息中携带发送者资料在群消息中携带发送者的昵称、头像、群名片、用户维度的自定义字段、群维度的自定义字段、群成员维度的自定义字段展示消息发送人昵称、头像等信息
脏字过滤即时通信 IM 后台在用户发送的消息中检测到是否包含脏字,如包含则拒绝下发该消息,并向发送者返回错误码 80001;
即时通信 IM 已经默认配置了政治类、色情类的脏字,能够满足这两方面的大多数过滤需求。同时也支持 App 配置自定义的脏字。
消息安全打击
群消息发送控制禁言和群消息发送前回调,是控制群消息发送的两种方式。禁止群内某个成员发送消息,禁止群内所有成员发消息,App 后台过滤或修改消息
群消息接收控制用户针对单个群组设置不同的消息接收选项:接收并提示,接收不提示,屏蔽消息。设置“接收不提示”后,iOS 终端会去掉 APNs 推送功能用户屏蔽某个群组的消息
群消息频率控制控制群普通消息的发送频率,默认值为 40条/秒。频控对象不包括 App 管理员用 REST API 发送的群系统消息。详细请参考下文消息优先级与频率控制。避免消息刷屏
注意:

如需携带发送者昵称和头像,则必须把这两个字段的信息导入到即时通信 IM 的用户资料中。
如果需要携带自定义资料,则需要先在控制台配置自定义字段,然后再提工单申请在消息携带相应的字段。

群消息发送控制

可以通过以下方式控制群消息的发送:

控制方式详细描述
群组内禁言禁止某一用户一段时间内在群内发言,只针对单个群组有效。如果用户退群再重新入群,只要禁言时间没有过期,禁言依旧有效
群消息发送前回调在把群消息下发给群成员之前,即时通信 IM 后台先去 App 后台询问是否允许下发消息,如果不允许,则拒绝下发消息;
App 后台在收到回调后,也可对消息内容进行修改并返回给即时通信 IM,即时通信 IM 将使用修改之后的信息进行下发,详情请参考 群内发言之前回调
但是即时通信 IM 在发起该回调后,最多只会等待2秒。如2秒内未收到应答,直接将消息下发给群成员,不会进行重试

消息优先级与频率控制

群消息优先级

群消息分为 4 个优先级,如果某个群的消息超过了频率限制,后台会优先下发高优先级的消息。因此用户应根据消息的重要程度,来选择合适的优先级。
4个优先级从高到低,分别如下:

优先级建议选择该优先级的消息类型
High红包消息和礼物消息
Normal普通文本消息
Low点赞消息
Lowest最不重要的消息

群消息频控

总消息数频控

总消息数频控是指单个群每秒最多能发送的消息数限制,默认值为 40条/秒。消息数量超过限制后,后台优先下发优先级相对较高的消息,同等优先级的消息随机排序。

被频控限制的消息,不会下发,不会存入历史消息,但会给发送人返回成功;会触发 群内发言之前回调,但不会触发 群内发言之后回调

优先级频控

优先级频控是指单个群每秒最多能发送多少条某优先级的消息,发消息请求只有在通过总消息数频控之后,才会进入优先级频控。
App 管理员/群主/群管理员发送的消息不受优先级频控限制;High 优先级的消息不受优先级频控限制,其余 3 个优先级可以独立配置,默认都为 40 条/秒。
一个 SDKAppID 下的每个 群组形态 都有自己的总消息数频控和优先级频控配置。如果需要修改默认值,请 提交工单 进行申请。

群组离线消息处理流程

群组离线消息处理流程:

  1. 用户 A 调用sendMessage给群组 C 发送消息,用户 B 处于下线状态;
    1.1 把群组 C 添加进用户 B 的最近联系人,缓存大小为 100 条;
    1.2 用户更新群组的消息信息,包括群组最新消息 seq;
    1.3 把消息存入漫游服务器中,时间限制 7 天。

  2. 用户B调用login接口登录即时通信 IM;

  3. SDK 自动拉取所有群组的消息 seq 信息,包括最新消息 seq 和未读计数;

  4. SDK 自动拉取最近联系人,通过OnNewMessage接口抛出;

  5. 同步消息过程完成,通过OnRefresh接口通知用户已完成群组数据同步;

  6. 用户调用getMessage,SDK 自动拉取漫游服务器。

消息内容 MsgBody 说明

MsgBody 中所填写字段是消息内容。即时通信 IM 支持一条消息中包括多种消息元素类别,例如一条消息中既包括文本消息元素,还包括表情消息元素。因此 MsgBody 定义为 Array 格式,可按照需求加入多类消息元素。消息元素名称为 TIMMsgElement,消息元素 TIMMsgElement 组成 MsgBody 的示例请参见 消息内容 MsgBody 实例

消息元素 TIMMsgElement 的格式统一为:

{    "MsgType": "",    "MsgContent": {}}
字段类型说明
MsgTypeString消息元素类别;目前支持的消息对象包括:TIMTextElem(文本消息),TIMLocationElem(位置消息),TIMFaceElem(表情消息),TIMCustomElem(自定义消息),TIMSoundElem(语音消息),TIMImageElem(图像消息),TIMFileElem(文件消息),TIMVideoFileElem(视频消息)。
MsgContentObject消息元素的内容,不同的 MsgType 有不同的 MsgContent 格式,具体参见下文。

目前支持消息类别 MsgType 见下表:

MsgType的值类型
TIMTextElem文本消息。
TIMLocationElem地理位置消息。
TIMFaceElem表情消息。
TIMCustomElem自定义消息,当接收方为 iOS 系统且应用处在后台时,此消息类型可携带除文本以外的字段到 APNs。一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。
TIMSoundElem语音消息。(服务端集成 Rest API 不支持发送该类消息)
TIMImageElem图像消息。(服务端集成 Rest API 不支持发送该类消息)
TIMFileElem文件消息。(服务端集成 Rest API 不支持发送该类消息)
TIMVideoFileElem视频消息。(服务端集成 Rest API 不支持发送该类消息)
注意:

通过服务端集成的 Rest API 接口,只能发送 TIMTextElem,TIMLocationElem,TIMFaceElem,TIMCustomElem 类型的消息,其它类型的消息(TIMSoundElem,TIMImageElem,TIMFileElem,TIMVideoFileElem)不能通过 Rest API 接口发送。

消息元素 TIMMsgElement

文本消息元素

{    "MsgType": "TIMTextElem",    "MsgContent": {        "Text": "hello world"    }}
字段类型说明
TextString消息内容。当接收方为 iOS 或 Android 后台在线时,作为离线推送的文本展示。

当接收方为 iOS 或 Android,且应用处在后台时,JSON 请求包体中的 Text 字段作为离线推送的文本展示。

地理位置消息元素

{    "MsgType": "TIMLocationElem",     "MsgContent": {        "Desc": "someinfo",         "Latitude": 29.340656774469956,         "Longitude": 116.77497920478824    }}
字段类型说明
DescString地理位置描述信息。
LatitudeNumber纬度。
LongitudeNumber经度。

当接收方为 iOS 或 Android,且应用处在后台时,中文版离线推送文本为“[位置]”,英文版离线推送文本为“[Location]”。

表情消息元素

{    "MsgType": "TIMFaceElem",     "MsgContent": {        "Index": 1,         "Data": "content"    }}
字段类型说明
IndexNumber表情索引,用户自定义。
DataString额外数据。

当接收方为 iOS 或 Android,且应用处在后台时,中文版离线推送文本为“[表情]”,英文版离线推送文本为“[Face]”。

自定义消息元素

{    "MsgType": "TIMCustomElem",     "MsgContent": {        "Data": "message",         "Desc": "notification",         "Ext": "url",         "Sound": "dingdong.aiff"    }}
字段类型说明
DataString自定义消息数据。 不作为 APNs 的 payload 字段下发,故从 payload 中无法获取 Data 字段。
DescString自定义消息描述信息。当接收方为 iOS 或 Android 后台在线时,做离线推送文本展示。
若发送自定义消息的同时设置了 OfflinePushInfo.Desc 字段,此字段会被覆盖,请优先填 OfflinePushInfo.Desc 字段。
当消息中只有一个 TIMCustomElem 自定义消息元素时,如果 Desc 字段和 OfflinePushInfo.Desc 字段都不填写,将收不到该条消息的离线推送,需要填写 OfflinePushInfo.Desc 字段才能收到该消息的离线推送。
ExtString扩展字段。当接收方为 iOS 系统且应用处在后台时,此字段作为 APNs 请求包 Payloads 中的 Ext 键值下发,Ext 的协议格式由业务方确定,APNs 只做透传。
SoundString自定义 APNs 推送铃音。

当接收方为 iOS 系统且应用处在后台时,Desc 作为推送文本, Ext 字段作为 APNS 请求包 Payloads 中的 ext 键值下发, Data 字段不作为 APNs 的 Payloads 字段下发。注意,一条组合消息中只能包含一个 TIMCustomElem 自定义消息元素。

语音消息元素

注意:

不能通过服务端集成的 Rest API 接口发送语音消息,发送语音消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的语音消息元素的格式如下:

{    "MsgType": "TIMSoundElem",    "MsgContent": {        "Url": "https://1234-5678187359-1253735226.cos.ap-shanghai.myqcloud.com/abc123/c9be9d32c05bfb77b3edafa4312c6c7d",        "Size": 62351,        "Second": 1,        "Download_Flag": 2    }}
字段类型说明
UrlString语音下载地址,可通过该 URL 地址直接下载相应语音。
SizeNumber语音数据大小,单位:字节。
SecondNumber语音时长,单位:秒。
Download_FlagNumber语音下载方式标记。目前 Download_Flag 取值只能为2,表示可通过Url字段值的 URL 地址直接下载语音。
说明:

2.X和3.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的语音消息元素如下:

{    "MsgType": "TIMSoundElem",    "MsgContent": {        "UUID": "305c0201", //语音序列号,类型为 String。后台用于索引语音的键值。无法通过该字段下载相应的语音。若需要获取该语音,请升级 IM SDK 版本至4.X。"Size": 62351,        //语音数据大小,类型为 Number,单位:字节。"Second": 1//语音时长,类型为 Number,单位:秒。    }}

图像消息元素

注意:

不能通过服务端集成的 Rest API 接口发送图像消息,发送图像消息需要通过客户端集成相应的接口。

{    "MsgType": "TIMImageElem",    "MsgContent": {        "UUID": "1853095_D61040894AC3DE44CDFFFB3EC7EB720F",        "ImageFormat": 1,        "ImageInfoArray": [            {                "Type": 1,           //原图"Size": 1853095,                "Width": 2448,                "Height": 3264,                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/0"            },            {                "Type": 2,      //大图"Size": 2565240,                "Width": 0,                "Height": 0,                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/720"            },            {                "Type": 3,   //缩量图"Size": 12535,                "Width": 0,                "Height": 0,                "URL": "http://xxx/3200490432214177468_144115198371610486_D61040894AC3DE44CDFFFB3EC7EB720F/198"            }        ]    }}
字段类型说明
UUIDString图片序列号。后台用于索引图片的键值。
ImageFormatNumber图片格式。JPG = 1,GIF = 2,PNG = 3,BMP = 4,其他 = 255。
ImageInfoArrayArray原图、缩略图或者大图下载信息。
TypeNumber图片类型: 1-原图,2-大图,3-缩略图。
SizeNumber图片数据大小,单位:字节。
WidthNumber图片宽度。
HeightNumber图片高度。
URLString图片下载地址。

文件消息元素

注意:

不能通过服务端集成的 Rest API 接口发送文件消息,发送文件消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的文件消息元素的格式如下:

{    "MsgType": "TIMFileElem",    "MsgContent": {        "Url": "https://7492-5678539059-1253735326.cos.ap-shanghai.myqcloud.com/abc123/49be9d32c0fbfba7b31dafa4312c6c7d",        "FileSize": 1773552,        "FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV",        "Download_Flag": 2    }}
字段类型说明
UrlString文件下载地址,可通过该 URL 地址直接下载相应文件。
FileSizeNumber文件数据大小,单位:字节。
FileNameString文件名称。
Download_FlagNumber文件下载方式标记。目前 Download_Flag 取值只能为2,表示可通过Url字段值的 URL 地址直接下载文件。
说明:

2.X和3.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的文件消息元素如下:

{    "MsgType": "TIMFileElem",    "MsgContent": {        "UUID": "305c02010", //文件序列号,类型为 String。后台用于索引文件的键值。无法通过该字段下载相应的文件。若需要获取该文件,请升级 IM SDK 版本至4.X。"FileSize": 1773552, //文件数据大小,类型为 Number,单位:字节。"FileName": "file:///private/var/Application/tmp/trim.B75D5F9B-1426-4913-8845-90DD46797FCD.MOV"//文件名称,类型为 String。    }}

视频消息元素

注意:

不能通过服务端集成的 Rest API 接口发送视频消息,发送视频消息需要通过客户端集成相应的接口。

4.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的视频消息元素的格式如下:

{    "MsgType": "TIMVideoFileElem",    "MsgContent": {        "VideoUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/f7c6ad3c50af7d83e23efe0a208b90c9",        "VideoSize": 1194603,        "VideoSecond": 5,        "VideoFormat": "mp4",        "VideoDownloadFlag":2,        "ThumbUrl": "https://0345-1400187352-1256635546.cos.ap-shanghai.myqcloud.com/abcd/a6c170c9c599280cb06e0523d7a1f37b",        "ThumbSize": 13907,        "ThumbWidth": 720,        "ThumbHeight": 1280,        "ThumbFormat": "JPG",        "ThumbDownloadFlag":2    }}
字段类型说明
VideoUrlString视频下载地址。可通过该 URL 地址直接下载相应视频。
VideoSizeNumber视频数据大小,单位:字节。
VideoSecondNumber视频时长,单位:秒。
VideoFormatString视频格式,例如 mp4。
VideoDownloadFlagNumber视频下载方式标记。目前 VideoDownloadFlag 取值只能为2,表示可通过VideoUrl字段值的 URL 地址直接下载视频。
ThumbUrlString视频缩略图下载地址。可通过该 URL 地址直接下载相应视频缩略图。
ThumbSizeNumber缩略图大小,单位:字节。
ThumbWidthNumber缩略图宽度。
ThumbHeightNumber缩略图高度。
ThumbFormatString缩略图格式,例如 JPG、BMP 等。
ThumbDownloadFlagNumber视频缩略图下载方式标记。目前 ThumbDownloadFlag 取值只能为2,表示可通过ThumbUrl字段值的 URL 地址直接下载视频缩略图。
说明:

2.X和3.X版本 IM SDK(Android、iOS、Mac 以及 Windows)发出的视频消息元素如下:

{    "MsgType": "TIMVideoFileElem",    "MsgContent": {        "VideoUUID": "1400123456_dramon_34ca36be7dd214dc50a49238ef80a6b5",//视频序列号,类型为 String。后台用于索引视频的键值。无法通过该字段下载相应的视频。若需要获取该视频,请升级 IM SDK 版本至4.X。"VideoSize": 1194603, //视频数据大小,类型为 Number,单位:字节。"VideoSecond": 5,     //视频时长,类型为 Number,单位:秒。"VideoFormat": "mp4", //视频格式,类型为 String,例如 mp4。"ThumbUUID": "1400123456_dramon_893f5a7a4872676ae142c08acd49c18a",//视频缩略图序列号,类型为 String。后台用于索引视频缩略图的键值。无法通过该字段下载相应的视频缩略图。若需要获取该视频缩略图,请升级 IM SDK 版本至4.X。"ThumbSize": 13907,   //缩略图大小,类型为 Number,单位:字节。"ThumbWidth": 720,    //缩略图宽度。类型为 Number。"ThumbHeight": 1280,   //缩略图高度。类型为 Number。"ThumbFormat": "JPG"//缩略图格式,类型为 String,例如 JPG、BMP 等。    }}

MsgBody 消息内容实例

单一文本元素消息

单条消息中只包括一个中文本消息元素,文本内容为 hello world。

{    "MsgBody": [        {            "MsgType": "TIMTextElem",             "MsgContent": {                "Text": "hello world"            }        }    ]}

组合消息

下述的单条消息中包括两个文本消息元素和一个表情元素,消息元素顺序是文本+表情+文本。

{    "MsgBody": [        {            "MsgType": "TIMTextElem",             "MsgContent": {                "Text": "hello"            }        },         {            "MsgType": "TIMFaceElem",             "MsgContent": {                "Index": 1,                 "Data": "content"            }        },         {            "MsgType": "TIMTextElem",             "MsgContent": {                "Text": "world"            }        }    ]}
注意:

一条组合消息中只能带一个 TIMCustomElem 自定义消息元素, 其它消息元素数量无限制。

Apple Push Notification Service(APNs)相关说明

客户端推送展示格式说明

  • 未设置帐号昵称
    如果帐号没有设置昵称,APNs 推送只展示推送文本内容。单聊消息只展示“推送文本”,群组消息展示“(群名称):推送文本“。

  • 已设置帐号昵称
    如果帐号设置昵称,单聊消息展示格式为“昵称:推送文本内容”,群组消息展示格式为昵称(群名称):推送文本内容。

  • 组合消息展示格式
    对于组合消息,按顺序叠加各个消息元素的推送文本作为展示文本。下述为已设置帐户昵称的单聊消息,推送文本为"helloworld"。注意 helloworld 中间没有空格,后台按照顺序叠加,各个消息元素推送文本之间不添加任何字符。如需要在各个不同的消息元素间添加空格或其他字符,需调用方自己控制。

    {
      "MsgBody": [
          {
              "MsgType": "TIMTextElem", 
              "MsgContent": {
                  "Text": "hello"  
              }
          },
          {
              "MsgType": "TIMCustomElem",
              "MsgContent": {
                  "Data": "message",
                  "Desc": "world",
                  "Ext": "https://www.example.com",               
                  "Sound": "dingdong.aiff"
              }
          }
      ] 
    }

各类消息元素推送文本字段汇总。

MsgType 的值类型消息元素推送文本
TIMTextElem文本消息。Text 字段。
TIMLocationElem地理位置消息。中文版离线推送文本为“[位置]”;英文版为“[Location]”。
TIMFaceElem表情消息。中文版离线推送文本为“[表情]”;英文版为“[Face]”。
TIMCustomElem自定义消息。Desc 字段。

昵称和群名称 REST API 设置接口

设置帐号昵称 REST API 接口:设置资料
设置群名称 REST API 接口:修改群组基础资料

高级应用

自定义推送声音,APNs 下发扩展字段.

利用自定义消息元素 TIMCustomElem,Sound 填写自定义声音文件名称, Ext 填写下发的扩展字段,请求扩展字段可以从 APNs 推送 PayLoad 中的 Ext 字段获取。

{    "To_Account": "lumotuwe5",     "MsgRandom": 121212,     "MsgBody": [        {            "MsgType": "TIMCustomElem",             "MsgContent": {                "Data": "other information",                 "Desc": "hello",                 "Ext": "www.qq.com",                 "Sound": "dingdong.aiff"            }        },         {            "MsgType": "TIMTextElem",             "MsgContent": {                "Text": "world"            }        }    ]}

客户端收到 APNs 推送 JSON Payload 为:

{    "aps": {        "alert": "Nickname:helloworld",   //各个消息元素推送文本顺序叠加"badge": 5,                               "sound": "dingdong.aiff"//对应 TIMCustomElem 中 Sound 字段    },     "ext": "www.qq.com"//对应 TIMCustomElem 中 Ext 字段}

离线推送 OfflinePushInfo 说明

OfflinePushInfo 是专用于离线推送配置的 JSON 对象,允许配置该条消息是否关闭推送、推送文本描述内容、推送透传字符串等。使用 OfflinePushInfo 可以方便地设置离线推送信息,无需再通过 TIMCustomElem 封装实现。

注意:

如果填写了 OfflinePushInfo,那么 TIMCustomElem 中与离线推送有关的信息配置会被忽略。目前 OfflinePushInfo 适用于 APNs 推送,以及 Android 厂商推送(小米、华为、魅族、OPPO 和 vivo 推送)。

OfflinePushInfo 的格式示例如下:

{    // ..."MsgBody": [...] // 这里同 MsgBody 相关描述"OfflinePushInfo": {        "PushFlag": 0,        "Title":"这是推送标题",        "Desc": "这是离线推送内容",        "Ext": "这是透传的内容",        "AndroidInfo": {             "Sound": "android.mp3",            "OPPOChannelID": "test_OPPO_channel_id"        },        "ApnsInfo": {            "Sound": "apns.mp3",            "BadgeMode": 1,            "Title":"apns title",            "SubTitle":"apns subtitle",            "Image":"www.image.com"        }    }}

字段说明如下:

字段类型属性说明
PushFlagInteger选填0表示推送,1表示不离线推送。
TitleString选填离线推送标题。该字段为 iOS 和 Android 共用。
DescString选填离线推送内容。该字段会覆盖上面各种消息元素 TIMMsgElement 的离线推送展示文本。
若发送的消息只有一个 TIMCustomElem 自定义消息元素,该 Desc 字段会覆盖 TIMCustomElem 中的 Desc 字段。如果两个 Desc 字段都不填,将收不到该自定义消息的离线推送。
ExtString选填离线推送透传内容。
AndroidInfo.SoundString选填Android 离线推送声音文件路径。
AndroidInfo.OPPOChannelIDString选填OPPO 手机 Android 8.0 以上的 NotificationChannel 通知适配字段。
ApnsInfo.BadgeModeInteger选填这个字段缺省或者为0表示需要计数,为1表示本条消息不需要计数,即右上角图标数字不增加。
ApnsInfo.TitleString选填该字段用于标识 APNs 推送的标题,若填写则会覆盖最上层 Title。
ApnsInfo.SubTitleString选填该字段用于标识 APNs 推送的子标题。
ApnsInfo.ImageString选填该字段用于标识 APNs 携带的图片地址,当客户端拿到该字段时,可以通过下载图片资源的方式将图片展示在弹窗上。
注意:

由于 APNs 推送限制数据包大小不能超过4K,因此除去其他控制字段,建议 Desc 和 Ext 字段之和不要超过3K。

参考

Apple Push Notification Service(APNs) 苹果推送开发文档
iOS 离线消息推送配置:离线推送(iOS)

群组系统简介

群组系统是一个支持多人聊天的即时通信系统,群组系统所具备的基本能力包括:

  • 完备的 群组管理 能力:创建/解散群组、成员管理、群组资料管理、成员资料管理等。

  • 稳定可靠的消息收发能力,完善的 群组消息 管理机制:权限控制,禁言,脏词过滤,消息回调,消息漫游等。

  • 内置私有群(Private)、公开群(Public)、聊天室(ChatRoom)、音视频聊天室(AVChatRoom)和在线成员广播大群(BChatRoom)五种群组形态, 并支持根据业务需要 自定义群组形态

  • 多种群成员人数上限:


    • 私有群成员人数上限200人,公开群成员人数上限2000人,聊天室成员人数上限6000人,但此三种群组实际的群成员上限还受预付费套餐包的限制,详情请参阅 价格说明 。

    • 音视频聊天室和在线成员广播大群人数无上限,也不受预付费套餐包的限制,但您可创建的音视频聊天室数量受预付费套餐包限制,详情请参阅 价格说明 。

  • 在 Web 端,音视频聊天室和在线成员广播大群支持用户以游客身份(即不需要登录)接收消息。

注意:


  1. 音视频聊天室(AVChatRoom)和在线成员广播大群(BChatRoom)成员人数没有上限,但如果预估群成员人数会超过1万人,请提前联系 腾讯云客服 或商务工作人员申请服务资源。

  2. 目前仅私有群(Private)、公开群(Public)和聊天室(ChatRoom)具备消息漫游能力(默认7天)。如需保存更长时间,您可以在 控制台 修改消息漫游时长。延长消息漫游时长是增值服务,具体计费说明请参考 价格说明

除此之外,即时通信 IM 群组系统具备高度可定制性,具体包括:

群成员角色介绍

群组中各成员的角色及其权限如下表:

群组成员角色描述管理权限
普通成员不具备管理权限的群成员
管理员由群主任命的、协助群主来管理群组的群成员,拥有一定的管理权限
1. 修改群组基本资料
2. 将普通群成员踢出群
3. 将普通群成员禁言(即禁止其在一段时间内发言)
4. 审批其他用户的入群申请
群主即群组的创建者,在群组中拥有最高的管理权限群主具备管理员所拥有的各项权限之外,还拥有如下权限:
1. 任命/取消管理员
2. 将管理员踢出群组
3. 将管理员禁言
4. 解散群组
5. 转让群组
App 管理员具备管理 App 中所有群组权限的一种特殊身份,能力超过群主App 管理员可以不是群组中的成员,但是拥有群主具备的所有权限

群组形态介绍

群组系统当前提供五种默认群组形态:

群组形态适用场景
私有群(Private)适用于较为私密的聊天场景,群组资料不公开,只能通过邀请的方式加入,类似于微信群
公开群(Public)适用于公开群组,具有较为严格的管理机制、准入机制,类似于 QQ 群
聊天室(ChatRoom)群成员可以随意进出,组织较为松散
音视频聊天室(AVChatRoom)适用于互动直播场景,管理上与聊天室相似,但群成员人数无上限;支持以游客身份(不登录)接收消息
在线成员广播大群(BChatRoom)适用于需要向全体在线用户推送消息的场景,例如在直播系统中的“大喇叭消息”

五种群组形态分别针对不同的应用场景,故而它们支持的管理方式稍有差别, 主要差异如下:

群组操作差异

控制项私有群公开群/聊天室音视频聊天室在线成员广播大群
是否支持模糊搜索不支持不支持不支持不支持
是否支持精确搜索不支持支持支持不支持
修改群基础资料的权限普通成员群管理员 
群主
App 管理员
群主
App 管理员
App 管理员
获取群成员信息可获取全部群成员信息可获取全部成员信息只能获取最多300个群成员的信息无法获取任何群成员信息
解散群只有 App 管理员可以解散群群主和 App 管理员可以解散群群主和 App 管理员可以解散群只有 App 管理员可以解散群
说明:


  1. 模糊搜索,是指非群成员通过群名称等字段查找群组;精确搜索,是指非群成员通过群组 ID 查找群组。

  2. 对于私有群,普通成员只能修改群名称、简介、公告、群头像 URL,不能修改其他群基础资料。

  3. 获取部分群成员的信息,常用于直播大群中只需要展示部分群成员列表的场景。

群成员操作差异

控制项私有群公开群/聊天室音视频聊天室/在线成员广播大群
申请加群不允许申请加群申请加群后,公开群需要管理员审批;而聊天室无需管理员审批,直接加入申请加群后,无需要管理员审批,直接加入
邀请他人入群1.任何群成员都可邀请他人加群,且无需被邀请人同意,直接将其拉入群组中
2.创建群时,可以直接拉人入群
1.默认只有 App 管理员可以邀请他人入群
2.创建群时,可以直接拉人入群
1.不允许任何人邀请他人入群(包括 App 管理员)
2.创建群时,也不可以直接拉人入群
群主是否可退群可以。群主退出后,该群将没有群主不可以。除非通过解散群组的方式不可以。除非通过解散群组的方式
群主是否可设置管理员不可以可以不可以
移除群成员群主和 App 管理员可移除群成员群管理员、群主和 App 管理员可移除群成员不允许任何人(包括 App 管理员)移除群成员
定期移除不在线的群成员默认不开启默认不开启不支持
注意:

如果需要开启定时清理不在线成员的功能,可以根据 工单模板 提交工单进行申请,但是只会清理普通成员,不会清理群主和管理员。

群组限制差异

控制项私有群公开群聊天室音视频聊天室在线成员广播大群
成员人数上限20020006000无上限无上限
每日可净增群组数量上限100001000010000100005
App 累计可创建群组数量无上限无上限无上限请参见 价格说明5
注意:


  1. 累计可创建群组数(包括所有群组类型)是没有限制的,但如超过10万,需支付一定费用,详情请参考 套餐外超量费用 > 峰值群组数。所以建议及时解散无需继续使用的群组。

  2. 对于私有群、公开群和聊天室,实际群成员人数上限还需结合购买情况,详情请参阅 价格说明。例如,您购买了专业版,那么这三种群组形态的成员人数上限均为200人;如果您额外购买了“扩展群人数上限-6000人”,则三种群组形态的成员人数上限分别为200、2000、6000。

  3. 净增群组数量,是指创建群组数减去解散群组数。

  4. 每日净增群组数量上限10000个,是指所有形态的群组的净增数量总和不能超过10000个。

消息管理差异

控制项私有群公开群聊天室音视频聊天室在线成员广播大群
消息发送权限App 管理员和所有群成员App 管理员和所有群成员App 管理员和所有群成员App 内已导入即时通信 IM 的任意帐号App 管理员
是否支持查看入群前历史消息不支持不支持支持不支持不支持
是否支持成员变更通知支持支持不支持支持不支持
新创建群组是否需要发一条消息激活需要不需要不需要不需要不需要
是否支持管理员对群成员设置禁言不支持支持支持支持不支持
默认消息接收选项接收在线推送消息和离线推送接收在线推送消息和离线推送只接收在线推送消息只接收在线推送消息只接收在线推送消息
是否支持未读消息计数支持支持不支持不支持不支持
是否支持用户以游客身份(即不需要登录)接收群消息不支持不支持不支持支持支持
是否支持消息漫游支持支持支持不支持不支持
注意:


  1. 需要激活的群组,在群主发消息前为未激活状态,对群主以外的其他群成员不可见;而不需要激活的群组,创建后即对所有群成员可见。

  2. 被禁言的群成员,在禁言时间内无法发送群聊消息;在线成员广播大群(BChatRoom)中,只有 App 管理员可以发送消息,所以不支持禁言。

  3. 离线推送目前只有 Android(Android 离线推送)和 iOS(APNs 推送)支持。

  4. 目前仅私有群(Private)、公开群(Public)和聊天室(ChatRoom)具备消息漫游能力(默认7天)。如需保存更长时间,您可以在 控制台 修改消息漫游时长。延长消息漫游时长是增值服务,详情请参见 价格说明

批量导入与自动回收差异

控制项私有群/公开群/聊天室音视频聊天室/在线成员广播大群
允许导入群、群成员和群消息允许导入群、群成员和群消息,适用于从第三方平台迁移历史群组到即时通信 IM 时使用不允许批量导入群、群成员和群消息,只能使用现有的群、群成员和群消息
群组自动回收时间(秒)后台不会回收群组,除非群主解散,或者所有成员都退出群组后台不会回收群组,除非群主解散,或者所有成员都退出群组
注意:

如果需要开启群组回收功能,可以根据 工单模板 提交工单进行申请。配置后,将会根据群组类型清理不活跃群组(群组不活跃是指群组中既没人发言,也没有成员变更)。

群组数据结构介绍

群基础资料

字段名称类型描述备注
GroupIdString群组的唯一标识只读
群组 ID,App 内保证唯一,其格式前缀为 @TGS#。另外,App 亦可自定义群组 ID
TypeString群组形态只读
默认支持五种产品形态:Private、Public 、ChatRoom、AVChatRoom、BChatRoom, 详情请参阅上文群组形态介绍
NameString群组名称可读可写。最长30字节,不可调整
IntroductionString群组简介可读可写。最长120字节,不可调整
NotificationString群组公告可读可写。最长150字节,不可调整
FaceUrlString群组头像 URL可读可写。最长100字节,不可调整
Owner_AccountString群主 ID只读
CreateTimeInteger群组的创建时间只读
InfoSeqInteger群资料的每次变都会增加该值只读
LastInfoTimeInteger群组最后一次信息变更时间只读
LastMsgTimeInteger群组内最后发消息的时间只读
NextMsgSeqInteger群内下一条消息的 Seq只读。
群组内每一条消息都有一条唯一的消息 Seq,且该 Seq 是按照发消息顺序而连续的。从 1 开始,群内每增加一条消息,NextMsgSeq 就会增加 1
MemberNumInteger当前成员数量只读
MaxMemberNumInteger最大成员数量-
ApplyJoinOptionString申请加群选项申请加群选项包括如下几种:DisableApply 表示禁止任何人申请加入;NeedPermission 表示需要群主或管理员审批;FreeAccess 表示允许无需审批自由加入群组
注意:

群组名称、群组简介、群组公告和群组头像 URL,这四个字段的修改权限具体是:私有群中,任何群成员都可以修改;公有群和聊天室中,群管理员、群主和 App 管理员可以修改;直播聊天室中,群主和 App 管理员可以修改;在线成员广播大群中,只有 App 管理员可以修改。

群成员资料

字段名称类型描述备注
Member_AccountString群成员 ID只读
RoleString群内身份群内身份包括如下几种:Owner 群主,Admin 群管理员,Member 群成员
JoinTimeInteger入群时间只读
MsgSeqInteger该成员当前已读消息 Seq只读
MsgFlagString消息接收选项消息接收选项包括如下几种:AcceptAndNotify 表示接收并提示;AcceptNotNotify 表示接收不提示(不会触发 APNs 远程推送);Discard 表示屏蔽群消息(不会向客户端推送消息)
LastSendMsgTimeInteger最后发送消息的时间只读
NameCardString群名片可读可写

自定义群组形态

在实际使用中,如果 IM 提供的 五种群组形态 无法满足您的需求,您可以按照 工单模板 准备相关信息,然后 提交工单 申请修改现有群组形态或新增自定义群组形态。
例如,某种办公场景下使用的群组,它与公开群相似但需要群内任意成员都具有最高级别的管理权限且可以查看入群之前的历史消息。那么您可以选择以下方案:

  • 选择使用公开群, 然后 提交工单 申请开启“是否支持查看入群前历史消息”和“是否允许普通成员踢人”选项。

  • 提交工单 申请定义一种新的群组形态:OAGroup,指定公开群(Public)为参考形态,并开启“是否支持查看入群前历史消息”和“是否允许普通成员踢人”选项。

注意:

新增群组形态时,需要指定一种参考的默认群组形态。其中,在线成员广播大群(BChatRoom)不能作为参考形态。
成功配置后,除了在申请工单中指定要修改的特性外,新群组形态具有的特性与参考的默认形态是相同的。

自定义群组 ID

默认情况下,App 创建群时,即时通信 IM 会为新创建的群组分配一个默认的群组 ID。该 ID 将以 @TGS# 开头,且保证在 App 中唯一。
为了使得群组 ID 更加简单,便于记忆传播,即时通信 IM 支持 App 在通过 REST API 创建群组时自定义群组 ID。自定义群组 ID 必须为可打印 ASCII 字符(0x20-0x7e),最长48个字节,且前缀不能为 @TGS#(避免与默认分配的群组 ID 混淆)。

自定义字段

即时通信 IM 支持 App 根据业务需求,在群组和群成员两个维度上设置自定义字段。群组维度最多支持20个字段,群成员维度最多支持5个字段。利用自定义字段,App 可以将一些额外数据附加到群组之上,并可以通过现有接口进行读写操作。但请注意自定义字段设置并使用后,就无法删除。

介绍

每个自定义字段有以下特性:

  1. 为 Key-Value 形式。

  2. Key 为 String 类型,长度不超过16字节,其命名仅支持英文大小写字母、数字、下划线。

  3. Value 为用户自定义 Buffer,可以为二进制数据,群维度的 Value 长度不超过512字节,群成员维度的 Value 长度不超过64字节。

  4. 支持配置每个 Key 的最小读权限、最小写权限。

每个自定义字段的读写权限从高到低分别是:

  1. App 管理员可读/可写。

  2. 群主可读/可写。

  3. 群管理员可读/可写。

  4. 群成员可读/可写。

  5. 任何人(包括非成员)可读/可写。

例如,假设 App 需要在群组中扩展一个字段:GroupLevel,其 Value 为一个数字,用于记录该群的等级信息。假设等级信息需要 App 后台计算得出,那么该字段的最小写权限应当为“App 管理员可写”。该字段应当为群的公开资料,故而其最小读权限应当为“任何人(包括非成员)可读”。

对于 C/C++ 开发者,如果需要存储的 Value 是数字,建议将其存储为数字的字符串形式,而非其二进制形式(例如,当存储的数字是1时,建议存储字符串“1”,而非二进制数据 0x01)。对于自定义字段,即时通信 IM 后续会扩展出更多操作方式,例如对 Value 进行特定数学操作等,这些运算未来都会以基于字符串形式表示的数字来进行操作。

配置方法

这两个维度的自定义字段,都可以通过即时通信 IM 控制台进行配置。
配置群成员维度的自定义字段,需要说明要为哪种群组形态新增自定义字段。但对于 AVChatRoom、BChatRoom 以及参考这两种群组形态设置的自定义群组形态,因为不存储所有群成员的资料,所以不支持群成员维度的自定义字段。
“自己的读写权限”是指对于自己本人的群成员维度自定义字段值,自己是否有读写权限。例如,某一个群成员维度的自定义字段是“MemberLevel”(表示成员在群组中的等级),成员一般可以读取但却无权修改自己的等级,因此自己的权限是“可读&不可写”。

自定义回调

第三方回调是 App 实现特殊需求的重要方式之一,为用户提供了自定义行为的能力。
即时通信 IM 群组系统支持多种回调,具体参见 第三方回调简介以及 回调命令列表

即时通信 IM 默认配置了以下群组形态:私有群(Private)、公开群(Public)、聊天室(ChatRoom)、音视频聊天室(AVChatRoom)和在线成员广播大群(BChatRoom),详细请参阅 群组形态介绍

针对群组,可进行以下操作:

群组操作说明备注
创建群组创建一个新的群组,可指定群组类型,群组名称以及要加入的用户列表,创建成功后返回群组 ID,可通过群组 ID 获取收发消息等每个 App 每天净消耗群组上限为10000个。
转让群组进行群组转让,更换群主App 管理员可以通过 REST API 转让群组,除此之外只有群主可以转让群组。
解散群组解散 App 上创建的某个群组,群组被解散时,群组原有成员均会收到解散群组的系统消息App 管理员可调用 REST API 接口解散任意群组。
私有群/在线成员广播大群:群内任何人都无法解散群组。
公开群/聊天室/音视频聊天室:只有群主可以解散群组。
注意:


  • 创建群组时,即时通信 IM 会分配默认群组 ID,该群组 ID 以@TGS# 开头。但也支持用户指定群组 ID,详情请参阅 自定义群组 ID

  • 创建群组之后,群主所在终端会收到创建群组系统消息,目的在于保持多终端群组同步(一个终端创建群组之后,所有终端都能立即感知到该群已被创建)。

群组资料管理

群组资料是指单个群组维度的属性,包括群名称、简介、公告、群主等,以及群组维度自定义字段。

群资料管理说明备注
获取群组资料拉取群组的基本资料,如果想拉取自定义资料,可通过设置拉取字段的接口进行设置群成员获取群组资料:成员获取本群组资料;
非群成员获取群组资料:非群成员获取群组资料只能获取公开信息;
获取本人在群里的资料:可以获取本人在所有群内的资料,也可以获取单个群内本人在群里的资料;
获取群内某个人的资料:直播大群只能获得部分成员的资料,包括群主、管理员和部分群成员
修改群组资料可修改群组名称、群组简介、群组公告、群组头像、群名片,修改加群选项、群纬度自定义字段、用户群内身份、群成员维度自定义字段和接收群消息选项等信息目前 App 可以在控制台上自助配置群名称、简介、公告、头像 URL 的变更回调。如果需要启用其他群资料(包括群维度的自定义字段)的变更回调,请 提工单 申请

群成员/群组管理

群成员管理包括以下两个方面:

  • 获取/修改自己在群组中的信息,这些信息仅仅可以由用户自己获取/设置,例如消息接收选项等。

  • 获取/修改其他群成员的信息,包括群成员的身份、入群时间、最后发消息时间、群名片以及群成员维度的自定义资料。

群成员管理说明备注
获取群成员资料获取自己或其他群成员的信息可获取群成员的身份、入群时间、最后发消息时间、群名片,以及群成员维度的自定义资料
修改群成员资料群主、管理员或成员均可修改相应的群成员资料群主或者管理员修改其他群成员的资料,包括修改群内身份(设置/取消管理员)、禁言、修改群名片、群成员维度的自定义字段等。
群成员主动修改自己在群内的资料,包括消息接收选项、群名片、群成员维度的自定义字段等
邀请加群邀请加群是希望将其他用户拉入某一群组中私有群中,任何群成员都可以邀请他人入群, 且无需被邀请人同意直接加入群中;
对于公开群、聊天室,默认只有 App 管理员能够邀请其他用户加群;
而对于音视频聊天室和在线成员广播大群,则不允许任何人邀请他人加群
申请加群申请加群即用户通过 IM SDK 主动加入某一群组的动作私有群不允许申请加群,会直接返回错误;
对于其他内置群组类型,申请加群的处理结果,由群资料中的 ApplyJoinOption 字段决定的
删除群组成员删除群组成员是群主或者群管理员将群成员从群组中移除的操作当管理员或群主将用户从群组中删除之后,被删除的用户会收到被移出群组的系统消息,群内其他成员也会收到该用户被移出群组的事件消息
主动退群主动退群是群内成员主动发起退群操作群成员主动退群之后,主动发起退群操作的用户会收到主动退群系统消息,群内其他成员会收到该成员退出群组的事件消息
获取用户所加入的群组拉取当前用户加入的所有群组列表,返回的信息只包含部分基本信息详细群组信息可以根据群成员获取群组资料功能进行获取
群未决信息列表群组未决信息泛指所有需要审批的群相关的操作可拉取群未决列表、上报群未决已读、处理群未决信息(同意或拒绝)
获取 App 中的所有群组可获取 App 中的所有群组仅 App 管理员才能获取 App 中的所有群组,普通用户无权限

接口调用频率限制

群组系统

接口后台调用限制特别说明
创建群组单 App 限制100次/秒单个 App 每天净增群组限制10000 个,单个 App 最多可拥有1亿个群组,但当总群组数量超过10万时,需要付费使用,详细价格说明请参见 价格说明
添加群组成员单 App 限制100次/秒一次最多支持添加100个成员,单个用户最大可加入1000个群组,具体请参见 产品价格
删除群组成员单 App 限制100次/秒一次请求最多可删除500个成员
修改群成员资料单 App 限制100次/秒-
获取用户加入的群组单 App 限制100次/秒如果用户加入的群组超过5000个,该用户只能拉取到最先加入的5000个群组
查询用户在群组中的身份单 App 限制100次/秒一次请求最多支持查询500个帐号
批量禁言单 App 限制100次/秒一次请求最多可禁言500个帐号
批量取消禁言单 App 限制100次/秒一次请求最多可取消500个帐号的禁言
发送普通消息单 App 限制100次/秒单个群的默认发送频率限制为40条/秒,单条消息长度限制为9000字节。如果5分钟内同一发送者的两条消息的随机值(Random 参数)相同,后面那条消息将被当做重复消息而丢弃
发送系统通知单 App 限制100次/秒-
导入群消息单 App 限制100次/秒单次最多可导入20条消息,要求按消息时间戳递增的顺序导入,消息时间戳必须大于建群时间且小于当前时间,否则失败
导入群成员单 App 限制100次/秒音视频聊天室和在线成员广播大群不支持导入群成员,一次请求最多支持导入500个成员
拉取群漫游消息单 App 限制100次/秒音视频聊天室和在线成员广播大群不支持漫游消息;其它类型群组默认支持七天的漫游消息
查询 App 中的所有群组单 App 限制100次/秒-
获取群组消息资料单 App 限制100次/秒-
获取群成员详细资料单 App 限制100次/秒-
修改群组基础资料单 App 限制100次/秒-
解散群组单 App 限制100次/秒-
获取群组被禁言用户列表单 App 限制100次/秒-
转让群组单 App 限制100次/秒-
导入群基础资料单 App 限制100次/秒-
设置群成员未读消息计数单 App 限制100次/秒-
删除指定用户发送的消息单 App 限制100次/秒-
设置全局禁言单 App 限制100次/秒-
查询全局禁言单 App 限制100次/秒-
查询 App 自定义脏字单 App 限制100次/秒-
添加 App 自定义脏字单 App 限制100次/秒自定义脏字总数最多不超过5000个
删除 App 自定义脏字单 App 限制100次/秒-

资料系统

接口后台调用限制特别说明
设置资料单 App 限制100次/秒资料支持标配字段及自定义字段,其中自定义字段的关键字,必须是英文字母,且长度不得超过8字节,自定义字段的值最长不能超过500字节
拉取资料单 App 限制100次/秒-

关系链系统

接口后台调用限制特别说明
拉取最近联系人-当前普通用户最多保存100个最近联系人
添加好友单 App 限制100次/秒当前单个用户支持3000个好友,添加好友时未决消息最多支持100条;好友分组最多支持32个,每个分组的名称最长30字节;好友备注最长支持96字节
添加黑名单单 App 限制100次/秒当前单个用户最多允许的黑名单人数为1000人
导入好友单 App 限制100次/秒如果使用批量导入好友,最多只能导入1000个好友
删除好友单 App 限制100次/秒-
删除所有好友单 App 限制100次/秒-
校验好友单 App 限制100次/秒-
拉取好友单 App 限制100次/秒-
删除黑名单单 App 限制100次/秒-
拉取黑名单单 App 限制100次/秒-
校验黑名单单 App 限制100次/秒-

单聊消息系统

接口后台调用限制特别说明
单聊消息单发单 App 限制100次/秒这里建议同一对帐号发消息,频率不要超过10条/秒,超过在线可收到,但离线只保存10条/秒,超过的会丢弃;单条消息长度不能超过9000字节
单聊消息群发单 App 限制100次/秒一次性针对最多500个用户进行单发消息。单条消息长度不能超过9000字节
单聊消息导入单 App 限制100次/秒-

帐号系统

接口后台调用限制特别说明
获取用户在线状态单 App 限制100次/秒一次请求最多可以查询500个用户的状态
UserSig 失效接口单 App 限制1000次/秒-
单个帐号导入单 App 限制1000次/秒用户名长度不超过32字节
批量帐号导入单 App 限制10次/秒单个用户名长度不超过32字节,单次最多导入100个用户名

其它

接口后台调用限制
REST API

业务特性限制

功能特性限制类型限制说明
消息内容内容长度单聊、群聊消息,单条消息最大长度限制为8000字节,超过此长度会被系统丢弃
发送文件文件大小当前文件消息中,SDK 端的单个文件最大支持28M,WebSDK 端的单个文件最大支持20M
系统消息数量及存储时间最多保存100条,存储时长不超过7天
多终端在线在线模式目前支持设置四种多段登录形式:单端登录(仅允许 Windows、Web、Android 或 iOS 单端登录)、双端登录(允许 Windows、Android 或 iOS 单端登录,同时允许与 Web 端同时在线)、三端登录(允许 Android 或 iOS 单端登录,同时允许与 Windows 和 Web 端同时在线)、多端同时在线(允许 Windows、Web、Android 或 iOS 多端或全端同时在线登录)。您可以在即时通信 IM 控制台 进行修改
UserID命名限制用户帐号,长度不超过32字节,不支持使用特殊字符,建议使用英文字母或数字
UserSig有效期用户密码,即时通信 IM 后台 SDK 默认接口生成的签名有效期为180天
单聊/群聊消息消息漫游时长目前单聊消息及群聊消息,含私有群(Private)、公开群(Public)和聊天室(ChatRoom),具备消息漫游能力(默认7天)。如需保存更长时间,您可以在即时通信 IM 控制台 修改消息漫游时长。延长消息漫游时长是增值服务,具体计费说明请参见 价格说明
群组资料资料内容限制群名称最长30字节,群简介最长240字节,群公告最长300字节,群头像 URL 最长100字节,群名片最大不超过50个字节
群组成员成员数量最大群成员数量:私有群是200人,公开群是2000人,聊天室是10000人,音视频聊天室和在线成员广播大群无限制
自定义群组 IDID 命名限制自定义群组 ID 必须为可打印 ASCII 字符(0x20-0x7e),最长48个字节,且前缀不能为 @TGS#(避免与默认分配的群组 ID 混淆)
群组维度自定义字段字段限制群组维度最多支持20个自定义字段,字段 Key 为 String 类型,长度不超过16字节,其命名仅支持英文大小写字母、数字、下划线;字段 Value 为用户自定义 Buffer,可以为二进制数据,群维度的 Value 长度不超过512字节
群成员维度自定义字段字段限制群成员维度最多支持5个自定义字段,字段 Key 为 String 类型,长度不超过16字节,其命名仅支持英文大小写字母、数字、下划线;字段 Value 为用户自定义 Buffer,可以为二进制数据,群成员维度的 Value 长度不超过64字节


  • 名称: 即时通信IM
  • 关键词: 即时通信价格,即时通信IM,即时通讯,IM系统集成,腾讯云,免费即时通信