文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>云联络中心>SDK 开发指南>集成在线会话用户端 SDK>Android

Android

最近更新时间：2026-01-27 11:49:32

我的收藏

本页目录：

介绍

智能客服用户端 Android UIKit。使用此 UIKit，您可以在一天内将智能客服的能力集成到您的 Android 项目。极简接入，用智能客服为您的产品增收提效，提升用户满意度和付费转化。

效果展示



快速集成

环境与版本

Android Studio
Gradle-7.4.1
Android Gradle Plugin Version-7.0.1

步骤1：Maven 镜像设置

在项目的 settings.gradle 的 dependencyResolutionManagement 中加入以下内容：
repositories {
    google()
    mavenCentral()
    maven {
        url 'https://mirrors.tencent.com/repository/maven/thirdparty/'
    }
    gradlePluginPortal()
}

步骤2：引入 AI Desk 包

我们提供了两种方式来引入，如果不需要修改源码可直接使用 Maven 镜像的方式引入，如果需要修改源码可用源码集成的方式。
Maven 镜像集成
源码方式集成
找到 app 的 build.gradle 文件，然后在 dependencies 中添加智能客服 UIKit 的依赖。
说明：
智能客服 UIKit 的版本信息请 点击 查看。
dependencies {
    ...
    implementation "com.tencentcloud.desk:aideskcustomer:$version"
}
1. 下载 AI TDesk SDK 源码，把 aideskcustomer、deskchat、deskcommon、deskcontact、deskcore、deskcustomerserviceplugin 文件夹复制到您项目的根目录。
2. 修改项目的 settings.gradle 文件，引入 AI TDesk SDK 相关代码。
// 集成智能客服相关代码
include ':deskcore'
include ':deskcommon'
include ':deskchat'
include ':deskcontact'
include ':deskcustomerserviceplugin'
include ':aideskcustomer'
3. 找到 app 的 build.gradle 文件，然后在 dependencies 中添加 AI TDesk SDK 的依赖。
implementation project(':aideskcustomer')

步骤3：带昵称和头像登录

调用 initWithProfile 方法登录智能客服。此接口支持同时设置用户的昵称和头像，可与业务侧账号体系打通。如果您希望人工客服在工作台接待用户咨询时，能看到用户的昵称、头像等信息以提升沟通效率，请在登录时设置 nickName 和 avatar 参数。效果如下图所示：

Java
int SDKAppID = 0; // Your SDKAppID，即开通了智能客服 Desk 的应用 ID
String userID = ""; // Your userID，可复用您 app 的账号体系，或随机生成
String userSig = ""; // Your userSig，接入阶段可控制台生成，生产阶段请务必由服务端生成

// 用户昵称。设置后，用户端转人工成功时，人工客服在工作台可见。您可将用户手机号，用户来源等信息写入昵称，长度限制500字节
// 注意！设置后，即时通信 IM 同 userID 的昵称也会被更新
// 如您不希望变更，请设置为 "" 或 null
String nickName = "";

// 用户头像。设置后，用户端转人工成功时，人工客服在工作台可见
// 注意！设置后，即时通信 IM 同 userID 的头像也会被更新
// 如您不希望变更，请设置为 "" 或 null
String avatar = "";

TencentAiDeskCustomer.getInstance().initWithProfile(context, SDKAppID, userID, userSig, nickName, avatar, new AIDeskCallback() {
    @Override
    public void onSuccess() {
        startActivity(TencentAiDeskCustomer.getInstance().getCustomerServiceChatIntent(context));
    }

    @Override
    public void onError(int code, String desc) {}
});
SDKAppID 信息，可在 即时通信 IM 控制台，单击应用管理 > 创建新应用，并选择客服服务 Desk > 智能客服， 开通智能客服 后获取。


userID 信息，可本地生成一个随机的字符串，例如 test-1234。
userSig 信息，可单击 即时通信 IM 控制台 > UserSig生成校验，填写创建的 userID，即可生成 userSig。


步骤4：打开客服聊天页，发起您的第一条客服咨询

Java
startActivity(TencentAiDeskCustomer.getInstance().getCustomerServiceChatIntent(context));

高级用法

设置显示人工服务按钮

