Android SDK

# Android SDK

智齿客服 SDK 为企业提供了一整套完善的智能客服解决方案。智齿客服 SDK 既包含客服业务逻辑，也提供交互界面；企业只需简单两步，便可在 APP 中集成智齿客服，让 APP 拥有 7 * 24 小时客服服务能力。

管理员可以在后台「首页 - 在线客服 - 设置 - 对接渠道设置 - 添加渠道」添加 APP，然后按照本接入文档说明完成 SDK 对接。

智齿客服 SDK 具有以下特性：

在线咨询：咨询机器人、咨询人工客服、留言、帮助中心。
指定技能组接待。
排队或客服不在线时引导用户留言。
机器人优先模式下隐藏转人工按钮，N 次机器人未知问题问题是显现。
客服满意度评价：用户主动满意度评价+用户退出时询问评价。
传入用户资料：用户对接 ID + 基础资料 + 自定义字段。
传入商品来源页：来源页标题 + 来源页 URL。
高度自定义 UI。

# 文档介绍

# ● 集成流程示意图

# ● 文件说明

SDK 文件包含 SDK 源码包（sobotsdk_x） 、 Demo 源码（Sobot_Sdk_Demo_Android） 、和 Doc 相关说明文档。

文件	描述
ZCSobotApi	该文件提供接入功能
Information	启动配置信息参数类

# 集成方式

# ● 导入集成

下载链接：Android_SDK (opens new window)

导入 Module ：

解压下载的智齿 Android_SDK_XXX.zip 文件，将 sobotsdk-x 或者 sobotsdk-mall-x 文件直接复制到您的项目中，然后 Build --> Clean Project 一下，之后在 build.gradle 中添加项目依赖。

完成上述步骤之后 build.gradle 中如下所示：

dependencies {
      implementation project(':sobotsdk-x')
      implementation 'com.squareup.okhttp3:okhttp:4.4.0'
      implementation 'androidx.appcompat:appcompat:1.0.0'
      implementation 'androidx.recyclerview:recyclerview:1.0.0'
      //目前支持常见的几种图片加载库，必须在下面的图片加载库中选择一个添加依赖
      //implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
      //implementation 'com.squareup.picasso:picasso:2.71828'
      //implementation 'com.facebook.fresco:fresco:2.6.0'
      implementation 'com.github.bumptech.glide:glide:4.9.0'
}

1
2
3
4
5
6
7
8
9
10
11

【注意】

如果您使用的是 picasso 框架，从 3.3.0 版本开始,SDK 默认支持 2.71828 及以上版本。

如果您使用的是 glide v4 框架，从 3.3.0 版本开始,SDK 默认支持 4.9.0 及以上版本。

如果您使用的 3.3.0 之前的SDK版本，但是glide v4 又使用的是4.9.0以上版本，您还需要单独添加依赖： 'com.sobot.chat:sobotsupport-glidev4:2.1'。

如果您想使用自己的图片加载方法，可以使用以下方法：SobotBitmapUtil.setImageLoader(new SobotImageLoader() {}); 使用这种方式后,网络图片显示时就不会走 SDK 内部的图片加载方式了。

# ● 依赖集成

普通版：最新版本地址 (opens new window)

//依赖里边的加号也可以替换成具体的版本号，具体版本号可以点击上边的链接获取
implementation  'com.sobot.chat:sobotsdk_x:3.+'

1
2

电商版：最新版本地址 (opens new window)

//依赖里边的加号也可以替换成具体的版本号，具体版本号可以点击上边的链接获取
implementation  'com.sobot.chat:sobotsdk-mall-x:3.+'

1
2

如果后端工作台账号没有升级到V6,请使用4.0.0（不含）以下的版本。

在 build.gradle 中如下所示：

dependencies {
      implementation 'com.sobot.chat:sobotsdk_x:3.+'
      implementation 'com.squareup.okhttp3:okhttp:4.4.0'
      implementation 'androidx.appcompat:appcompat:1.0.0'
      implementation 'androidx.recyclerview:recyclerview:1.0.0'
      //目前支持常见的几种图片加载库，必须在下面的图片加载库中选择一个添加依赖
      //implementation 'com.nostra13.universalimageloader:universal-image-loader:1.9.5'
      //implementation 'com.squareup.picasso:picasso:2.71828'
      //implementation 'com.facebook.fresco:fresco:2.6.0'
      implementation 'com.github.bumptech.glide:glide:4.9.0'
}

1
2
3
4
5
6
7
8
9
10
11

【注意】如果您使用的是 picasso 框架，从 3.3.0 版本开始,SDK 默认支持 2.71828 及以上版本。

如果您使用的是 glide v4 框架，从 3.3.0 版本开始,SDK 默认支持 4.9.0 及以上版本。

如果您使用的 3.3.0 之前的SDK版本，但是glide v4 又使用的是4.9.0以上版本，您还需要单独添加依赖： 'com.sobot.chat:sobotsupport-glidev4:2.1'。

混淆相关：

参照混淆文件（Android_SDK_x.x.x\Sobot_Sdk_Demo_Android\sobotsdkdemo\proguard-rules.pro）中的混淆配置添加混淆规则。

-keep class com.sobot.** {*;}

注意：使用的图片框架需要自己配置混淆。

【注意】为保持移动端两端方法名一致，方便对接，2.8.5 版本后 SobotApi 类改名 ZCSobotApi ，部分方法名更改，但是原有 SobotApi 的方法都可继续使用。

# 功能说明

# ● 域名设置

域名说明：

默认 SaaS 平台域名为: https://api.sobot.com。
如果您是腾讯云服务，请设置为: https://www.soboten.com。
如果您是本地化部署，请使用自己的部署的服务域名。

示例代码：

【注意：设置域名一定要在所有接口请求之前设置，即在初始化之前就必须设置完。】

SobotBaseUrl.setApi_Host("域名");

# ● 获取 Appkey

登录智齿科技管理平台 (opens new window) 获取，如图

# ● 初始化

# 1. 普通版

初始化参数和调用方式：

【注意：启动智齿 SDK 之前，需要调用初始化方法 initSobotSDK，否则将无法启动 SDK。】

接口：

/**
* 初始化sdk
* @param applicationcontext 上下文  必填
* @param appkey  用户的 appkey  必填 如果是平台版用户需要传总公司的 appkey
* @param partnerid     用户的唯一标识，不能传一样的值，可以为空
*/
ZCSobotApi.initSobotSDK(Context application,String appkey,final String partnerid);

//2.8.5 以前版本方法
SobotApi.initSobotSDK(Context application,String appkey,final String partnerid);

1
2
3
4
5
6
7
8
9
10

示例代码：

private void initSobotApp() {  
      ZCSobotApi.initSobotSDK(your application,"your appkey", "");
}

1
2
3

# 2. 电商版

初始化参数和调用方式：

【注意：启动智齿 SDK 之前，需要调用初始化方法 initPlatformUnion 和 initSobotSDK，否则将无法启动 SDK。】

接口：

/**
* 初始化平台 ID
* @param applicationcontext 上下文  必填
* @param platformUnionCode   平台 ID  必填  请联系对应的客服申请
* @param platformSecretkey 平台标识 秘钥 请联系对应的客服申请
*/
ZCSobotApi.initPlatformUnion(Context application, String platformUnionCode,String platformSecretkey);

//2.8.5 以前版本方法
SobotApi.initPlatformUnion(Context application, String platformUnionCode,String platformSecretkey);

//商户对接 ID （仅电商版适用，如果没有 app_key 则必须提供）
//info.setCustomer_code("商户id");

1
2
3
4
5
6
7
8
9
10
11
12
13

接口（可选）:

//设置溢出商城主站公司 ID
ZCSobotApi.setFlow_Company_Id(context,"your flowCompanyId");
//设置溢出商城主站公司技能组 ID
ZCSobotApi.setFlow_GroupId(context,"your flowGroupId");
//设置是否溢出到主商户 flowType  0-不溢出 , 1-全部溢出，2-忙碌时溢出，3-不在线时溢出,默认不溢出
ZCSobotApi.setFlow_Type(context,"your flowType");

//2.8.5 以前版本方法
SobotApi.setFlow_Company_Id(context,"your flowCompanyId");
SobotApi.setFlow_GroupId(context,"your flowGroupId");
SobotApi.setFlow_Type(context,"your flowType");

1
2
3
4
5
6
7
8
9
10
11
12

示例代码：

private void initApp() { 
     ZCSobotApi.initSobotSDK(your application, getResources().getString(R.string.sobot_appkey), "");
     // initPlatformUnion() 在 initSobotSDK() 之后调用
     // platformUnionCode  平台 ID
     ZCSobotApi.initPlatformUnion(your application, "your platformUnionCode", ""); 
}

1
2
3
4
5
6

# 3. 权限说明

