tencent cloud

即时通信 IM

动态与公告
产品动态
公告
产品简介
产品概述
基本概念
应用场景
功能介绍
账号系统
用户资料与关系链
消息管理
群组相关
公众号系统
音视频通话 Call
使用限制
购买指南
计费概述
价格说明
购买指引
续费指引
停服说明
退费说明
开发指引
Demo 专区
开通服务
体验 Demo
快速跑通
下载中心
SDK & Demo 源码
更新日志
聊天互动(含 UI)
TUIKit 组件介绍
快速开始
全功能接入
单功能接入
AI 集成
构建基础界面
更多特性
定义外观
国际化界面语言
推送服务(Push)
服务概述
名词解释
开通服务
快速跑通
厂商通道
数据统计
排查工具
客户端 API
服务端 API
推送回调
高级功能
更新日志
错误码
常见问题
智能客服
功能概述
快速入门
集成指引
管理员操作手册
客服操作手册
更多实践
直播间搭建
AI 聊天机器人方案
超大娱乐协作社群
Discord 实现指南
游戏内集成 Chat 指南
类 WhatsApp Channel 搭建方案
发送红包
Chat 应对防火墙限制相关
无 UI 集成
快速开始
集成 SDK
初始化
登录登出
消息相关
会话相关
群组相关
社群话题
用户管理
离线推送
云端搜索
本地搜索
公众号
客户端 API
JavaScript
Android
iOS & macOS
Swift
Flutter
Electron
Unity
React Native
C 接口
C++
服务端 API
生成 UserSig
REST API
第三方回调
控制台指南
新版控制台介绍
创建并升级应用
基本配置
功能配置
账号管理
群组管理
公众号管理
回调配置
用量统计
资源包查看指南
实时监控
开发辅助工具
访问管理
高级功能
常见问题
uni-app 常见问题
购买相关问题
SDK 相关问题
账号鉴权相关问题
用户资料与关系链相关问题
消息相关问题
群组相关问题
直播群相关问题
昵称头像相关问题
协议与认证
服务等级协议
安全合规认证
IM 政策
隐私政策
数据隐私和安全协议
平滑迁移方案
平滑迁移完整版
平滑迁移简化版
错误码
联系我们

终端 SDK 相关问题

PDF
聚焦模式
字号
最后更新时间: 2025-11-06 16:30:48

TUIKit 源码是否支持 AndroidX?

TUIKit 最新源码已经支持 AndroidX。

出现 6013 SDK 未初始化错误?

如果出现 6013 SDK 未初始化错误,您可以尝试以下方式排查:
1. 查看是否没有登录成功就进行收发消息等其他操作;
2. 查看是否登录时被其它终端踢掉,Chat SDK 默认一个账号仅能在一个终端上登录。处理方式请参考 多终端同时登录 文档;
3. Android 请关注库文件是否未能全部加载,或是使用过程中被系统回收。

发送表情,消息列表显示为空、或者乱码?

即时通信 Chat 不提供表情包,具体的解析需要自己对齐。
表情使用有两种方式:
一种是使用 TChatFaceElem 中的 index,标识表情的索引,例如 Android 和 iOS 两端都有同一套表情图,索引2为笑脸,index=2 就表示笑脸,两端发送和接收都显示同一张索引表情图片即可。
另一种是使用 TChatFaceElem 中的 data,例如表情图片是由字符串命名,smile 表示笑脸,可在 data 中存储 smile,iOS 和 Android 两端都通过 data 作为 key 找到对应表情图片进行显示。
另外也可以两个字段都使用,如 data 表示哪一套表情,index 表示这套表情的哪个索引,可以实现类似 QQ 的多种不同表情效果。甚至可以在 data 数据中存储更为复杂的数据结构,只要多端解析规则一致即可。

翻译 IM 消息,怎么剔除表情和 @ 消息?

1. 先把输入的文本过滤一遍,提取出不需要翻译的表情或者 at 信息并缓存起来,把需要翻译的设置给接口。
2. 等翻译结果返回后,再把缓存的不需要的翻译的表情或者 at 信息一起组合起来

