会话配置

会话来源

本节说明如何设置会话来源信息，帮助客服识别访客从哪个业务入口发起咨询。

会话来源

针对不同的会话场景，可在进入聊天页面时设置不同的会话来源信息，与客服建立联系后，客服可在会话窗口右侧访问信息-会话页查看来源信息。样例如下：

QYSource *source = [[QYSource alloc] init];
source.title = @"七鱼客服";
source.urlString = @"https://qiyukf.com/";
sessionViewController.source = source;

请注意，代码中的sessionViewController均指代由[QYSDK sharedSDK]的sessionViewController方法新建的聊天界面控制器实例。

会话来源 QYSource 提供了如下属性：

属性	类型	必须	说明
title	NSString	否	来源标题
urlString	NSString	否	来源链接
customInfo	NSString	否	来源自定义信息

人工客服分配

本节说明如何指定客服、客服组或分流模板，以控制访客进入人工客服的分配逻辑。

分配客服

若企业有多个咨询入口，为提高咨询效率，可在不同咨询入口设置对应的人工客服接待。通过配置sessionViewController的staffId属性指定人工客服，该属性是int64_t类型的，样例如下：

sessionViewController.staffId = 123456;

指定ID后，进入聊天页面时，会直接以此ID去请求对应的人工客服。

人工客服ID查询：管理端-应用-在线系统-设置-会话流程-会话分配-ID查询-客服及客服组ID查询

指定客服ID后，进入聊天页面时会默认跳过机器人客服直接连接人工客服；如果希望先连接机器人客服，转人工时再连接指定的人工客服，可通过配置如下属性：

sessionViewController.openRobotInShuntMode = YES;

默认为NO。

分配客服组

若企业有多个咨询入口，为提高咨询效率，可在不同咨询入口设置对应的人工客服组接待。通过配置sessionViewController的groupId属性指定客服组，样例如下：

sessionViewController.groupId = 123456;

指定ID后，进入聊天页面时，会直接以此ID去请求对应的客服组，服务组会随机分配客服组中可用客服接待。

客服组ID查询：管理端-应用-在线系统-设置-会话流程-会话分配-ID查询-客服及客服组ID查询

指定客服组ID后，进入聊天页面时会默认跳过机器人客服直接连接客服组内人工客服；如果希望先连接机器人客服，转人工时再连接指定的客服组，可通过配置如下属性：

sessionViewController.openRobotInShuntMode = YES;

默认为NO。

设置多入口分流模板

若企业希望针对不同入口配置该入口对应的多入口分流模板，通过设置sessionViewController的shuntTemplateId属性指定模板ID，样例如下：

sessionViewController.shuntTemplateId = 123456;

指定ID后，进入聊天页面请求人工客服时，会弹出此模板ID对应的分流入口消息。

多入口分流模板ID查询：管理端-应用-在线系统-设置-会话流程-会话分配-App分配-多入口分配

联系客服成功前输入框禁止输入

默认情况下客服页面的输入框是允许输入的，如果想要禁用，可以用下面的样例设置

sessionViewController.isForbiddenInput = YES;

设置禁用后，仅对需要重新请求客服的情况下生效，并且在成功连接客服后恢复可输入；如果上一次的会话未结束，进入客服页面，仍然不会被禁用。

机器人客服

本节说明机器人接待、常见问题、快捷入口和欢迎语等机器人相关配置。

机器人客服

分配机器人

若企业开通了机器人，且不止一个，可在聊天页面入口匹配不同机器人，提高服务效率。通过配置sessionViewController的robotId属性指定机器人，样例如下：

sessionViewController.robotId = 123456;

指定ID后，进入聊天页面时，会直接以此ID去请求对应的机器人客服。

机器人客服ID查询：管理端-应用-机器人-在线机器人

设置常见问题

用户进入机器人会话时，可以收到设置的一组常见问题，不同聊天入口可配置不同常见问题模板，提高咨询效率。通过配置sessionViewController的commonQuestionTemplateId属性指定问题模板，样例如下：