SDK 使用了 3 个高敏权限（文件存储、麦克风、相机）。权限使用情况说明表：

权限	涉及该权限的功能
文件存储	给客服发送语音消息；加号里边图片、视频、拍摄、文件；留言上传图片、视频；
麦克风	给客服发送语音消息；加号里边拍摄录制视频；
相机	加号里边拍摄；留言拍照；

这些高敏权限只是在上边表中涉及的功能中使用到，使用时动态检测申请，用户同意后才能继续；没有这些高敏权限也不影响 SDK 的其他功能的正常使用。
如果需要在申请权限之前告诉用户该权限的用途，可以使用这个方法弹出权限用途提示框。

# ● 启动智齿页面

# 1. 启动智齿页面

普通版本和电商版本启动方式一样。

接口

Information info = new Information();
//appkey 必传
info.setApp_key("Your appkey");
/**
* @param context 上下文对象
* @param information 初始化参数
*/
ZCSobotApi.openZCChat(context, information);

//2.8.5 以前版本方法
SobotApi.startSobotChat(context, information);

1
2
3
4
5
6
7
8
9
10
11

示例代码：

Information info = new Information();
// appkey 必填 
info.setApp_key(et_appkey.getText().toString());
//注意：用户唯一标识，不能传入一样的值，选填，最大长度限制为300
info.setPartnerid("");
//用户昵称，选填
info.setUser_nick("");
//用户姓名，选填
info.setUser_name("");
//用户电话，选填
info.setUser_tels("");
//用户邮箱，选填
info.setUser_emails("");
//自定义头像，选填
info.setFace("");
//用户QQ，选填
info.setQq("");
//用户备注，选填
info.setRemark("");
//访问着陆页标题，选填
info.setVisit_title("");
//访问着陆页链接地址，选填
info.setVisit_url("");
ZCSobotApi.openZCChat(context, info);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

如有特殊需求，SDK 还提供了以 Fragment 嵌入的方式集成会话界面，开发者可以更灵活的使用 SDK。示例代码如下（也可参考 SobotChatActivity 中 Fragment 的实现)。

Bundle informationBundle = new Bundle();
informationBundle.putSerializable(ZhiChiConstant.SOBOT_BUNDLE_INFO, info);
SobotChatFragment fragment = SobotChatFragment.newInstance(informationBundle);
FragmentManager fm = getSupportFragmentManager();
FragmentTransaction transaction = fm.beginTransaction();
// containerId 为 ViewGroup 的 resId
transaction.replace(containerId, fragment);
try {
    transaction.commitAllowingStateLoss();
} catch (Exception e) {
}

1
2
3
4
5
6
7
8
9
10
11

# 2. 启动商家列表（仅电商版）

/**
 * 启动商家列表
 *
 * @param context 上下文对象
 * @param uid 用户唯一标识 与information中传的uid一致
 */
ZCSobotApi.openZCChatListView(Context context,String uid);

//2.8.5 以前版本方法
SobotApi.startMsgCenter(Context context,String uid)

1
2
3
4
5
6
7
8
9
10

设置消息中心item回调：