有时进行操作时返回错误码:10002?

在需要进行服务端验证的操作时,如果网络异常、超时或者票据切换失败,就会返回此状态码,遇到此状态码时稍后重试即可。

收发消息时,收到错误码 6200 或 6201?

返回此状态码时,是客户端在网络离线、超时或无网络访问时出现,6200 的定义为请求时没有网络,6201 的定义为响应时没有网络,遇到此状态码时,请检查网络或等待网络恢复后重试。

收发消息时返回错误码:20003?

请检查用户账号(UserID)是否已在腾讯云导入,当 UserID 无效或 UserID 未导入腾讯即时通信 Chat 时,会返回此错误码。

语音消息播放语音时返回错误码:6010?

通常情况是语音消息超过了漫游保存有效期,请求失败导致,可 延长漫游消息时间 或获取语音文件到本地播放(已过期的文件无法恢复)。但不同版本的 SDK 支持延长历史消息存储时长的消息类型不同,详情请参见 消息存储

账号鉴权时返回错误码 70001 或 70003 或 70009 或 70013?

这些状态码对应的原因是 UserID 与 UserSig 不匹配,请检查 UserID 及 UserSig 的有效性。其中,70001 定义为 UserSig 已过期,70003 定义为 UserSig 被截断导致校验失败,70009 定义为 UserSig 验证失败(可能是因为生成 UserSig 时混用了其他 SDKAppID 的密钥或私钥导致),70013 定义为 UserID 不匹配。

Web 端使用 Chat SDK 时返回错误码-2或-5?

-2:Web 端请求服务器失败,通常为网络问题,Web 端使用 HTTP Long Polling 方式向服务端请求,网络存在问题时会返回此状态码,请检查网络或重试。
-5:登录操作未完成,SDK 未获取到服务器返回的 a2key 和 tinyID 时,直接调用其他接口会出现“tinyid或a2为空”的错误提示信息和-5的错误码。

在 armeabi 平台上 SDK 报"java.lang.UnsatisfiedLinkError: No implementation found for"错误该如何处理?

拷贝 imsdk 的 aar 里面的 jni/armeabi-v7a/libImSDK.so 到源码工程的 src/main/jniLibs/armeabi 目录里,并在 build.gradle 中加载即可。

上架 App Store 时,出现 x86_64, i386 架构错误该如何解决?

该问题是由于 App Store 不支持 x86_64, i386 架构引起的,具体解决方法如下:
1. 清空项目编译缓存: 选择Product>clean,按住Alt变成 clean build Folder...,等待操作完成。
2. 剔除 App Store 不支持的 x86_64 和 i386 架构: a. 选择TARGETS>Build Phases。 b. 单击加号,选择New Run Script Phase。 c. 添加如下代码:
APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and

# removes unused architectures.

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK
do
FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)
FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"
echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS
do
echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"
lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"
EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")
done

echo "Merging extracted architectures: ${ARCHS}"
lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"
rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"
rm "$FRAMEWORK_EXECUTABLE_PATH"
mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

3. 重新打包上传。

Chat 各端 Demo/TUIKit 工程中演示用的表情包,开发者是否可以直接使用?

为尊重表情设计版权,Chat Demo/TUIKit 工程中不包含大表情元素切图,正式上线商用前请您替换为自己设计或拥有版权的其他表情包。下图所示默认的小黄脸表情包版权归腾讯云所有,您可以通过升级至 Chat 专业版 Plus 和企业版 免费使用该表情包。




会话列表同步规则?

getConversationList(拉取会话列表) 是异步拉取本地缓存的会话列表数据
1. 第一次登录成功后,IM SDK 内部会去同步服务端漫游会话和未读消息(此时本地暂无会话缓存数据)。
2. 首次登录,在漫游会话还没同步完成之前,调用 getConversationList 接口拉取本地会话列表,会返回空数据。
3. 会话同步完成后,SDK 会通过 V2TIMConversationListener -> onSyncServerFinish 回调告知上层(上层可以在收到此回调再去拉取会话)
4. 会话同步完成,对于本地缓存的会话有变更,也会通过V2TIMConversationListener ->( onNewConversation | onConversationChanged) 回调告知上层。