// 设置为 true 后，只有没在人工服务阶段就会显示“人工服务”按钮，在人工服务阶段会自动隐藏。
// 设置为 false 后，永远不显示“人工服务”按钮
TencentAiDeskCustomer.getInstance().setShowHumanService(true);

设置显示结束排队按钮

// 设置为 true 后，转人工排队阶段显示“结束排队”按钮
// 设置为 false 后，永远不显示“结束排队”按钮
TencentAiDeskCustomer.getInstance().setShowLeaveQueue(true);

设置显示服务评价按钮

// 设置为 true 后，进入人工服务状态就会显示“服务评价”按钮，在人工服务前会自动隐藏。
// 设置为 false 后，永远不显示“服务评价”按钮
TencentAiDeskCustomer.getInstance().setShowServiceRating(true);

设置显示结束会话按钮

// 设置为 true 后，进入人工服务状态就会显示“结束会话”按钮，在人工服务前会自动隐藏。
// 设置为 false 后，永远不显示”结束会话“按钮
TencentAiDeskCustomer.getInstance().setShowEndHumanService(true);

设置聊天窗口头像和昵称的显隐

// 显示头像(默认 true)
TencentAiDeskCustomer.getInstance().setShowAvatar(true);
// 显示昵称(默认 false)
TencentAiDeskCustomer.getInstance().setShowNickName(true);

设置机器人的头像和昵称

// 设置机器人头像
TencentAiDeskCustomer.getInstance().setRobotAvatar("https://tccc-im-agent-avatar-1258344699.cos.ap-nanjing.myqcloud.com/robot_default_avatar_3.png");
// 设置机器人昵称
TencentAiDeskCustomer.getInstance().setRobotNickName("your robot nickname");

设置人工客服的头像和昵称

说明：
仅转人工成功后，与人工客服对话时有效。
客服成员或管理员可以在智能客服管理端 > 团队管理 > 成员界面，编辑成员的昵称和头像。
如果您的应用需要区分人工客服的头像和昵称，请设置enableUnifiedMemberProfile值为 false。默认值为 true，即展示统一的人工客服的头像和昵称。如果您未在代码中设置统一的人工客服头像和昵称，则 UIKit 会使用客服号的头像和昵称进行展示。
// 设置为 false，则 UIKit 展示在智能客服管理端配置的人工客服的头像和昵称
TencentAiDeskCustomer.getInstance().setEnableUnifiedMemberProfile(false);


// 设置为 true（默认值），则 UIKit 展示设置的统一的客服头像和昵称
// 如果您未设置统一的客服头像，则展示客服号默认的头像
// 如果您未设置统一的客服昵称，则展示客服号默认的昵称
TencentAiDeskCustomer.getInstance().setMemberAvatar("https://tccc-im-agent-avatar-1258344699.cos.ap-nanjing.myqcloud.com/seat_default_avatar_2.png");
// 统一的人工客服的昵称
TencentAiDeskCustomer.getInstance().setMemberNickName("your member name");

设置消息阅读状态

// 消息阅读状态默认展示，如果您想隐藏消息阅读状态，请设置为 false
TencentAiDeskCustomer.getInstance().setShowReadStatus(false);

设置快捷入口

如果您想实现输入框上方增加快捷按钮，方便用户使用，例如增加“在线时间”，“售后查询”等，可使用 setQuickAccessItems 接口。效果如下所示：

Java
// 快捷入口
ArrayList<AIDeskQuickAccessItem> quickAccessItems = new ArrayList<>();
AIDeskQuickAccessItem quickAccessItem1 = new AIDeskQuickAccessItem();
quickAccessItem1.setTitle("联系我们");
quickAccessItems.add(quickAccessItem1);

AIDeskQuickAccessItem quickAccessItem2 = new AIDeskQuickAccessItem();
quickAccessItem2.setTitle("产品动态");
quickAccessItems.add(quickAccessItem2);
TencentAiDeskCustomer.getInstance().setQuickAccessItems(quickAccessItems);

底部快捷订单

如果您想实现打开客服会话时在聊天区域底部展示快捷订单，效果如下所示：

