会话配置
会话来源
本节说明如何设置会话来源信息，帮助客服识别访客从哪个业务入口发起咨询。
功能配置
在打开客服咨询窗口或者构造 ServiceMessageFragment 时，可以通过 ConsultSource 对咨询来源、客服分配和会话行为进行配置。
构造方法说明
public ConsultSource(String uri, String title, String custom)| 字段 | 类型 | 说明 |
|---|---|---|
| uri | String | 咨询页面的uri，可以是url，也可以任意能标识来源的字符串 |
| title | String | 咨询页面的title |
| custom | String | 可自定义传入的字符串，可以为null比如商品详细信息，用户操作状态等等, 在分配客服时该字段会传递给客服 |
人工客服分配
本节说明如何指定客服、客服组或分流模板，以控制访客进入人工客服的分配逻辑。
分配客服&客服组
SDK 在 ConsultSource 增加了指定客服或者客服组的参数，开发者可以在访客进入咨询界面前就指定好要为其服务的客服，例如从订单页面打开咨询界面时为其指定售后客服，在商品页面打开时，为其指定售前客服。在 ConsultSource 中，staffId 为客服 ID，groupId 为客服组 ID，其值可以在管理后台设置页面的「访客分配」页面中找到。如果这两个参数都没有设置，则按照后台配置逻辑分配客服，如果指定了其中一个，则只会分配指定的客服或者在指定的客服分组中分配，如果指定的客服不在线，或者指定的客服分组中没有客服在线，则会提示用户客服不在线。
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| groupId | long | 指定客服分组 | 默认为0查询路径：管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-ID查询-客服及客服组ID查询 |
| staffId | long | 指定客服ID | 默认为0，如果指定了此参数，则groupId会被忽略查询路径：管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-ID查询-客服及客服组ID查询 |
| groupTmpId | long | 多入口分流模版 | 默认为0查询路径：管理端-服务中心-在线系统-设置-会话流程-会话分配-自定义链接分配-多入口分配自定义模板 |
App 侧配置示例
如果 App 不需要指定客服或客服组，只传基础来源信息即可，SDK 会按管理后台的默认分配规则进线。
ConsultSource source = new ConsultSource("product_detail", "商品详情页", null);
Unicorn.openServiceActivity(context, "在线客服", source);如果 App 已经根据业务场景判断出要进入某个客服组，例如订单售后、商品咨询，可以设置 groupId。此时会优先在该客服组内分配客服。
ConsultSource source = new ConsultSource("order_detail", "订单详情页", null);
source.groupId = 123456L;
Unicorn.openServiceActivity(context, "订单售后", source);如果 App 已经明确要指定某个客服，可以设置 staffId。同时设置 staffId 和 groupId 时，staffId 优先，groupId 会被忽略。
ConsultSource source = new ConsultSource("vip_service", "专属客服", null);
source.staffId = 10086L;
source.groupId = 123456L;
Unicorn.openServiceActivity(context, "专属客服", source);如果 App 只想指定一套多入口分流模板，可以设置 groupTmpId，让后台模板继续决定最终分配到哪个客服或客服组。
ConsultSource source = new ConsultSource("campaign_page", "活动页咨询", null);
source.groupTmpId = 123456L;
Unicorn.openServiceActivity(context, "活动咨询", source);机器人客服
本节说明机器人接待、常见问题、快捷入口和欢迎语等机器人相关配置。
机器人配置
SDK支持机器人配置
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| robotFirst | boolean | 先由机器人接待 | 默认为false，表示是否先机器人接待由后台配置如果指定了 groupId 或者 staffId 时，该参数有效。表示会先进机器人，之后如果用户转人工服务，再分配给上面指定的groupId 或者 staffId |
| robotId | long | 指定机器人ID | 机器人ID，如果开启了机器人，该参数有效如果不设置，将连接默认机器人查询路径：管理端首页- 在线客服 - 在线接入 - 网站 - 机器人开关 |
| faqGroupId | long | 机器人热门问题组 ID | 如果指定了此参数，且请求客服为机器人客服，则会下发该 ID 对应的热门问题查询路径：管理端首页 - 在线机器人 - 设置 - 导航菜单 - 常见问题 - 常见问题模版 |
| robotWelcomeMsgId | String | 机器人欢迎语 ID | 如果指定了此参数，且请求客服为机器人客服，则会下发该 ID 对应的机器人欢迎语 |
App 侧配置示例
如果希望先由机器人接待，用户转人工后再进入指定客服组或客服，可以同时设置 robotFirst 和 groupId / staffId。
ConsultSource source = new ConsultSource("faq", "智能客服", null);
source.robotFirst = true;
source.groupId = 123456L;
Unicorn.openServiceActivity(context, "智能客服", source);如果 App 需要指定机器人、热门问题组或机器人欢迎语，可以在打开会话前设置对应字段；不设置时使用后台默认配置。
ConsultSource source = new ConsultSource("help_center", "帮助中心", null);
source.robotFirst = true;
source.robotId = 123L;
source.faqGroupId = 456L;
source.robotWelcomeMsgId = "welcome_msg_id";
Unicorn.openServiceActivity(context, "帮助中心", source);常见快捷入口模版
常见快捷入口模版ID
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| shortcutTemplateId | String | 常见快捷入口模版ID | 查询路径：管理端首页 - 在线机器人 - 设置 - 导航菜单 - 常见快捷入口 |
App 侧配置示例
ConsultSource source = new ConsultSource("help_center", "帮助中心", null);
source.shortcutTemplateId = 789L;
Unicorn.openServiceActivity(context, "帮助中心", source);用户 VIP 等级
本节说明如何设置访客等级，以便后台按业务规则区分用户优先级或服务策略。
设置用户VIP等级
SDK增加设置用户 VIP 等级的功能，便于区分用户等级，允许 VIP 用户优先进线或为 VIP 用户指定专线客服，提升用户体验。
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| vipLevel | int | 用户VIP等级 | 默认为0，表示普通用户0：普通用户1-10：用户 VIP 等级 1-10 级11：通用 VIP 用户，即不显示用户等级 |
App 侧配置示例
ConsultSource source = new ConsultSource("member_center", "会员中心", null);
source.vipLevel = 3;
Unicorn.openServiceActivity(context, "会员客服", source);专属客服与客服信息
本节说明如何配置专属客服或自定义客服展示信息。
专属客服设置
SDK提供了专属客服设置，该设置只对本地生效，并且会覆盖后台的设置
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| vipStaffid | String | 专属客服的ID | 客户自定义设置 |
| prompt | String | 连接专属客服成功时候的提示语 | 客户自定义设置 |
| VIPStaffAvatarUrl | String | 专属客服头像的 url | 客户自定义设置 |
| vipStaffName | String | 专属客服的名字 | 客户自定义设置 |
| vipStaffWelcomeMsg | String | 专属客服的欢迎语 | 客户自定义设置 |
App 侧配置示例
ConsultSource source = new ConsultSource("exclusive_service", "专属客服", null);
source.vipStaffid = "staff_account";
source.vipStaffName = "专属客服";
source.VIPStaffAvatarUrl = "https://example.com/avatar.png";
source.vipStaffWelcomeMsg = "您好，我是您的专属客服";
Unicorn.openServiceActivity(context, "专属客服", source);会话入口参数
本节说明进入客服会话时可配置的扩展参数，用于控制会话入口行为。
设置允许在当前客服界面进入新客服界面
SDK支持是否使用 CLEAR_TOP 的方式启动客服界面，当用户想要在当前客服界面中进入新的客服界面时，需要把该字段设置为 true
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| forbidUseCleanTopStart | boolean | 是否使用 CLEAR_TOP 的方式 | 默认为false |
App 侧配置示例
ConsultSource source = new ConsultSource("order_detail", "订单详情页", null);
source.forbidUseCleanTopStart = true;
Unicorn.openServiceActivity(context, "在线客服", source);设置访客端IP
由于隐私合规，SDK获取IP是采用服务端方式获取，可能会存在获取不准确或获取不到的情况，如果对后台IP地址显示比较在意，请自行获取IP并传给七鱼
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| clientIpAddress | String | 访客端的 IP 地址 | 客户传入的IP地址 |
App 侧配置示例
ConsultSource source = new ConsultSource("webview_page", "活动页", null);
source.clientIpAddress = clientIpAddress;
Unicorn.openServiceActivity(context, "在线客服", source);会话生命周期配置
本节说明会话退出、排队、结束会话和评价弹出等生命周期相关配置。
控制会话过程
SDK 增加了开发者对于会话过程控制的力度，相关选项由 SessionLifeCycleOptions 提供，包括主动结束会话、退出排队、退出确认、满意度评价和界面退出监听等能力。
| 参数名 | 类型 | 参数说明 | 取值说明 |
|---|---|---|---|
| sessionLifeCycleOptions | SessionLifeCycleOptions | 对用户咨询会话的一些生命周期控制选项 | SessionLifeCycleOptions类型 |
SessionLifeCycleOptions
| 方法名 | 参数说明 | 取值说明 |
|---|---|---|
| setCanCloseSession(boolean canCloseSession) | 是否允许主动结束会话 | 设置是否允许用户主动结束会话，设置该选项后，在会话状态下，右上角会有结束会话的入口 |
| setCanQuitQueue(boolean canQuitQueue) | 是否允许主动退出排队 | 设置是否允许用户主动退出排队，设置该选项后，在排队状态下，右上角会有退出排队的入口。如果用户通过按返回键退出，会给出弹框提示 |
| setQuitQueuePrompt(String quitQueuePrompt) | 退出排队提示语 | 设置排队状态下，按返回键时给用户的提示语，该选项只有在setCanQuitQueue(boolean) 设置为 true 时才有效 |
| setCanBackPrompt(boolean canBackPrompt) | 是否允许弹出返回弹框 | 设置是否允许用户退出聊天界面时弹出结束会话弹框 |
| setCanShowEvaluation(boolean canShowEvaluation) | 是否允许弹出满意度评价 | 用户返回时弹出结束会话弹框时设置是否弹出满意度评价，该选项只有在setCanBackPrompt(boolean)设置为 true 时才有效 |
| sessionLifeCycleListener | 会话界面退出监听器 | 仅在使用 Fragment 集成时需要处理，如果使用 Activity 集成则无需处理，需要在用户退出排队时给予挽留提示，则需要在宿主 activity 触发 onBackPressed 时调用 ServiceMessageFragment 的 onBackPressed 方法 |
SessionLifeCycleListener
| 接口回调函数 | 说明 |
|---|---|
| SessionLifeCycleListener | 需要实现onLeaveSession方法 |
代码示例
SessionLifeCycleOptions lifeCycleOptions = new SessionLifeCycleOptions();
lifeCycleOptions.setCanCloseSession(boolean)
.setCanQuitQueue(boolean)
.setQuitQueuePrompt(String)
.setCanBackPrompt(boolean)
.setCanShowEvaluation(boolean);
source.sessionLifeCycleOptions = lifeCycleOptions;App 一般在打开客服前按当前入口诉求设置生命周期选项。例如订单售后入口希望允许用户主动结束会话，同时排队时返回要给出挽留提示，可以这样配置：
ConsultSource source = new ConsultSource("order_after_sale", "订单售后", null);
SessionLifeCycleOptions lifeCycleOptions = new SessionLifeCycleOptions();
lifeCycleOptions.setCanCloseSession(true)
.setCanQuitQueue(true)
.setQuitQueuePrompt("正在为您接入售后客服，确定退出排队吗？")
.setCanBackPrompt(true)
.setCanShowEvaluation(true);
source.sessionLifeCycleOptions = lifeCycleOptions;
Unicorn.openServiceActivity(context, "订单售后", source);咨询内容弹层
从 Android SDK 11.9.0 开始，App 可以在访客进入会话时展示商品或订单选择弹层。访客点击其中一项后，SDK 会将所选内容转换为商品或订单消息并发送到当前会话；点击底部按钮则直接关闭弹层。
将 ConsultationContentConfig 设置到 ConsultSource.consultationContentConfig 后，再通过标准 Activity 或 Fragment 接口打开会话。该字段为 null，或者配置中没有有效 Tab 时，SDK 不展示弹层。
弹层配置
ConsultationContentConfig 的 setter 均返回当前对象，可以链式调用；每个 setter 都有对应的 getter。
| 方法 | 参数类型 | 说明 |
|---|---|---|
| setTitle | String | 设置弹层标题 |
| setBottomButtonTitle | String | 设置底部关闭按钮文案；为空时使用 SDK 默认文案 |
| setTabs | List<ConsultationContentTab> | 设置订单或商品 Tab 列表 |
| setPriceColor | Integer | 设置价格文字颜色，使用 Android ARGB 整数；为空时使用默认颜色 |
| setHeaderBackgroundColor | Integer | 设置弹层头部背景色，使用 Android ARGB 整数；为空时使用白色 |
| setSelectedIndex | int | 设置默认选中的 Tab 下标，从 0 开始；越界时使用第一个有效 Tab |
ConsultationContentTab 用于区分订单和商品列表。
| 方法或常量 | 说明 |
|---|---|
| TYPE_ORDER | 订单 Tab，值为 1 |
| TYPE_PRODUCT | 商品 Tab，值为 2 |
| setTitle(String) | 设置 Tab 标题 |
| setType(int) | 设置 Tab 类型，只接受 TYPE_ORDER 或 TYPE_PRODUCT |
setOrders(List<ConsultationContentOrder>) | 设置订单列表，仅用于订单 Tab |
setProducts(List<ConsultationContentItem>) | 设置商品列表，仅用于商品 Tab |
ConsultationContentOrder 描述订单卡片，ConsultationContentItem 描述订单中的商品或商品 Tab 中的单个商品。
| 对象 | 方法 | 说明 |
|---|---|---|
| ConsultationContentOrder | setOrderText(String) | 设置订单编号等标题文案 |
| ConsultationContentOrder | setTimeText(String) | 设置订单时间文案 |
| ConsultationContentOrder | setItems(List<ConsultationContentItem>) | 设置订单中的商品列表 |
| ConsultationContentOrder | setAmountTitle(String)、setAmount(String) | 设置金额标题和金额 |
| ConsultationContentOrder | setStatusText(String)、setStatusColor(Integer) | 设置订单状态文案和 ARGB 颜色 |
| ConsultationContentItem | setPictureUrl(String) | 设置商品图片地址 |
| ConsultationContentItem | setTitle(String)、setSubtitle(String)、setDetail(String) | 设置商品标题、副标题和详情 |
| ConsultationContentItem | setPrice(String)、setCount(String) | 设置价格和数量文案 |
| ConsultationContentItem | setUrl(String) | 设置商品或订单卡片的跳转地址 |
代码示例
ConsultationContentItem item = new ConsultationContentItem()
.setPictureUrl("https://example.com/product.png")
.setTitle("降噪耳机")
.setSubtitle("云雾白")
.setDetail("蓝牙 5.4 / 40 小时续航")
.setPrice("¥459.00")
.setCount("x1")
.setUrl("https://example.com/products/1001");
ConsultationContentOrder order = new ConsultationContentOrder()
.setOrderText("订单编号：202607310001")
.setTimeText("2026-07-31 10:30")
.setItems(Collections.singletonList(item))
.setAmountTitle("应付金额")
.setAmount("¥459.00")
.setStatusText("待收货")
.setStatusColor(Color.parseColor("#FF911F"));
ConsultationContentTab orderTab = new ConsultationContentTab()
.setTitle("我的订单")
.setType(ConsultationContentTab.TYPE_ORDER)
.setOrders(Collections.singletonList(order));
ConsultationContentTab productTab = new ConsultationContentTab()
.setTitle("商品信息")
.setType(ConsultationContentTab.TYPE_PRODUCT)
.setProducts(Collections.singletonList(item));
ConsultationContentConfig config = new ConsultationContentConfig()
.setTitle("请选择咨询内容")
.setBottomButtonTitle("其他问题")
.setTabs(Arrays.asList(orderTab, productTab))
.setSelectedIndex(0)
.setPriceColor(Color.parseColor("#FF4D5A"))
.setHeaderBackgroundColor(Color.WHITE);
ConsultSource source = new ConsultSource("order_list", "订单列表", null);
source.consultationContentConfig = config;
Unicorn.openServiceActivity(context, "在线客服", source);Fragment 运行期间展示或更新
使用 Fragment 接入时，保留 Unicorn.newServiceFragment() 返回的 ServiceMessageFragment 实例，即可在会话页运行期间调用 showConsultationContent() 展示或更新弹层。会话页尚未显示时，SDK 会保留最近一次有效配置，并在页面恢复后展示；弹层已显示时，重复调用会刷新当前内容。
ConsultSource source = new ConsultSource("order_list", "订单列表", null);
ServiceMessageFragment serviceFragment =
Unicorn.newServiceFragment("在线客服", source, null);
getSupportFragmentManager()
.beginTransaction()
.replace(R.id.customer_service_container, serviceFragment)
.commit();
// 获取到新的订单或商品数据后，展示或更新咨询内容弹层
serviceFragment.showConsultationContent(config);这篇文档有帮助吗？