应用切后台或息屏情况下客户端 IM SDK 会一直处于连接状态吗?

不会,切后台或息屏都有可能导致 IM 连接断开。IM 只有长连接保活,没有进程保活。主要原因是手机厂商对于应用处于后台运行的限制策略越来越严格。
当 App 切后台或处于前台息屏,由于手机操作系统回收机制的策略原因,应用进程被挂起导致 IM 连接断开。不过应用重新切回前台,只要进程没有改变,IM SDK 感知到网络变化会自动重连(推荐:前台可配合调用 doForeground 接口,可主动触发重连)。
SDK 重连动作会触发:V2TIMSDKListener-> onConnecting、onConnectSuccess、onConnectFailed回调,告知上层当前IM连接状态。






Android 端 UIKit 接入,添加自定义消息,不需要显示默认边距,该如何操作?

方法一:在不需要显示内边距的 Holder -> layoutVariableViews 函数中,添加以下代码:
msgArea.setPaddingRelative(0, 0, 0, 0);
reactionArea.setPaddingRelative(0,0,0,0);

方法二:layoutVariableViews 函数最底部调用下面两个方法:
setMessageBubbleBackground(null);
setMessageBubbleZeroPadding();

IM SDK 是什么样的日志缓存策略?

IM SDK 的日志模块是使用了微信 MARS 的 Xlog,XLog使用流式方式对单行日志进行压缩,压缩加密后写入作为 log 中间 buffer 的 mmap 中。使用 Xlog 方案,除非 io 损坏或者磁盘没有可用空间,基本可以保证不会丢失任何一行日志。
1. 日志先写内存映射文件.mmap3。
2. 每15分钟从 mmap3 flush 一次到本地xlog文件。
3. 如果内容大于100kB,直接 Flush。
4. 结束进程重新登录也会直接 Flush。
5. 本地缓存的日志文件只会保存7天。

调用 IM SDK API 接口,报 6014 错误,请问如何优化?

6014 是比较常见的问题,例如:登录失败、被踢、主动退出登录,导致当前 IM 处于未登录状态,后续调用 IM SDK 接口未重新登录都会报 6014 错误。
我们的建议是:在上层做下兜底逻辑,例如:将 IM 所有使用的接口error回调统一处理,如遇到 6014 报错统一做下 login 操作成功后再请求一次,让用户无感知。
SDK 也有提供以下两个 API,用于 login 接口调用的判重处理,防止重复调用:
1. getLoginStatus():获取当前登录状态,如果登录状态为已登录登录中,则上层无需调用 login 接口重复登录,仅无登录状态下调用即可(特例:如果是 UserSig 过期,那么可在 UserSig 过期回调内做登录操作,无需判断登录状态)。
2. getLoginUser():获取当前已登录的 UserID,如果当前已登录的 UserID 与需要业务层登录的 UserID 不一致,可重新登录,否则过滤不处理。

IM SDK 主动获取各类资料的缓存时长是否有限制?

主动获取群资料:默认1小时缓存时长。
主动获取群成员:默认1小时缓存时长。
主动获取用户资料:默认10分钟缓存时长。

IM SDK 重连策略是怎样的?

网络状态发生变更时,IM SDK会自动重连。重连最多重试 6 次,最长要一分钟左右;如果 3 分钟左右 SDK 多种重连方式均失败则暂停继续重连,主动调用 API 接口或感知网络变化会再次触发重连。
IM SDK 有自己的一套长连接保活的逻辑,接入层一般不需要关注重连动作,正常调用接口就好。

为什么 GitHub 里下载的 Demo 的 TUI 组件代码和 pod ‘TUIXXX’ 集成的代码不一样?

GitHub 里下载的 Demo 先 pod update,再对比看看。

冷启动 App 后首次拉取好友申请列表,有一定概率会报错提示未登录,打印登录状态是登录中,是什么问题?