调用接口直接发送
展示底部快捷订单弹窗
// 客服会话启动后，通过接口发送快捷订单
// onCustomerServiceChatDidStart 可能会因为用户操作回调多次，请注意发送消息的次数
TencentAiDeskCustomer.getInstance().addListener(new AIDeskListener() {
    @Override
    public void onCustomerServiceChatDidStart() {
        AIDeskBottomQuickOrder bottomQuickOrder = new AIDeskBottomQuickOrder();
        bottomQuickOrder.setHeader("高级版智能客服（包含3个客服许可）");
        bottomQuickOrder.setDesc("¥3000/月");
        bottomQuickOrder.setPic("https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg");
        bottomQuickOrder.setUrl("https://your_url.com");
        ArrayList<Pair<String, String>> customField = new ArrayList<>();
        customField.add(new Pair<>("订单号", "11111111111111111111"));
        customField.add(new Pair<>("下单时间", "2025-07-02 16:23"));
        bottomQuickOrder.setCustomField(customField);
        TencentAiDeskCustomer.getInstance().sendCustomMessage(bottomQuickOrder.toJsonData(), false);
    }
});
AIDeskBottomQuickOrder bottomQuickOrder = new AIDeskBottomQuickOrder();
bottomQuickOrder.setHeader("高级版智能客服（包含3个客服许可），标题很长很长很长很长贼长贼长贼长贼长");
bottomQuickOrder.setDesc("¥3000/月");
bottomQuickOrder.setPic("https://cloudcache.tencent-cloud.com/qcloud/portal/kit/images/presale.a4955999.jpeg");
bottomQuickOrder.setUrl("https://your_url.com");
ArrayList<Pair<String, String>> customField = new ArrayList<>();
customField.add(new Pair<>("订单号", "11111111111111111111"));
customField.add(new Pair<>("下单时间", "2025-07-02 16:23"));
customField.add(new Pair<>("订单状态", "已完成"));
customField.add(new Pair<>("测试", "value贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长贼长"));

bottomQuickOrder.setCustomField(customField);
TencentAiDeskCustomer.getInstance().setBottomQuickOrder(bottomQuickOrder);

获取客服会话未读数

如果您的应用需要获取客服会话未读数，展示角标数或者红点以提醒用户，请参考以下代码实现。
TencentAiDeskCustomer.getInstance().addListener(new AIDeskListener() {
    @Override
    public void onUnreadCountDidChange(int unreadCount) {
        Log.i("客服会话未读数:" + unreadCount);
    }
});

设置多客服号

如果您的应用内需要多个客服号，为用户提供专属客服功能，以提高服务质量和响应速度，可用 UIKit 提供的多客服号功能实现。效果如下所示：

// 设置多客服号列表
ArrayList<String> list = new ArrayList<>(Arrays.asList("desk-1", "desk-2", "346236"));
TencentAiDeskCustomer.getInstance().setCustomerServiceIDList(list);

// 跳转至指定客服号聊天页面
startActivity(TencentAiDeskCustomer.getInstance().getCustomerServiceChatIntent(context, "346236"));

发送自定义消息

如果您的业务需要更灵活地控制客服会话，例如在用户退出客服聊天时主动结束会话，可以通过调用 sendCustomMessage 接口，发送自定义消息实现。
// 结束会话
JSONObject endServiceJson = new JSONObject();
try {
    endServiceJson.put("customerServicePlugin", 0);
    endServiceJson.put("src", "27");
} catch (JSONException e) {
    throw new RuntimeException(e);
}
TencentAiDeskCustomer.getInstance().sendCustomMessage(endServiceJson.toString(), "your customerServiceID", true);

多语言

智能客服 UIKit 会自动获取设备语言，目前已支持简体中文、繁体中文、英语、日语、韩语、西班牙语、印地语、阿拉伯语、法语、土耳其语。您也可以通过 setLanguage 接口设置语言。
// 切换为英语
TencentAiDeskCustomer.getInstance().setLanguage(context, TencentAiDeskCustomerLanguageConfig.en);

常见问题

配置混淆规则

在您的 app/proguard-rules.pro 文件中添加以下混淆规则：
-dontshrink
-dontoptimize
-keep class com.tencentcloud.tencentcloudcustomer.** { *; }
-keep class com.tencent.qcloud.** { *; }
-keep class com.tencent.imsdk.** { *; }
-keep class * implements com.tencent.qcloud.tuicore.interfaces.TUIInitializer {}
中国站
目录