SobotOption.sobotConversationListCallback = new SobotConversationListCallback(){
   @Override
   public void onConversationInit(Context context,Information info) {
     //点击会话列表中的单个会话，启动聊天页面
     //由于默认的启动方式无法获取客服聊天的配置，因此需要手动设置此回调
     /**
      *  例如：
      *  用户昵称，选填
      *  info.setUser_nick("");
      *  .....
      *  ZCSobotApi.openZCChat(context, info);
      **/
   }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 3. 启动客户服务中心

Information info = new Information();
info.setApp_key("Your AppKey");  //分配给App的的密钥

//2.9.3 新增客服中心电话按钮,电话号码和显示文案都不为空才能显示
info.setHelpCenterTel("18510000000");//电话号码
info.setHelpCenterTelTitle("联系电话");//打电话按钮显示文案

/**
* @param context 上下文对象
* @param information 初始化参数
*/
ZCSobotApi.openZCServiceCenter(context, information);

//2.8.5 以前版本方法
SobotApi.openSobotHelpCenter(context, information);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

效果图如下：

# ● 结束会话

用户在应用中退出登陆时可以调用 SDK 的注销操作（在切换账号时调用），该操作会通知服务器进行推送信息的解绑，避免用户已退出但推送依然发送到当前设备的情况发生。

当用于用户退出登录时调用以下方法：

【注意：调用此方法会造成通道连接断开，此时用户将无法再收到消息。】

/**
* @param context 上下文对象
*/
ZCSobotApi.outCurrentUserZCLibInfo(context);

//2.8.5 以前版本方法
SobotApi.exitSobotChat(context);

1
2
3
4
5
6
7

# ● 机器人客服

# 1. 对接指定机器人

在后台获取机器人编号：

在 SDK 代码中配置：

//设置机器人编号
info.setRobotCode("your robot code");

//设置机器人编号对应的别名  2.8.6 新增
//指定别名和指定的编号 ID 效果一样
info.setRobot_alias("your robot alias");

1
2
3
4
5
6

# 2. 自定义接入模式

根据自身业务的需要，可进行以下初始化参数配置，控制接入模式：

//默认false：显示转人工按钮。true：智能转人工
info.setArtificialIntelligence(false);
//当未知问题或者向导问题显示超过(X)次时，显示转人工按钮。
//注意：只有ArtificialIntelligence参数为true时起作用
info.setArtificialIntelligenceNum(X);
//是否使用语音功能 true使用 false不使用   默认为true
info.setUseVoice(true);
//是否使用机器人语音功能 true使用 false不使用 默认为false,需要付费才可以使用
info.setUseRobotVoice(false);
//客服模式控制 -1不控制 按照服务器后台设置的模式运行
//1 仅机器人 2 仅人工 3 机器人优先 4 人工优先
info.setService_mode(-1);
//设置机器人模式下输入关键字转人工
HashSet<String> tmpSet = new HashSet<>();
tmpSet.add("转人工");
tmpSet.add("人工");
info.setTransferKeyWord(tmpSet);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

# 3. 自定义转人工事件

SDK 可以配置转人工拦截器，在转人工前做一些额外的逻辑处理，例如自定义技能组选择 Dialog。

1.设置拦截器

SobotOption.transferOperatorInterceptor = new SobotTransferOperatorInterceptor() {
    @Override
    public void onTransferStart(final Context context, final SobotTransferOperatorParam param) {
        //do something
    }
};

1
2
3
4
5
6

2、修改转人工参数 SobotTransferOperatorParam，以下为可修改参数介绍：

//技能组 ID 
String groupId;
//技能组名称
String groupName;
//转人工后是否提示
boolean isShowTips;
//商品卡片信息
ConsultingContent consultingContent;

1
2
3
4
5
6
7
8

3、使用转人工参数主动调用转人工接口：

/**
 * 外部主动调用转人工
 * @param context
 * @param param 转人工参数        
 */
ZCSobotApi.connectCustomerService(context, param);

//2.8.5 以前版本方法
SobotApi.transfer2Operator(context, param);

1
2
3
4
5
6
7
8
9

# 4. 设置转人工溢出

注意：如果设置了指定客服或者指定技能组接待，则溢出配置不生效。

1.配置参数对象示例

Information info = new Information();
//设置溢出技能组或客服，最多四层,
List<SobotTransferAction> datas = new ArrayList<>();
//例如:设置专员客服接待；溢出规则和技能组一样
SobotTransferAction firstData = new SobotTransferAction.ServiceBuilder()
        .conditionIntelligentudgement()
        .overflow()
        .designatedServiceId("d679e5b8d45b484e9475a2ca051b44a0")//专员客服 ID
        .ServiceBuilder();
//例如:贵宾技能组
SobotTransferAction guibinData = new SobotTransferAction.Builder()
        .designatedSkillId("ae654754311e4fa59sdfdsafdsffc")
        .conditionIntelligentudgement()
        .overflow()
        .Build();

//例如:vip技能组
SobotTransferAction vipData = new SobotTransferAction.Builder()
        .designatedSkillId("ae654754311e4fa590b0e3a4298672fc")
        .conditionIntelligentudgement()
        .overflow()
        .Build();
//例如:普通技能组
SobotTransferAction data = new SobotTransferAction.Builder()
        .designatedSkillId("a71100c5463d42bfb467762bccfef511")
        .conditionIntelligentudgement()
        .overflow()
        .Build();
datas.add(firstData);
datas.add(guibinData);
datas.add(vipData);
datas.add(data);
JSONArray jsonArray = GsonUtil.praseList2Json(datas);
info.setTransferAction(jsonArray.toString());

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34

2.配置参数说明

①、设置是否溢出
//设置溢出
overflow()
//设置不溢出
no_overflow()
②、设置指定的技能组
designatedSkillId("技能组id")
   设置指定的客服
designatedServiceId("客服id")


③、设置溢出条件
//指定客服组时：技能组无客服在线
conditionServiceOffline()
//指定客服组时：技能组所有客服忙碌
conditionServiceBusy()
//指定客服组时：技能组不上班
conditionServiceOffWork()
//指定客服组时：智能判断
conditionIntelligentudgement()

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20

# 5. 机器人咨询模式下可隐藏加号菜单栏的按钮

//隐藏留言功能，人工和机器人模式下都会隐藏 true 隐藏,false 显示,默认false
info.setHideMenuLeave(true);
//隐藏评价功能 true 隐藏,false 显示,默认false 
info.setHideMenuSatisfaction(true);

1
2
3
4

# 6. 指定常见问题引导

//2.9.2 新增 不同场景进入可以配置 faqid 指定机器人对应的常见问题引导
info.setFaqId("robot faqid");

1
2

# ● 人工客服

# 1. 对接指定技能组

在后台获取技能组编号：

在 SDK 代码中配置技能组 ID：

//预设技能组编号
info.setGroupid("your groupId");
//预设技能组名称，选填
info.setGroup_name("your groupName");

1
2
3
4

注意：此字段可选，如果传入技能组 ID,那么 SDK 内部转人工之后不在弹技能组的选择框，直接跳转到传入 ID 所对应的技能组中。

# 2. 对接指定客服

在后台获取指定客服 ID ：

在 SDK 代码中设置：

//转接类型(0-可转入其他客服，1-必须转入指定客服)
info.setTranReceptionistFlag(1);
//指定客服id
info.setChoose_adminid("your Customer service id");

1
2
3
4

注意：

choose_adminid ：指定对接的客服，如果不设置，取默认。

tranReceptionistFlag ：设置指定客服之后是否必须转入指定客服 0 ：可转入其他客服， 1：必须转入指定客服，注意：如果设置为1 ，当指定的客服不在线，不能再转接到其他客服。

# 3. 设置用户自定义资料和自定义字段

开发者可以直接传入这些用户信息，供客服查看。

在工作台自行配置所需要显示的字段，配置方法如下图：

//设置用户自定义字段,key必须是后端字段对应的ID
Map<String,String> customerFields = new HashMap<>();
customerFields.put("weixin","your wechat");
customerFields.put("weibo","your weibo");
customerFields.put("sex","女");
customerFields.put("birthday","2017-05-17");
info.setCustomer_fields(customerFields);

1
2
3
4
5
6
7

用户自定义资料

方式一：Map方式

//自定义用户料
Map<String, String> customInfo = new HashMap<>();
customInfo.put("资料", "aaaaa");
info.setParams(customInfo);

1
2
3
4

方式二：Json方式

//自定义用户料 字符串必须是json 格式，不然可能出现不显示的情况
 info.setParams("{\"title\":\"标题\",\"url\":\"https://www.baidu.com\"}");

1
2

效果图如下：

# 4. 设置转接成功后自动发消息

SDK 可以设置转接成功后自动发消息,(2.9.3 新增)可设置是否每次进入聊天页面都自动发送一次，默认只发送一次。

//发送文字消息
//设置发送模式 
//SobotAutoSendMsgMode.Default  默认 不发送
//SobotAutoSendMsgMode.SendToRobot  只给机器人发送
//SobotAutoSendMsgMode.SendToOperator   只给人工客服发送
//SobotAutoSendMsgMode.SendToAll   全部发送
//setIsEveryTimeAutoSend 是否每次进入聊天页都发送
info.setAutoSendMsgMode(SobotAutoSendMsgMode.SendToAll.setContent("your msg").setIsEveryTimeAutoSend(false));

//2.8.6 新增转人工成功后可发送文字、图片、视频、文件(只限人工模式下),需要设置文件本地路径和发送类型
//SobotAutoSendMsgMode.ZCMessageTypeText   文本(默认)
//SobotAutoSendMsgMode.ZCMessageTypePhoto  图片
//SobotAutoSendMsgMode.ZCMessageTypeFile   文件
//SobotAutoSendMsgMode.ZCMessageTypeVideo  视频
String path = CommonUtils.getSDCardRootPath() + File.separator + "2.jpg";
//path =  "发送内容";
//path =  CommonUtils.getSDCardRootPath() + File.separator + "3.mp4";
//path = CommonUtils.getSDCardRootPath() + File.separator + "1.txt";
info.setAutoSendMsgMode(SobotAutoSendMsgMode.SendToOperator.setContent(path).setAuto_send_msgtype(SobotAutoSendMsgMode.ZCMessageTypePhoto));

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 5. 设置指定客户排队优先接入

SDK 可以设置当前用户排队优先，当此用户进入排队状态时，将会被优先接待。

//设置排队优先接入 true:优先接入  false:默认值，正常排队
info.setIs_Queue_First(true);

1
2

# 6. 设置服务总结自定义字段

SDK 可以配置服务总结自定义字段，可以使客服更快速的对会话进行服务总结。

1、获取自定义字段 ID

2、设置服务总结自定义字段 (转人工支持传入服务总结参数)

//服务总结自定义字段
Map<String, String> summaryInfo = new HashMap<>();
summaryInfo.put("your keyId", "your value");
info.setSummary_params(summaryInfo);

1
2
3
4

# 7. 设置多轮会话接口参数

在使用多轮会话功能时,每一个接口我们都会传入 uid 和 mulitParams 两个固定的自定义参数，uid 是用户的唯一标识，mulitParams 是自定义字段 json字符串、如果用户对接了这两个字段，我们会将这两个字段回传给第三方接口、如果没有我们会传入空字段。

//多轮会话自定义参数
info.setMulti_params("{\"key1\",\"val1\"}");

1
2

# 8. 商品的咨询信息并支持直接发送消息卡片，仅人工模式下支持

在用户与客服对话时，经常需要将如咨询商品或订单发送给客服以便客服查看。咨询对象目前最多支持发送5个属性(title,imgUrl,fromUrl,describe,lable)，其中(title,fromUrl)为必填字段，如下以商品举例说明：
//咨询内容
ConsultingContent consultingContent = new ConsultingContent();
//咨询内容标题，必填
consultingContent.setSobotGoodsTitle("XXX超级电视50英寸2D智能LED黑色");
//咨询内容图片，选填 但必须是图片地址
consultingContent.setSobotGoodsImgUrl("http://www.li7.jpg");
//咨询来源页，必填
consultingContent.setSobotGoodsFromUrl("www.sobot.com");
//描述，选填
consultingContent.setSobotGoodsDescribe("XXX超级电视 S5");
//标签，选填
consultingContent.setSobotGoodsLable("￥2150");
//转人工后是否自动发送
consultingContent.setAutoSend(true);
//3.0.3 新增 每次返回再次进入聊天页面是否都重新发送 true 每次都发，false 只发一次，默认只发一次 
consultingContent.setEveryTimeAutoSend(false);
//启动智齿客服页面 在Information 添加,转人工发送卡片消息
info.setConsultingContent(consultingContent);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

效果图如下：

# 9. 发送订单卡片，仅人工模式下支持,订单卡片点击事件可拦截

用法一：启动智齿客服时，自动发送订单卡片消息。

List<OrderCardContentModel.Goods> goodsList = new ArrayList<>();
goodsList.add(new OrderCardContentModel.Goods("苹果", "https://img.sobot.com/chatres/66a522ea3ef944a98af45bac09220861/msg/20190930/7d938872592345caa77eb261b4581509.png"));
goodsList.add(new OrderCardContentModel.Goods("苹果1111111", "https://img.sobot.com/chatres/66a522ea3ef944a98af45bac09220861/msg/20190930/7d938872592345caa77eb261b4581509.png"));
goodsList.add(new OrderCardContentModel.Goods("苹果2222", "https://img.sobot.com/chatres/66a522ea3ef944a98af45bac09220861/msg/20190930/7d938872592345caa77eb261b4581509.png"));
goodsList.add(new OrderCardContentModel.Goods("苹果33333333", "https://img.sobot.com/chatres/66a522ea3ef944a98af45bac09220861/msg/20190930/7d938872592345caa77eb261b4581509.png"));
OrderCardContentModel orderCardContent = new OrderCardContentModel();
//订单编号（必填）
orderCardContent.setOrderCode("zc32525235425");
//订单状态
//待付款:1 待发货:2 运输中:3  派送中:4  已完成:5  待评价:6 已取消:7
orderCardContent.setOrderStatus(1);

//2.9.7 版本新增自定义订单状态名称 只有订单状态是0时才有效，其他值还按照原有逻辑
//orderCardContent.setOrderStatus(0);
//orderCardContent.setStatusCustom("您的自定义状态");                 

//订单总金额(单位 分)
orderCardContent.setTotalFee(1234);
//订单商品总数
orderCardContent.setGoodsCount("4");
//订单链接
orderCardContent.setOrderUrl("https://item.jd.com/1765513297.html");
//订单创建时间
orderCardContent.setCreateTime(System.currentTimeMillis() + "");
//转人工后是否自动发送
orderCardContent.setAutoSend(true);
//3.0.3 新增 每次返回再次进入聊天页面是否都重新发送 true 每次都发，false 只发一次，默认只发一次 
orderCardContent.setEveryTimeAutoSend(false);
//订单商品集合
orderCardContent.setGoods(goodsList);
//订单卡片内容
info.setOrderGoodsInfo(orderCardContent);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32

用法二：转人工后，加号中可添加一个订单按钮，点击后给客服发送一条订单消息。

final String ACTION_SEND_ORDERCARD = "sobot_action_send_ordercard";
ChattingPanelUploadView.SobotPlusEntity ordercardEntity = new ChattingPanelUploadView.SobotPlusEntity(ResourceUtils.getDrawableId(getApplicationContext(), "sobot_ordercard_btn_selector"), ResourceUtils.getResString(getApplicationContext(), "sobot_ordercard"), ACTION_SEND_ORDERCARD);
tmpList.add(ordercardEntity);
SobotUIConfig.pulsMenu.operatorMenus = tmpList;
//sSobotPlusMenuListener 只能有一个，否则，下边的会覆盖上边的(例如：加号中
//同时自定义添加位置和订单按钮后，可根据action 判断点击的是哪个按钮，做对应的处理)
SobotUIConfig.pulsMenu.sSobotPlusMenuListener = new SobotPlusMenuListener() {
    @Override
    public void onClick(View view, String action) {
        if (ACTION_SEND_ORDERCARD.equals(action)) {
            Context context = view.getContext();
            List<OrderCardContentModel.Goods> goodsList = new ArrayList<>();
            goodsList.add(new OrderCardContentModel.Goods("苹果", "https://img.sobot.com/chatres/66a522ea3ef944a98af45bac09220861/msg/20190930/7d938872592345caa77eb261b4581509.png"));
            OrderCardContentModel orderCardContent = new OrderCardContentModel();
            //订单编号（必填）
            orderCardContent.setOrderCode("zc32525235425");
            //订单状态
            //待付款:1 待发货:2 运输中:3 派送中:4 已完成:5 待评价:6 已取消:7
            orderCardContent.setOrderStatus(1);

            //2.9.7 版本新增自定义订单状态名称 只有订单状态是0时才有效，其他值还按照原有逻辑
            //orderCardContent.setOrderStatus(0);
            //orderCardContent.setStatusCustom("您的自定义状态");   

            //订单总金额(单位是分)
            orderCardContent.setTotalFee(1234);
            //订单商品总数
            orderCardContent.setGoodsCount("4");
            //订单链接
            orderCardContent.setOrderUrl("https://item.jd.com/1765513297.html");
            //订单创建时间
            orderCardContent.setCreateTime(System.currentTimeMillis() + "");
            //转人工后是否自动发送
            orderCardContent.setAutoSend(true);
            //3.0.3 新增 每次返回再次进入聊天页面是否都重新发送 true 每次都发，false 只发一次，默认只发一次 
            orderCardContent.setEveryTimeAutoSend(false);
            //订单商品集合
            orderCardContent.setGoods(goodsList);
            ZCSobotApi.sendOrderGoodsInfo(context, orderCardContent);
        }
    }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

配置订单卡片拦截，也可使用 ZCSobotApi.setNewHyperlinkListener(）进行拦截；setOrderCardListene 拦截后 setNewHyperlinkListener 就不会在拦截了。

ZCSobotApi.setOrderCardListener(new SobotOrderCardListener() {
    @Override
    public void onClickOrderCradMsg(OrderCardContentModel orderCardContent) {
        ToastUtil.showToast(getApplicationContext(), "点击了订单卡片" );
    }
});

1
2
3
4
5
6

效果图如下：

# 10. 查看商户客服是否正在和用户聊天 (仅电商版可用)

/**
 * 判断当前用户是否正在与当前商户客服聊天
 *
 * @param appkey 当前商户的appkey
 * @return true 表示正在与当前商户客服聊天
 *           false 表示当前没有与所选商户客服聊天
 */
ZCSobotApi.isActiveOperator(appkey);

1
2
3
4
5
6
7
8

# 11. 设置用户是否是 vip 和用户 vip 级别

//可在启动智齿客服时设置
//指定客户是否为vip，0:普通 1:vip
info.setIsVip("1");
//通过名称设置vip级别;vip级别可在智齿管理端（系统设置>自定义字段>客户字段）中编辑，拿到等级对应的 ID 或者名称
info.setVip_level("尊贵");

1
2
3
4
5

# 12. 设置用户自定义标签

//可在启动智齿客服时设置
//用户标签可在智齿管理端（系统设置>自定义字段>客户字段）中编辑，拿到用户标签对应的 ID 或者名称
//可添加多个用户标签，多个标签 ID 或者名称之间用,分割
info.setUser_label("明星,记者");

1
2
3
4

# 13. 转人工后可隐藏“+”号菜单栏中的按钮

//隐藏留言功能，人工和机器人模式下都会隐藏 true 隐藏,false 显示,默认false
info.setHideMenuLeave(true);
//隐藏留言功能，只有人工模式下会隐藏 true 隐藏,false 显示,默认false
info.setHideMenuManualLeave(true);
//隐藏评价功能 true 隐藏,false 显示,默认false
info.setHideMenuSatisfaction(true);
//隐藏图片功能 true 隐藏,false 显示,默认false
info.setHideMenuPicture(true);
//隐藏视频功能 true 隐藏,false 显示,默认false
info.setHideMenuVedio(true);
//隐藏文件功能 true 隐藏,false 显示,默认false
info.setHideMenuFile(true);
//隐藏拍摄功能 true 隐藏,false 显示,默认false
info.setHideMenuCamera(true);

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# ● 留言工单相关

# 1. 工作台设置留言界面

在工作台可以设置留言界面

# 2. 留言页面用户信息自定义配置

留言中的邮箱、电话、附件这三个参数的校验和显示逻辑可在pc端console页面配置。

# 3. 跳转到留言页面

/**
 * 跳转到留言界面
 *
 * @param context   上下文  必填
 * @param info     用户的appkey  必填 如果是平台用户需要传总公司的appkey
 * @param isOnlyShowTicket true只显示留言记录界面，false 请您留言和留言记录界面都显示
 */
ZCSobotApi.openLeave(Context context,Information info,boolean isOnlyShowTicket);

//2.8.5 以前版本方法
SobotApi.startToPostMsgActivty(Context context,Information info,boolean isOnlyShowTicket);

1
2
3
4
5
6
7
8
9
10
11

示例代码：

Information info = new Information();
info.setApp_key(et_appkey.getText().toString());/* 必填 */
//工单技能组
info.setLeaveMsgGroupId("6576d173af904d97b1d5d01a11cc66f5");
Map<String,String> map=new HashMap<>();
//自定义字段，key和后端添加字段 ID 的对应
map.put("834b34870b2e47daa1904d8f63ee55c2","zzz");
info.setLeaveCusFieldMap(map);
//2.9.5 添加 指定留言模版id，跳转到指定的留言界面
info.setLeaveTemplateId("7800560a37784ce1be064915c8389d28");
ZCSobotApi.openLeave(SobotStartActivity.this, info, false);

1
2
3
4
5
6
7
8
9
10
11

# 4. 留言页面事件拦截

SDK 中留言可跳转到自定义页面，如有此需求，可以使用如下方法进行设置：

ZCSobotApi.setSobotLeaveMsgListener(new SobotLeaveMsgListener() {
    @Override
    public void onLeaveMsg() {
      ToastUtil.showToast(getApplicationContext(),"在这里实现方法，跳转页面");
   }
});

1
2
3
4
5
6

# 5. 已完成状态的留言详情界面的回复按钮可通过参数配置是否显示

//已完成状态的留言，是否可持续回复 true 持续回复 ，false 不可继续回复 ；
//默认 true 用户可一直持续回复
ZCSobotApi.setSwitchMarkStatus(MarkConfig.LEAVE_COMPLETE_CAN_REPLY,true);

1
2
3

# 6. 获取留言回复

/**
 * 获取未读留言回复列表，如果获取到有未读的留言回复，把最新的一条展示在通知栏中，点击通知栏通知，跳转到留言详情页面
 *
 * 如果您通过类似定时任务的方式实时获取最新的留言回复，两次请求间隔时间需大于 60s，接口才会有数据返回
 *
 * @param context   上下文  必填
 * @param partnerId 用户唯一标识 与 information 中传的 partnerid 一致
 * @param noReadLeaveReplyListener 获取未读留言回复列表回调，SobotLeaveReplyModel:单个留言回复对象
 */
ZCSobotApi.getLastLeaveReplyMessage(SobotStartActivity.this,"your partnerid", new SobotNoReadLeaveReplyListener() {
        @Override
        public void onNoReadLeaveReplyListener(List<SobotLeaveReplyModel> sobotLeaveReplyModelList) {
            if(sobotLeaveReplyModelList!=null&&sobotLeaveReplyModelList.size()>0){
            // 发送留言回复通知，点击通知栏通知后，跳转到留言详情页面
            ZCSobotApi.sendLeaveReplyNotification(SobotStartActivity.this, sobotLeaveReplyModelList.get(0), R.drawable.sobot_logo_small_icon, R.drawable.sobot_logo_small_icon);
            }
        }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18

# 7. 添加留言评价主动提醒开关

//已完成留言详情界面-未评价：返回时是否弹出服务评价窗口(只会第一次返回弹，下次返回不会再弹) 默认false(不弹)
info.setShowLeaveDetailBackEvaluate(true);

1
2

# 8. 添加留言扩展参数

//添加留言对接字段
List<SobotLeaveMsgFieldModel> leaveParamsExtends = new ArrayList<>();
//SobotLeaveMsgFieldModel 属性说明；ID:对接字段系统自动生成的 ID; Value:传递的数据;Params:显示的字段 ID，例如 city、address，与 ID 对应；数据从后端工作台配置得到
leaveParamsExtends.add(new SobotLeaveMsgFieldModel("your id", "your value", "your params"));
info.setLeaveParamsExtends(leaveParamsExtends);

//添加留言技能组
info.setLeaveMsgGroupId("your groupId");

//添加留言自定义字段，key和后端添加字段ID的对应
Map<String,String> map=new HashMap<>();
map.put("your field key","zzz");
info.setLeaveCusFieldMap(map);

1
2
3
4
5
6
7
8
9
10
11
12
13

# ● 评价

# 1. 设置评价界面

在工作台可以设置，满意度评价界面：

# 2. 导航栏左侧点击返回时是否弹出满意度评价

注意：只有用户发送过消息，满意度评价窗口才能弹出。

//点击返回时是否弹出弹窗(您是否结束会话？)
info.setShowLeftBackPop(true);
//导航栏左侧点击返回时是否弹出满意度评价。true弹出,false不弹;默认false
info.setShowSatisfaction(false);

1
2
3
4

效果图如下：

# 3. 导航栏右侧关闭按钮是否显示和点击时是否弹出满意度评价

注意：只有用户发送过消息，满意度评价窗口才能弹出。

//设置是否显示导航栏右侧关闭按钮，true显示,false隐藏;默认false
info.setShowCloseBtn(false);
//导航栏右侧点击关闭按钮时是否弹出满意度评价。true弹出,false不弹;默认false
info.setShowCloseSatisfaction(false);

1
2
3
4

# 4. 配置用户提交人工满意度评价后释放会话

/**
 * 配置用户提交人工满意度评价后释放会话
 * @param context 上下文对象
 * @param flag true 表示释放会话  false  表示不释放会话
 */
ZCSobotApi.setEvaluationCompletedExit(context,flag);

1
2
3
4
5
6

# 5. 左上角返回和右上角关闭时,人工满意度评价弹窗界面配置是否显示暂不评价按钮

/**
 * 左上角返回和右上角关闭 返回弹出评价窗口时，是否显示暂不评价按钮  默认 false (不显示)
 */
info.setCanBackWithNotEvaluation(true);

1
2
3
4

# ● 消息相关

# 1. 发送文本消息

如您的 APP 需要主动发送文本消息给客服，请使用如下代码：

/**
 * 发送文本类信息
 * @param context
 * @param content 文本内容
 */
ZCSobotApi.sendTextToUser(Context context,String content)

//2.8.5 以前版本方法
SobotApi.sendTextMsg(Context context,String content)

1
2
3
4
5
6
7
8
9
10

# 2. 设置是否开启消息提醒

当用户不处在聊天界面时，收到客服的消息，APP 可以在通知栏给出提醒。点击通知栏提醒可以跳转到聊天界面。

/**
* 设置是否开启消息提醒 默认不提醒
* @param context
* @param flag
* @param smallIcon 小图标的 ID 设置通知栏中的小图片，尺寸一般建议在 24×24
* @param largeIcon 大图标的 ID
*/
public static void setNotificationFlag(Context context,boolean flag,int smallIcon,int largeIcon);

1
2
3
4
5
6
7
8

示例代码：

//设置是否开启消息提醒
ZCSobotApi.setNotificationFlag(getApplicationContext(), true, R.drawable.sobot_logo_small_icon, R.drawable.sobot_logo_icon);

1
2

# 3. 设置离线消息

开启离线消息：

// 开启通道接受离线消息，开启后会将消息以广播的形式发送过来,如果无需此功能那么可以不做调用
ZCSobotApi.checkIMConnected(getApplicationContext(), "uid");

//2.8.5 以前版本方法
SobotApi.initSobotChannel(getApplicationContext(), "uid");

1
2
3
4
5

关闭离线消息：

// 关闭通道,清除当前会话缓存
ZCSobotApi.closeIMConnection(getApplicationContext());

//2.8.5 以前版本方法
SobotApi.disSobotChannel(getApplicationContext());

1
2
3
4
5

# 4. 注册广播、获取新收到的信息和未读消息数

注册广播后，当消息通道连通时，可以获取到新接收到的消息。

1 注册广播

/**
* action:ZhiChiConstants.sobot_unreadCountBrocast
*/
IntentFilter filter = new IntentFilter();
filter.addAction(ZhiChiConstant.sobot_unreadCountBrocast);
contex.registerReceiver(receiver, filter);

1
2
3
4
5
6

2 接收新信息和未读消息数

在 BroadcastReceiver 的 onReceive 方法中接收信息。

public class MyReceiver extends BroadcastReceiver {
  @Override
  public void onReceive(Context context, Intent intent) {
    //未读消息数
    int noReadNum = intent.getIntExtra("noReadCount", 0);
    //新消息内容
    String content = intent.getStringExtra("content");
    Bundle bundle = intent.getExtras();
    ZhiChiPushMessage message = (ZhiChiPushMessage) bundle.get("sobotMessage");
    LogUtils.i(" 未读消息数:" + noReadNum + "   新消息内容:" + content);
    LogUtils.i(" 消息对象:" + message.toString());
    unread_msg_num.setText(noReadNum + "");
  }
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14

当用户不处在聊天界面时，收到客服的消息会将未读消息数保存在本地，如果需要获取本地保存的未读消息数，那么在需要的地方调用该方法即可。如下：

/**
* @param context 上下文对象
* @param partnerid 用户唯一标识 与 information 中传的 partnerid 一致，
* @return int
*/
ZCSobotApi.getUnReadMessage(Context context,String partnerid);//如果您没有在 information 里设置这个 partnerid，请传入null。

//2.8.5以前版本方法
SobotApi.getUnreadMsg(Context context,String partnerid);

1
2
3
4
5
6
7
8
9

# 5. 发送位置消息

如您的 APP 需要发送客户的位置信息，请参照以下步骤设置(其中地图定位需要开发者自行开发)。

1、客服聊天界面配置位置发送按钮（显示在点击 “+” 按钮的菜单面板中，只在转人工后显示），代码如下：

//菜单动作 当点击按钮时会将对应action返回给callback以此作为依据，
//判断用户点击了哪个按钮，可自行定义
final String ACTION_LOCATION = "sobot_action_location";
//配置位置发送按钮
ChattingPanelUploadView.SobotPlusEntity locationEntity = new ChattingPanelUploadView.SobotPlusEntity(R.drawable.sobot_location_btn_selector, ResourceUtils.getResString(getApplicationContext(), "sobot_location"), ACTION_LOCATION);
List<ChattingPanelUploadView.SobotPlusEntity> tmpList = new ArrayList<>();
tmpList.add(locationEntity);
SobotUIConfig.pulsMenu.operatorMenus = tmpList;

1
2
3
4
5
6
7
8

2、设置位置发送按钮的回调：

//sSobotPlusMenuListener 只能有一个，否则，下边的会覆盖上边的(例如：加号中
//同时自定义添加位置和订单按钮后，可根据action 判断点击的是哪个按钮，做对应的处理)
SobotUIConfig.pulsMenu.sSobotPlusMenuListener = new SobotPlusMenuListener() {
    @Override
    public void onClick(View view, String action) {
        if (ACTION_LOCATION.equals(action)) {
            Context context = view.getContext();
            //在地图定位页面获取位置信息后发送给客服：
            SobotLocationModel locationData = new SobotLocationModel();
            //地图快照，必须传入本地图片地址，注意：如果不传会显示默认的地图图片
            locationData.setSnapshot(Environment.getExternalStorageDirectory().getAbsolutePath()  +"/1.png");
            //纬度
            locationData.setLat("40.057406655722");
            //经度
            locationData.setLng("116.2964407172");
            //标点名称
            locationData.setLocalName("金码大厦");
            //标点地址
            locationData.setLocalLabel("北京市海淀区六道口金码大厦");
            ZCSobotApi.sendLocation(context, locationData);
        }
    }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

# 6. 自定义超链接的点击事件（拦截范围：帮助中心、留言、聊天、留言记录、商品卡片，订单卡片，位置卡片）

2.8.2 之后：

// 链接的点击事件, 根据返回结果判断是否拦截 如果返回true,拦截;false 不拦截
// 可为订单号,商品详情地址等等;客户可自定义规则拦截,返回true时会把自定义的信息返回
// 拦截范围  （帮助中心、留言、聊天、留言记录、商品卡片，订单卡片）
ZCSobotApi.setNewHyperlinkListener(new NewHyperlinkListener() {
    @Override
    public boolean onUrlClick(String url) {
        //举例
        if (url.contains("baidu.com")) {
            ToastUtil.showToast(getApplicationContext(), "点击了超链接，url=" + url);
            //如果url链接是百度,拦截
            //do().....
            return true;
        }
        //举例
        if (url.contains("订单编号：123456789")) {
            ToastUtil.showToast(getApplicationContext(), "点击了超链接，url=" + url);
            //如果链接是订单卡片,拦截
            //do().....
            return true;
        }
        return false;
    }
    @Override
    public boolean onEmailClick(String email) {
        ToastUtil.showToast(getApplicationContext(), "点击了邮件，email=" + email);
        return false;
    }
    @Override
    public boolean onPhoneClick(String phone) {
        ToastUtil.showToast(getApplicationContext(), "点击了电话，phone=" + phone);
        return false;
    }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33

设置位置卡片点击事件回调 (2.9.3 新增)：

//位置卡片点击后默认优先打开百度地图，没有安装百度地图，再打开高德地图；可拦截位置卡片点击事件，自己处理
SobotOption.mapCardListener = new SobotMapCardListener() {
     @Override
     public boolean onClickMapCradMsg(Context context, SobotLocationModel locationModel) {
          if (context != null && locationModel != null) {
               ToastUtil.showCustomToast(context, "点击拦截位置卡片事件");
               //优先打开高德地图
               //StMapOpenHelper.firstOpenGaodeMap(context, locationModel);
               //优先打开百度地图
               //StMapOpenHelper.firstOpenBaiduMap(context, locationModel);
          }
       //返回true 拦截 ;返回false 不拦截
       return true;
     }
};

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

2.8.2 之前这个方法配置后会拦截所有的，不能动态拦截，建议使用新方法（setNewHyperlinkListener）：

ZCSobotApi.setHyperlinkListener(new HyperlinkListener() {
  @Override
  public void onUrlClick(String url) {
    LogUtils.i("点击了超链接，url="+url);
  }
  @Override
  public void onEmailClick(String email) {
    LogUtils.i("点击了邮件，email="+email);
  }
  @Override
  public void onPhoneClick(String phone) {
    LogUtils.i("点击了电话，phone="+phone);
  }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14

# 7. 监听当前聊天模式的变化

ZCSobotApi.setChatStatusListener(new SobotChatStatusListener() {
    @Override
    public void onChatStatusListener(SobotChatStatusMode chatStatusMode) {
        switch (chatStatusMode) {
            case ZCServerConnectRobot:
                ToastUtil.showToast(getApplicationContext(), "机器人聊天模式");
                break;
            case ZCServerConnectArtificial:
                ToastUtil.showToast(getApplicationContext(), "转人工客服聊天模式");
                break;
            case ZCServerConnectOffline:
                ToastUtil.showToast(getApplicationContext(), "已离线");
                break;
            case ZCServerConnectWaiting:
                ToastUtil.showToast(getApplicationContext(), "仅人工排队中");
                break;
        }
    }
});

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

# 8. 替换消息中手机或固话识别的正则表达式

ZCSobotApi.replacePhoneNumberPattern(String regex);

# 9. 替换消息中超链接识别的正则表达式

ZCSobotApi.replaceWebUrlPattern(String regex);

# 10. 隐藏消息列表中的时间提示

//isHide true 隐藏 ，false 显示 默认false
ZCSobotApi.hideTimemsgForMessageList( Context context, boolean isHide);

1
2

# ● 会话页面自定义 UI 设置

为了咨询客服窗口的界面风格能与集成智齿客服 SDK 的 APP 整体统一，智齿客服 SDK 提供了简洁的 UI 自定义配置选项。

# 1. 配置属性值

以下属性可在 Application 的 oncreate() 方法中设置：

//设置 toolbar右边第一个按钮是否显示，默认显示（更多 2.9.5新增）
SobotUIConfig.sobot_title_right_menu1_display = true;
//设置 toolbar右边第二个按钮是否显示，默认隐藏（评价）
SobotUIConfig.sobot_title_right_menu2_display = true;
//设置 toolbar右边第三个按钮是否显示，默认隐藏（电话 2.9.5新增）
SobotUIConfig.sobot_title_right_menu3_display = true;
//修改toolbar右边第三个按钮的图片(电话图标R.drawable.sobot_phone)
SobotUIConfig.sobot_title_right_menu3_bg = R.drawable.sobot_phone;
//设置toolbar右边第三个按钮电话需要拨打的号码
SobotUIConfig.sobot_title_right_menu3_call_num = "18510000000";

1
2
3
4
5
6
7
8
9
10

# 2. 动态控制显示标题栏的头像和昵称

默认显示只显示头像：

/**
 * 设置聊天界面头部标题栏的昵称模式
 *
 * @param context      上下文对象
 * @param title_type   titile的显示模式
 *    SobotChatTitleDisplayMode.Default:显示客服昵称(默认)
 *    SobotChatTitleDisplayMode.ShowFixedText:显示固定文本
 *    SobotChatTitleDisplayMode.ShowCompanyName:显示console设置的企业名称
 * @param custom_title 如果需要显示固定文本，需要传入此参数，其他模式可以不传
 * @param isShowTitle  是否显示标题
 */
ZCSobotApi.setChatTitleDisplayMode(getApplicationContext(),
        SobotChatTitleDisplayMode.ShowFixedText, "昵称", true);        
      
 
/**
 * 设置聊天界面标题栏的头像模式
 *
 * @param context           上下文对象
 * @param avatar_type       头像的显示模式
 * SobotChatAvatarDisplayMode.Default:显示客服头像(默认)
 * SobotChatAvatarDisplayMode.ShowFixedAvatar:显示固定头像
 * SobotChatAvatarDisplayMode.ShowCompanyAvatar:显示console设置的企业名称
 * @param custom_avatar_url 如果需要显示固定头像，需要传入此参数，其他模式可以不传
 * @param isShowAvatar      是否显示头像
 */
SobotApi.setChatAvatarDisplayMode(getApplicationContext(),SobotChatAvatarDisplayMode.Default, "https://sobot-test.oss-cn-beijing.aliyuncs.com/console/66a522ea3ef944a98af45bac09220861/userImage/20191024164346682.PNG", false);

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27

# 3. 控制横竖屏显示开关

//true 横屏 , false 竖屏; 默认 false 竖屏
ZCSobotApi.setSwitchMarkStatus(MarkConfig.LANDSCAPE_SCREEN,false);

1
2

# 4. 横屏下是否打开刘海屏开关

//只有在横屏下才有用;竖屏已适配，可修改状态栏颜色
//true 打开 ,false 关闭; 默认 false 关闭
ZCSobotApi.setSwitchMarkStatus(MarkConfig.DISPLAY_INNOTCH, true);

1
2
3

# 5. UI 样式通过同名资源替换

在客户 APP 中 colors.xml 中添加同名颜色可覆盖智齿 SDK 中的颜色样式；也可通过在主项目中同一位置放一个同名的图片资源去替换智齿 SDK 界面中的图片；也可通过在主项目中同一位置放一个同名的文字资源去替换智齿 SDK 界面中的文字。

以下是常用的颜色配置，更多颜色、图片资源可到手动集成模块中下载源码包中去查找。

    <!-- 主题色 默认绿色 -->
    <color name="sobot_color">@color/sobot_common_green</color>

    <!-- 头部开始 -->
    <!-- 头部背景 -->
    <color name="sobot_color_title_bar_bg">@color/sobot_white</color>
    <!-- 状态栏的颜色设置 -->
    <color name="sobot_status_bar_color">@color/sobot_color_title_bar_bg</color>
    <!-- 头部中间昵称颜色 -->
    <color name="sobot_color_title_bar_title">@color/sobot_common_gray1</color>


    <!-- 中间 聊天列表 -->
    <!-- 聊天背景 -->
    <color name="sobot_color_chat_bg">@color/sobot_white</color>
    <!--文本消息气泡 左侧  黑色字 -->
    <color name="sobot_left_msg_text_color">@color/sobot_common_gray1</color>
    <!--文本消息气泡 右侧 白色字 -->
    <color name="sobot_right_msg_text_color">@color/sobot_white</color>
    <!-- 超链接颜色 左边 -->
    <color name="sobot_color_link">@color/sobot_common_blue</color>
    <!-- 超链接颜色 右边 -->
    <color name="sobot_color_rlink">@color/sobot_common_yellow</color>
    <!-- 消息之间间隔 时间 颜色 -->
    <color name="sobot_color_remind_time_color">@color/sobot_common_gray2</color>
    <!-- 聊天界面提醒背景颜色-->
    <color name="sobot_listview_remind">@color/sobot_common_bg</color>
    <!-- 聊天界面提醒的字体颜色-->
    <color name="sobot_listview_remind_text_color">@color/sobot_common_gray2</color>
    <!-- 消息提醒中的超链接颜色 -->
    <color name="sobot_color_link_remind">@color/sobot_common_green</color>
    <!-- 文件消息气泡颜色 -->
    <color name="sobot_chat_file_bgColor">@color/sobot_color</color>
    <!-- 消息气泡左侧背景默认颜色 -->
    <color name="sobot_chat_left_bgColor">@color/sobot_common_gray4</color>
    <!-- 消息气泡右侧背景默认颜色 -->
    <color name="sobot_chat_right_bgColor">@color/sobot_color</color>

    <!-- 底部 -->
    <!-- 点击加号后 面板背景 -->
    <color name="sobot_color_bottom_bg">@color/sobot_white</color>
    <!-- 消息输入框 文字 颜色 -->
    <color name="sobot_color_bottom_msg_input_color">@color/sobot_common_gray1</color>
    <!-- 点击加号后 面板 按钮字体颜色 -->
    <color name="sobot_color_bottom_btn_wz_color">@color/sobot_common_gray1</color>

    <!-- 留言相关 -->
    <!--留言 导航栏切换 文字下边 横线 颜色  -->
    <color name="sobot_postMsg_nav_indicator_color">@color/sobot_color</color>
    <!--留言 导航栏切换 选中 字体 颜色  -->
    <color name="sobot_postMsg_nav_sel_tx_color">@color/sobot_common_gray1</color>
    <!--留言 导航栏切换  未选中字体 颜色  -->
    <color name="sobot_postMsg_nav_tx_color">@color/sobot_common_gray2</color>
    <!--留言引导语 超链接颜色  -->
    <color name="sobot_postMsg_url_color">@color/sobot_common_blue</color>

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55

# 6.设置夜间（深色）模式

3.3.0 版本新增

  /** 设置界面白天、夜间模式或者跟随系统，默认跟随系统
     * sdk 初始化后设置，因为每次初始化后会还原。
     * @param mode     0 / AppCompatDelegate.MODE_NIGHT_AUTO:根据当前时间在day/night主题间切换
     *                 1 / AppCompatDelegate.MODE_NIGHT_NO:白天模式
     *                 2 / AppCompatDelegate.MODE_NIGHT_YES:夜间模式
     *                 其它 / AppCompatDelegate.MODE_NIGHT_FOLLOW_SYSTEM:跟随系统
     *            
     */
ZCSobotApi.setLocalNightMode(context, int mode)；

1
2
3
4
5
6
7
8
9

# ● 其他配置

# 1. 自定义自动应答语

SDK 中的自动应答语可以在 PC 工作台进行动态设置，如果 PC 工作台的设置满足不了您的需求，那么您可以使用以下接口在代码中进行本地配置。

注意：本地设置本地优先，PC 端不在起效。

3.0.4 之后
information.setAdmin_Hello_Word( "自定义客服欢迎语");//自定义客服欢迎语,默认为空 （如果传入，优先使用该字段）
information.setRobot_Hello_Word( "自定义机器人欢迎语");//自定义机器人欢迎语,默认为空 （如果传入，优先使用该字段）
information.setUser_Tip_Word( "自定义用户超时提示语");//自定义用户超时提示语,默认为空 （如果传入，优先使用该字段）
information.setAdmin_Tip_Word("自定义客服超时提示语");//自定义客服超时提示语,默认为空 （如果传入，优先使用该字段）
information.setAdmin_Offline_Title( "自定义客服不在线的说辞");// 自定义客服不在线的说辞,默认为空 （如果传入，优先使用该字段）
information.setUser_Out_Word( "自定义用户超时下线提示语");// 自定义用户超时下线提示语,默认为空 （如果传入，优先使用该字段）

3.0.3 之前
//自定义客服欢迎语,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setAdmin_Hello_Word(getApplicationContext(), "自定义客服欢迎语");
//自定义机器人欢迎语,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setRobot_Hello_Word(getApplicationContext(), "自定义机器人欢迎语");
//自定义用户超时提示语,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setUser_Tip_Word(getApplicationContext(), "自定义用户超时提示语");
//自定义客服超时提示语,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setAdmin_Tip_Word(getApplicationContext(), "自定义客服超时提示语");
// 自定义客服不在线的说辞,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setAdmin_Offline_Title(getApplicationContext(), "自定义客服不在线的说辞");
// 自定义用户超时下线提示语,默认为空 （如果传入，优先使用该字段）
ZCSobotApi.setUser_Out_Word(getApplicationContext(), "自定义用户超时下线提示语");

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

# 2. 自定义聊天记录显示时间范围

如想设置用户只能看到 xx 天内的聊天记录，那么可以调用以下方法进行设置:

/**
 * 控制显示历史聊天记录的时间范围，最多只能显示60天内的消息,单位(分钟)
 * 不传默认会显示所有的历史记录
 * @param time  查询时间(例:100-表示从现在起前100分钟的会话)
*/
SobotApi.setScope_time(context,time);

1
2
3
4
5
6

# 3. “+” 号面板菜单扩展

客服聊天界面中点击“+”按钮后所出现的菜单面板，可以根据需求自行添加菜单，代码如下：

private void customMenu(){
    //添加扩展菜单数据
    ArrayList<ChattingPanelUploadView.SobotPlusEntity> objects = new ArrayList<>();
    /**
     * SobotPlusEntity为自定义菜单实体类
     * @param iconResId 菜单图标 drawableId
     * @param name      菜单名称
     * @param action    菜单动作 当点击按钮时会将对应action返回给callback
     *                  以此作为依据，判断用户点击了哪个按钮
     */
     objects.add(new ChattingPanelUploadView.SobotPlusEntity(R.drawable.sobot_camera_picture_button_selector, "位置", "action_location"));
     objects.add(new ChattingPanelUploadView.SobotPlusEntity(R.drawable.sobot_camera_picture_button_selector, "签到", "action_sing_in"));
     objects.add(new ChattingPanelUploadView.SobotPlusEntity(R.drawable.sobot_camera_picture_button_selector, "收藏", "action_ollection"));
     //机器人模式和人工模式下都添加数据
     //SobotUIConfig.pulsMenu.menus = objects;
     //只在人工模式下添加数据
     SobotUIConfig.pulsMenu.operatorMenus = objects;
     //设置回调
      SobotUIConfig.pulsMenu.sSobotPlusMenuListener = new SobotPlusMenuListener() {
         @Override
         public void onClick(View view, String action) {
            //action与实体类中的action对应
            ToastUtil.showToast(getApplicationContext(), "action:"+action);
         }
      };
}

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26

# 4. 调起拨号界面接口

/**
* @param phone 是传入的电话号码 context 上下文对象
*/
CommonUtils.callUp(String phone, Context context)

1
2
3
4

# 5. 智齿日志显示开关

/**
* true 显示日志信息 默认false不显示
*/
ZCSobotApi.setShowDebug(false);

//2.8.5 以前版本方法
/日志显示开关 true 打开；false 关闭；默认关闭
LogUtils.isDebug = true;
//日志显示各级别开关 true 显示；false 不显示
LogUtils.allowI = true;
LogUtils.allowD = false;
LogUtils.allowE = false;
LogUtils.allowI = false;
LogUtils.allowV = false;
LogUtils.allowI = false;

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15

# 6. 多语言支持

方式一、目前 SDK 支持英文和中文等多种语言，语言会根据当前手机语言自行切换适配，如果当前手机语言不识别，默认使用中文。

如果需要新增语言包，把支持的语言文件放入对应的语言目录下即可，例如；英文路径：sobotsdk/src/main/res/values-en/strings.xml。

说明：语言文件夹名称为 values- 的后面加上语言的标示，例如 values-en；strings.xml 名字不变。

方式二、

《客户SDK支持语言编码表》 (opens new window)

/**
 * 2.8.6 新增，使用功能需和智齿开发沟通，服务端是否有对应的语言包
 * 指定使用国际化语言包
 * @param language     指定语言编码，例如："zh-Hans"：简体中文、"en"：英文，其他语言编码参考《客户SDK支持语言编码表》
 * @param isUse        是否使用指定语言
 * @param isReDownload 是否重新下载语言包 true 重新下载，false 不重新下载,默认false
 */
ZCSobotApi.setInternationalLanguage(context,language, isUse, isReDownload);

1
2
3
4
5
6
7
8

服务端接口多语言指定(2.8.9 版本之后支持)。

/**
 * 支持语言: 简体中文:zh-Hans 英语:en 其他语言编码参考《客户SDK支持语言编码表》
 */
info.setLocale("your language");

1
2
3
4

特殊处理：
如果多语言时配置了人工评价或机器人评价标签，不支持多语言显示，可以通过如下属性隐藏显示（不影响评价功能使用，仅评价内容中缺失标签）。

//  隐藏机器人时评价标签，默认不隐藏。 true 隐藏 ；false 显示
info.setHideRototEvaluationLabels(false);

//  隐藏人工时评价标签，默认不隐藏。 true 隐藏 ；false 显示
info.setHideManualEvaluationLabels(false);

1
2
3
4
5

# 7. 时区适配

从 2.8.9 版本开始支持，默认系统北京东八区标准事件，如果需要根据手机时区动态适配，配置如下代码：

// false 默认使用东八区时区，true 自动适配手机系统设置的时区
ZCSobotApi.setSwitchMarkStatus(MarkConfig.AUTO_MATCH_TIMEZONE, false);

1
2

# 8. 弹出权限用途提示框

从 2.9.1 版本开始支持，是否在申请权限前弹出权限用途提示框，配置如下代码：

// 是否在申请权限前弹出权限用途提示框,默认 false 不弹,true 弹
ZCSobotApi.setSwitchMarkStatus(MarkConfig.SHOW_PERMISSION_TIPS_POP, false);

1
2

# 9. 智齿部分功能页面点击返回的监听（只记录不拦截），可自己添加逻辑（例如埋点）

ZCSobotApi.setFunctionClickListener(new SobotFunctionClickListener() {
   @Override
   public void onClickFunction(Context context, SobotFunctionType functionType) {
       //1:留言返回,2:会话页面返回,3:帮助中心返回,4:电商消息中心页面返回,5:电话联系客服
       LogUtils.i(functionType.toString());
   }
});

1
2
3
4
5
6
7

# 10. 安全校验

1.功能位置：在线渠道设置-渠道安全设置-安全秘钥设置-勾选“生效范围（APP)"。

2、开启生效范围 APP “安全密钥”功能后，SDK 渠道必须传 partnerid 参数。且对接时传参增加参数 “sign” 和 “createTime”，其中，sign =“MD5（app_key + partnerid + 密钥 + createTime）”，createTime 是 Unix 毫秒时间戳；secret 长度为 32 的字符串，createTime 是毫秒级时间戳。

3、传入参数后智齿会对 sign 进行解密，验证传入的 partnerid 与 sign 中传入的 partnerid 是否一致，若一致则正常接入智齿系统，若不一致则接入失败。若客户没有传 partnerid 或 sign，则视同非法用户，接入失败；若 createTime 与当前时间相差超过 5 分钟，则是为非法用户，接入失败。

4、APP “安全密钥”的功能开启和关闭，生效范围的设置是实时生效的。

//启动智齿页面时传入下边两个参数
//签名
info.setSign(your sign);
//毫秒级时间戳
info.setCreateTime(crete_time);

1
2
3
4
5

# ● Information 类说明

# 1. ID 相关

参数	类型	必填	描述
app_key	String	是	必须设置，不设置初始化不成功
choose_adminid	String	否	指定客服 ID
tranReceptionistFlag	Integet	否	指定客服转接类型， 0 可转入其他客服； 1 必须转入指定客服
partnerid	String	否	用户唯一标识
robot_code	String	否	对接机器人 ID
robot_alias	String	否	对接机器人 ID 对应的别名
faqId	String	否	常见问题参数
sign	String	否	签名 MD5 加密(app_key+partnerid+secret+create_time)
createTime	String	否	时间戳

电商版：

设置电商转人工溢出策略，以下属性与 transferaction 冲突，如果设置 transferaction，将覆盖 flow_type、flow_companyid、flow_groupid 的配置。

参数	类型	必填	描述
customer_code	String	否	商户对接id （仅电商版适用，如果没有 app_key，请提供此编码）

# 2. 客服工作台显示

参数	类型	必填	描述
user_nick	String	否	昵称
user_name	String	否	真实姓名
user_tels	String	否	用户电话
user_emails	String	否	用户邮箱
qq	String	否	qq
remark	String	否	备注
face	String	否	用户自定义头像
visit_title	String	否	接入来源页面标题
visit_url	String	否	接入的来源URL
params	String	否	用户资料
customer_fields	String	否	固定KEY的自定义字段
group_name	String	否	技能组名称
groupid	String	否	技能组编号
isVip	String	否	指定客户是否为vip
vip_level	String	否	vip等级
user_label	String	否	用户标签

# 3. 会话页面相关

参数	类型	必填	描述
service_mode	Integet	否	自定义接入模式 1 只有机器人,2 仅人工 3 智能客服-机器人优先 4 智能客服-人工客服优先
custom_title_url	String	否	聊天页顶部标题自定义图像路径
isShowLeftMsgFace	boolean	否	是否显示左侧消息的头像，默认false不显示
isShowLeftMsgNickName	boolean	否	是否显示左侧消息的昵称，默认false不显示

# 4. 其他

参数	类型	必填	描述
transferaction	String	否	转人工指定技能组溢出
summary_params	String	否	转人工自定义字段
multi_params	String	否	多轮会话自定义字段
margs	String	否	热点引导问题的扩展字段
content	String	否	自动发送商品订单信息内容
queue_first	Boolean	否	指定客户优先
isArtificialIntelligence	Boolean	否	是否智能转人工,默认 false
artificialIntelligenceNum	Integet	否	如果是只能转人工，那么未知问题或者向导问题出现多少次时，显示转人工按钮。默认是一次
isUseVoice	Boolean	否	是否使用语音功能默认 true，可以使用语音功能
isUseRobotVoice	Boolean	否	是否使用机器人语音功能默认 false，机器人不可以使用语音功能会转为文字
isShowLeftBackPop	Boolean	否	左上角返回时是否弹出(您是否结束会话？) 默认 false 不弹
isShowSatisfaction	Boolean	否	导航栏左侧点击返回时是否弹出满意度评价。默认 false，弹出，false 不弹满意度
isShowCloseSatisfaction	Boolean	否	导航栏关闭按钮关闭时是否弹出满意度评价。默认 false，弹出，false 不弹满意度。
equipmentId	String	否	设备编号
tranReceptionistFlag	Integet	否	转接类型(0 - 可转入其他客服，1 - 必须转入指定客服)
transferKeyWord	HashSet	否	转人工关键字
isCloseInquiryForm	Boolean	否	是否关闭询前表单
leaveMsgGuideContent	String	否	留言引导文案
leaveMsgGroupId	String	否	留言技能组
leaveCusFieldMap	Map	否	留言自定义字段
leaveParamsExtends	List	否	对接型字段
leaveTemplateId	List	否	留言模版 ID
hideMenuSatisfaction	Boolean	否	隐藏评价
hideMenuLeave	Boolean	否	隐藏留言
hideMenuPicture	Boolean	否	隐藏图片
hideMenuVedio	Boolean	否	隐藏视频
hideMenuCamera	Boolean	否	隐藏拍摄
hideMenuFile	Boolean	否	隐藏文件
showLeaveDetailBackEvaluate	Boolean	否	留言详情界面返回弹出服务评价窗口
canBackWithNotEvaluation	Boolean	否	弹出评价窗口时，暂不评价按钮
hideRototEvaluationLabels	Boolean	否	是否隐藏机器人评价标签
hideManualEvaluationLabels	Boolean	否	是否隐藏人工评价标签
locale	String	否	服务端接口国际化语言
helpCenterTel	String	否	帮助中心添加呼叫电话号码
helpCenterTelTitle	String	否	帮助中心电话号码按钮字段
hideMenuManualLeave	Boolean	否	仅隐藏人工状态下的留言

请在《隐私政策》中向用户告知使用智齿客服 SDK，参考条款如下：

SDK 名称：智齿客服 SDK

服务类型：客服系统

收集个人信息类型：设备及系统信息（包括操作系统类型、系统版本、APP 包名、APP 版本、设备类型、设备厂商、设备型号、网络类型）、传感器（包括加速度传感器和距离传感器）、网络身份标识信息（IP 地址）

隐私权政策链接：https://www.zhichi.com/docs/clause/sdk-clause.html

1
2
3
4
5
6

上次更新: 2024/5/14 16:23:54

← Web-JS 接入说明 Android SDK V6→