除获取会话列表、拉取历史消息这两个接口以外,SDK 的各项功能接口必须在登录成功后才能调用。

IM 运行报冲突:Multiple commands produce '/Users/apple/Library/Developer/Xcode/DerivedData/xxx/Build/Products/Debug-iphonesimulator/xxx.app/Frameworks/ImSDK_Plus.framework',该如何解决?

导致报冲突的原因通常是集成了两个或者以上的 IM SDK,只保留一个即可,常见情形:
1. 客户单独集成 TXIMSDK_Plus_iOS 后,又集成 TUI 组件,通过 TUI 组件又集成了 IM SDK,编译报冲突。
解决:这种情况可以将单独集成的 TXIMSDK_Plus_iOS 去掉。
2. 之前集成了 TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件,通过依赖集成进入到 TXIMSDK_Plus_iOS;后又集成了 TUICallKitTUIRoomKit 或者 TUILiveKit 等音视频相关的组件,这些组件依赖集成了 TXIMSDK_Plus_iOS_XCFramework,集成后编译也会报冲突。
解决:TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件使用 DevelopPods 源码集成 时,可以确认下 .podspec 文件是否依赖 IM SDK,比如 TUICore.podspec 里依赖的是 TXIMSDK_Plus_iOS 的话,可以改成 TXIMSDK_Plus_iOS_XCFramework(和音视频依赖的 IM SDK 统一),然后 pod update。
TUIChatTUIConversationTUICore 等非音视频相关的 TUI 组件直接 pod 拉下来的可以尝试 pod update 都更新至最新版本。