sessionViewController.commonQuestionTemplateId = 123456;

指定ID后，进入聊天页面联系客服时会带上问题模板ID参数，服务端下发对应的常见问题消息。

常见问题模板ID查询：管理端-应用-机器人-在线机器人-设置-常见问题-设置常见问题模板

设置常见快捷入口

用户进入机器人会话时，可以收到设置的一组常见快捷入口列表，通过配置sessionViewController的shortcutTemplateId属性指定问题模板，样例如下：

sessionViewController.shortcutTemplateId = 123456;

指定ID后，进入聊天页面联系客服时会带上模板ID参数，服务端下发对应的模板数据。

常见快捷入口模板ID查询：管理端-应用-机器人-在线机器人-设置-导航菜单-常见快捷入口

设置欢迎语

用户进入机器人会话时，可收到欢迎语；V5.5.0 版本后，不同聊天入口可配置不同欢迎语模板，以适应更多场景。通过配置sessionViewController的robotWelcomeTemplateId属性指定欢迎语模板，样例如下：

sessionViewController.robotWelcomeTemplateId = 123456;

指定ID后，进入聊天页面联系客服时会带上欢迎语模板ID参数，服务端下发对应的欢迎语消息。

机器人欢迎语模板ID查询：管理端-应用-机器人-在线机器人-设置-基础设置-引导语设置-欢迎语-手机端-设置

用户 VIP 等级

本节说明如何设置访客等级，以便后台按业务规则区分用户优先级或服务策略。

设置用户VIP等级

sessionViewController提供访客 VIP 等级设置，NSInterger类型，等级的划分和取值范围SDK不做定义，由用户自己决定：

sessionViewController.vipLevel = 1;

默认为非VIP。

专属客服与客服信息

本节说明如何配置专属客服或自定义客服展示信息。

设置客服信息

V4.6.0 版本之后，新增自定义人工客服信息功能，配置完成后该入口人工客服的昵称、头像、接入语等均会被设置的信息替换。样例如下：

QYStaffInfo *staffInfo = [[QYStaffInfo alloc] init];
staffInfo.staffId = @"123456";
staffInfo.nickName = @"七鱼客服";
staffInfo.iconURL = @"客服头像链接";
staffInfo.accessTip = @"七鱼客服为您服务";
staffInfo.infoDesc = @"系统提示：当前用户选择了七鱼客服";
sessionViewController.staffInfo = staffInfo;

客服信息QYStaffInfo类提供了如下属性：

属性	类型	必须	说明
staffId	NSString	是	客服ID，限制20字符
nickName	NSString	否	客服昵称，限制20字符
iconURL	NSString	否	客服头像URL
accessTip	NSString	否	接入提示，限制50字符
infoDesc	NSString	否	客服信息描述

请注意，必须配置staffId信息，且应保证标识唯一性，用以区分不同客服信息。昵称、头像、接入提示若没有配置则按原逻辑显示。客服信息描述字段infoDesc用于接入人工客服后隐式向客服发送消息的文本，访客端无感知。

#import <QYBiz/QYConsultationContent.h>

QYSessionViewController *sessionVC = [[QYSDK sharedSDK] sessionViewController];

QYConsultationContentConfig *config = [[QYConsultationContentConfig alloc] init];
config.title = @"请选择咨询内容";
config.bottomButtonTitle = @"暂不咨询";
config.priceColor = [UIColor redColor];
config.headerBackgroundColor = [UIColor whiteColor];
config.selectedIndex = 0;
config.tabs = @[orderTab, productTab];

[sessionVC presentConsultationContentWithConfig:config];

// 再 push 或 present 会话页
[self.navigationController pushViewController:sessionVC animated:YES];

参数说明

QYConsultationContentConfig参数如下：

属性	类型	说明
title	NSString	弹层标题。
bottomButtonTitle	NSString	底部关闭按钮标题。点击效果与右上角关闭按钮一致。
tabs	NSArray	Tab 数据数组，至少应包含一个有效 Tab。
priceColor	UIColor	商品价格、订单金额颜色；未设置时默认红色。
headerBackgroundColor	UIColor	标题区域和 Tab 区域背景色；未设置时默认白色。
selectedIndex	NSUInteger	默认选中的 Tab 下标；越界时自动回退至第一个有效 Tab。

QYConsultationContentTab参数如下：

属性	类型	说明
title	NSString	Tab 标题。
type	QYConsultationContentType	Tab 类型，仅支持 QYConsultationContentTypeOrder 和 QYConsultationContentTypeProduct。
orders	NSArray	订单数据。仅当 type = QYConsultationContentTypeOrder 时生效。
products	NSArray	商品数据。仅当 type = QYConsultationContentTypeProduct 时生效。

QYConsultationContentOrder参数如下：

属性	类型	说明
orderText	NSString	订单信息文案。
timeText	NSString	时间文案。
items	NSArray	订单商品明细；非法对象会被 SDK 过滤
amountTitle	NSString	金额标题，例如“应付金额”。
amount	NSString	订单总金额展示文案。
statusText	NSString	订单状态文案，例如“待收货”
statusColor	UIColor	订单状态文字颜色

QYConsultationContentItem参数如下:

属性	类型	说明
pictureUrlString	NSString	商品图片 URL。
title	NSString	商品标题，点击发送后会作为商品卡片标题。
subtitle	NSArray	第一行辅助描述。
detail	NSString	第二行辅助描述。
price	NSString	价格展示文案。
count	NSString	数量展示文案，例如 x1。
urlString	NSString	商品或订单卡点击跳转地址

示例代码：

QYConsultationContentItem *item = [[QYConsultationContentItem alloc] init];
item.pictureUrlString = @"https://example.com/product.jpg";
item.title = @"轻便婴儿推车";
item.subtitle = @"双向避震 / 可坐可躺";
item.detail = @"曜石黑 / 标准版";
item.price = @"¥ 899.00";
item.count = @"x1";

QYConsultationOrder *order = [[QYConsultationOrder alloc] init];
order.orderText = @"订单编号：SP20260730001";
order.timeText = @"下单时间：2026-07-30 10:30";
order.items = @[item];
order.amountTitle = @"应付金额";
order.amount = @"¥ 899.00";

QYConsultationContentTab *orderTab = [[QYConsultationContentTab alloc] init];
orderTab.title = @"最近订单";
orderTab.type = QYConsultationContentTypeOrder;
orderTab.orders = @[order];

QYConsultationContentTab *productTab = [[QYConsultationContentTab alloc] init];
productTab.title = @"推荐商品";
productTab.type = QYConsultationContentTypeProduct;
productTab.products = @[item];

QYConsultationContentConfig *config = [[QYConsultationContentConfig alloc] init];
config.title = @"请选择咨询内容";
config.bottomButtonTitle = @"暂不咨询";
config.priceColor = [UIColor colorWithRed:1 green:0.30 blue:0.35 alpha:1];
config.headerBackgroundColor = [UIColor colorWithRed:1 green:0.96 blue:0.96 alpha:1];
config.tabs = @[orderTab, productTab];

[sessionVC presentConsultationContentWithConfig:config];

隐私开关配置

属性	类型	默认值	说明
messageCopyBtnSwitch	BOOL	YES	消息流 cell 长按后气泡弹框中是否显示“复制”
proximitySensorEnable	BOOL	YES	播放语音消息时是否使用距离传感器进行贴耳切换

会话配置

会话来源

会话来源

人工客服分配

分配客服

分配客服组

设置多入口分流模板

联系客服成功前输入框禁止输入

机器人客服

机器人客服

分配机器人

设置常见问题

设置常见快捷入口

设置欢迎语

用户 VIP 等级

设置用户VIP等级

专属客服与客服信息

设置客服信息

会话入口参数

会话生命周期配置

会话配置

人工客服

自定义咨询页面

接入方式

参数说明

隐私开关配置

其他

目录