报错:Upload Symbols Failed: The archive did not include a dSYM for the ImSDK Plus.framework with the UUiDs[B8B90567-F276-334A-8937-4D327A49AB4C1. Ensure that the archive's dSYM folder includes a DWARF filefor lmSDK Plus.framework with the expected UUlDs.

Xcode 16 报的警告,不影响打包可先忽略。

iOS 端和 Android 端登录同一账号在线,Web 端和 iOS 端登录同一账号在线,接收通话邀请的场景下,一端挂断,另一端没有退出通话邀请界面,如何处理?

多端登录的处理需要客户调用 enableMultiDeviceAbility 接口才能开启,也需要 开通对应套餐包

报错 Error: The pod "TXIMSDK_Plus_iOS_XCFramework," required by the plugin "tencent_cloud_chat_push" requires a higher minimum iOS deployment version than the plugin's reported minimum version. To build, remove the plugin "tencent_cloud_chat_push", or contact the plugin's developers for assistance. Error running pod install. Error launching application on iPhone 16 Pro.

解决方法:
1. 打开编译器控制台,进入 iOS 目录:cd ios
2. 删除 Podfile.lockpod.lock 文件(如果存在)。
3. 执行pod更新命令:pod repo updatepod install --repo-update
4. 重新运行项目。
报错原因:
Flutter 中依赖的某个插件版本,本地 CocoaPods 缓存无法检测下载,需要更新。

Flutter 使用多引擎模式,当某个引擎 detach 的时候,会把 IM SDK 的所有 channel 都释放,导致所有引擎都无法使用?

IM Flutter SDK 8.7.7201 版本已优化多引擎支持。

在 iOS 上运行官网 IM Flutter Demo 报如下错误怎么办?

Swift Compiler Error(Xcode): Cannot find type 'PhoneNumber/Users/xia/.pub-cache/hosted/pub.dev/libphonenumber_plugin-.3.3/ios/Classes/SwiftLibphonenumberPlugin.swift:6:24 Could not build the application for the simulator. Error launching application on iPhone 15.

原因:iOS 项目用到了库 libphonenumber_plugin,其中依赖了 PhoneNumberKit 的最新版本。但 PhoneNumberKit 的最新版 4.0.0 是 breaking API change,其中做了改动 “renames the class PhoneNumberKit to PhoneNumberUtility“。libphonenumber_plugin 尚未针对该变动做适配,无法找到 PhoneNumberKit 而报错。
解决方法:libphonenumber_plugin 中依赖的 PhoneNumberKit 降级到旧版本 3.8.0。



Podfile 里这样改即可:


运行 iOS 模拟器时报错 CocoaPods not installed or not in valid state,但其实 CocoaPods 安装正常,是什么原因?

按照以下顺序,重新设置一下项目:
1. flutter clean
2. flutter pub get
3. Reload Android Studio
4. flutter run
点击查看 参考文档

Flutter web 运行,一开始初始化的时候就报错:

TypeError: Cannot read properties of undefined (reading 'create')
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 134:27 initTim
packages/tencent_cloud_chat_sdk/web/manager/im_sdk_plugin_js.dart 148:14 initWebTim
packages/tencent_cloud_chat_sdk/web/manager/v2_tim_manager.dart 108:21 initSDK
packages/tencent_cloud_chat_sdk/tencent_cloud_chat_sdk_web.dart 171:26 initSDK
解决方案:点击查看 参考文档

Flutter IM Demo 怎么打 Web 应用包后,在手机上运行?

点击查看 参考文档

报错 FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring project ':better_player_plus'.
> Could not create an instance of type com.android.build.api.variant.impl.LibraryVariantBuilderImpl.
> Namespace not specified. Specify a namespace in the module's build file. See https://d.android.com/r/tools/upgrade-assistant/set-namespace for information about setting the namespace.
解决方案1:升级插件版本(推荐)​​
修改:
pubspec.yaml:
dependencies:
better_player_plus: ^1.0.8
解决方案2:手动注入命名空间​
1. 找到插件的 Android 模块构建文件:
路径:<项目目录>/android/src/main/build.gradle
或通过缓存路径:C:\\Users\\你的用户名\\.gradle\\caches\\.../better_player_plus/../android/build.gradle
2. ​在 Android 块内添加命名空间:
android {
namespace "uz.shs.better_player_plus" // 具体值参考库的包名
// 其他配置...
}


IM Flutter Demo 选择 web 浏览器运行报如下错误:Finished with error: Failed to bind web development server: SocketException: Failed to create server socket (OS Error: Failed to start accept), address = localhost, port = 63480




解决方法1:打开 Android Studio 在如下截图位置添加以下内容:--web-hostname=127.0.0.1






解决方法2:如果是通过 terminal 命令工具运行,通过如下方式:flutter run -d chrome --web-hostname=127.0.0.1

运行 Flutter Demo 报关于 better_player_plus 错误?




better_player_plus 升级至 better_player_plus: ^1.0.8

Flutter IM SDK 接入后,在 Android、iOS、macOS 和 Windows 都运行正常,但仅在 Web 平台运行报错,报错内容如下:pub-cache/hosted/pub.dev/tencent_cloud_chat_sdk-8.6.7040/lib/native_im/bindings/native_imsdk_bindings_generated.dart:996:19: Error: 'Pointer' isn't a type. ffi.Pointer<ffi.Void>)>>('DartFindMessages');,该如何解决?

HarmonyOS 切后台断连,再切回前台 SDK 重连耗时久,要如何解决?

原因:因应用切回前台时,没有主动调用 IM SDK API 接口主动触发重连,导致耗时久。
解决方法:在 HarmonyOS 工程中对应位置参考以下截图对应位置添加 SDK 两个 API,用于主动触发重连。




注册 Token 失败,报错1000900010,如何解决?

参考 鸿蒙官网错误码。提醒:使用自动签名,是不行的,需改成手动签名。

集成鸿蒙推送成功了,安卓、iOS 给鸿蒙发消息,收不到推送?

其他平台发消息代码里面,要 setHarmonyCategory

TUICallKit 接入,怎么主动获取当前群聊是否正在进行“音视频通话”?

调用 getGroupAttributes() 获取群属性接口,参数二 keys:传 inner_attr_kit_info
当群内正在进行音视频通话时,群属性会记录当前群内的通话信息,包括:房间号、通话人数、通话类型 等信息,开发者自行解析获取即可。






帮助和支持

本页内容是否解决了您的问题?

填写满意度调查问卷,共创更好文档体验。

文档反馈