功能配置

七鱼客服系统主要功能配置由主页面控制器QYSessionViewController提供,可配置机器人客服、人工客服、消息加载等功能,同时对外开放了部分能力。

会话来源

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

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 来源自定义信息

机器人客服

分配机器人

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

sessionViewController.robotId = 123456;

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

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

设置常见问题

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

sessionViewController.commonQuestionTemplateId = 123456;

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

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

设置欢迎语

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

sessionViewController.robotWelcomeTemplateId = 123456;

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

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

人工客服

分配客服

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

sessionViewController.staffId = 123456;

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

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

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

sessionViewController.openRobotInShuntMode = YES;

默认为NO。

分配客服组

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

sessionViewController.groupId = 123456;

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

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

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

sessionViewController.openRobotInShuntMode = YES;

默认为NO。

设置客服信息

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用于接入人工客服后隐式向客服发送消息的文本,访客端无感知。

主动请求客服

V4.4.0 版本之后,新增主动请求人工客服接口:

/**
 *  请求人工客服
 */
- (void)requestHumanStaff;

该接口仅在当前无会话或机器人模式下才能主动请求人工客服,否则无效。

主动切换客服

V4.6.0 版本之后,新增主动切换人工客服接口:

/**
 *  切换人工客服
 *
 *  @param staffId 客服ID
 *  @param groupId 分组ID
 *  @param closetip 切换提示语
 *  @param closeCompletion 退出旧会话完成的回调
 *  @param requestCompletion 请求新会话完成的回调
 */
- (void)changeHumanStaffWithStaffId:(int64_t)staffId
                            groupId:(int64_t)groupId
                           closetip:(NSString *)closetip
                    closeCompletion:(QYCompletion)closeCompletion
                  requestCompletion:(QYCompletion)requestCompletion;

切换客服逻辑为自动结束当前会话,并使用设置的 staffIdgroupId去请求新的人工客服;在结束当前会话时,消息流中会展示提示消息 您退出了咨询,此文案可通过设置接口中的closetip来替换。

主动结束会话

V5.2.0 版本之后,新增主动结束会话/退出排队接口:

/**
 *  退出会话/退出排队
 *  @param popViewController 是否退出聊天界面,设置为YES,无论退出是否成功均退出聊天界面
 *  @param completion 退出完成回调
 */
- (void)closeSession:(BOOL)popViewController completion:(QYCompletion)completion;

结束逻辑为判断当前会话状态,若处在会话中,则退出当前会话;若处在排队流程中,则效果相当于点击 取消排队 按钮,退出排队。

设置用户VIP等级

sessionViewController提供访客 VIP 等级设置:

sessionViewController.vipLevel = 1;

默认为非VIP。

商品卡片

商品定义

访客进入不同咨询入口可带入该入口对应的商品信息,以商品卡片消息的形式自动或主动发送,提供多个配置字段并支持点击跳转链接,方便客服直观了解访客咨询内容。商品信息类QYCommodityInfo提供如下属性:

属性 类型 必须 说明
show BOOL 是否在访客端隐藏,默认隐藏
isCustom BOOL 是否自定义-只显示图片,默认否
sendByUser BOOL 是否由访客手动发送,默认否
title NSString 商品标题,限制100字符
desc NSString 商品描述,限制300字符
pictureUrlString NSString 商品图片,限制1000字符
urlString NSString 跳转链接,限制1000字符
note NSString 备注信息-可用于价格/订单号等,限制100字符
tagsArray NSArray 商品卡片标签按钮,限制3个
tagsString NSString 商品卡片标签按钮,限制3个,二选一
actionText NSString 访客手动发送按钮文案
actionTextColor UIColor 访客手动发送按钮文案颜色
ext NSString 附加信息,透传数据

需要注意的是,默认访客端隐藏商品卡片;商品卡片展现形式分为两种,默认所有字段均展示,若isCustom设置为YES,则仅展示商品图片;卡片下方可携带标签按钮,但按钮仅在客服端显示,访客端无需显示。

样例如下:

QYCommodityInfo *commodityInfo = [[QYCommodityInfo alloc] init];
commodityInfo.show = YES;
commodityInfo.title = @"网易七鱼";
commodityInfo.desc = @"网易七鱼是网易旗下一款专注于解决企业与客户沟通的客服系统产品。";
commodityInfo.pictureUrlString = @"http://qiyukf.com/main/res/img/index/barcode.png";
commodityInfo.urlString = @"http://qiyukf.com/";
commodityInfo.note = @"¥10000";

sessionViewController.commodityInfo = commodityInfo;

商品卡片点击事件可自定义,具体请查阅文档 自定义事件 相关说明。

发送规则

  • 若入口设置了商品信息,进入后需等待人工客服连接,成功后自动发送商品卡片消息;若企业开启机器人,默认不发送给机器人客服,转人工客服后再发送,该逻辑可通过配置sessionViewControllerautoSendInRobot属性修改为机器人可接收商品卡片消息。
  • 若设置了商品信息,同时开启了机器人客服及autoSendInRobot属性,则进入聊天页面连接上机器人客服后,自动发送商品卡片;之后转人工客服连接成功后,会再次发送商品卡片给人工。
  • 会话未结束退出咨询页面后再次进入,会判断商品卡片是否重复,若关键信息重复则不再继续发送,若信息有变化会再次发送。
  • 会话未结束,访客App重启,进入同一咨询入口会重复发送一次商品卡片。

自定义商品卡片

客服端可使用 iframe 数据向访客端发送商品卡片,此数据为 JSON 格式,由一连串key-value组成。若开发者认为 SDK 提供的商品卡片样式不符合预期,则可使用自定义商品卡片功能;在 iframe 数据中新增如下两个字段即可:

属性 类型 说明
isOpenCustomProduct BOOL 是否为自定义商品卡片
productCustomField NSString 自定义商品卡片数据

isOpenCustomProduct字段配置为true时,访客端收到此 iframe 数据后,会通过 block 回调透传productCustomField字段内容即自定义卡片数据,该 block 定义在QYSessionViewController中:

/** 以下为自定义卡片消息相关接口 **/

/**
 *  自定义卡片消息回调
 *
 *  @param jsonString 自定义卡片消息数据
 */
typedef void (^QYCustomMessageDataBlock)(NSString *jsonString);

/**
 *  自定义卡片消息事件,回调时机为收到该类消息时刻
 */
@property (nonatomic, copy) QYCustomMessageDataBlock customMessageDataBlock;

SDK 会忽略此条消息并完全将数据交由外部进行处理,开发者可在收到回调后,使用 高级功能-自定义消息 来插入一条本地自定义消息,将提前定义好的 JSON 数据构建为消息对象QYCustomMessage子类,并构建对应的数据模型QYCustomModel子类、视图QYCustomContentView子类。样例如下:

__weak typeof(self) weakSelf = self;
sessionViewController.customMessageDataBlock = ^(NSString *jsonString) {
    NSData *data = [jsonString dataUsingEncoding:NSUTF8StringEncoding];
    if (data) {
        id object = [NSJSONSerialization JSONObjectWithData:data options:0 error:nil];
        if ([object isKindOfClass:[NSDictionary class]]) {
            QYCustomTicketMessage *message = [QYCustomTicketMessage objectByDict:object];
            [weakSelf.sessionViewController addCustomMessage:message
                                                needSaveData:YES
                                              needReloadView:YES
                                                  completion:^(NSError *error) {
                if (error) {
                    NSLog(@"addCustomMessage error !!!");
                }
            }];
        }
    }
};

会话消息

七鱼客服系统 iOS SDK 默认持久化所有账户的聊天消息至本地数据库,进入聊天页面时从数据库中读取历史消息并显示出来,并非网络拉取。

消息加载规则

默认消息加载规则为20条,即进入聊天页面,从数据库中读取最近的20条历史消息进行展示,若不满20条,则全部显示。访客可手动下拉加载更多历史消息,每次加载20条数据。注意20条不仅是普通消息,系统类型消息也包含在内,例如时间消息、接入提示消息等。此加载规则可修改,由sessionViewController提供属性:

/**
 *  每页消息加载的最大数量,默认为20条
 */
@property (nonatomic, assign) NSInteger messagePageLimit; 

历史消息收起

进入聊天页面后,无论是重新连接客服还是继续上次会话,从数据库读取的历史消息默认全部展示。设置历史消息收起后,进入聊天页面若需重新连接客服,则不会读取和显示历史消息,访客主动下拉加载历史消息后,消息流中新增 以上为历史消息 用以区分新旧消息。通过配置sessionViewController属性可收起历史消息:

/**
 *  是否收起历史消息,默认为NO;若设置为YES,进入会话界面时若需创建新会话,则收起历史消息
 */
@property (nonatomic, assign) BOOL hideHistoryMessages;

同时可自定义提示文案:

/**
 *  历史消息提示文案,默认为“——以上为历史消息——”;仅在hideHistoryMessages为YES,首次下拉历史消息时展示
 */
@property (nonatomic, copy) NSString *historyMessagesTip;

漫游消息拉取

七鱼客服系统支持账号信息打通,对于企业通过setUserInfo:接口传入的userId,服务端会合并不同访客端产生的消息记录。iOS SDK 默认不从服务端拉取漫游消息,仅读取本地数据库持久化数据。若开启漫游消息拉取功能,则在企业调用setUserInfo:时会联网请求该userId账户对应的漫游历史消息,并与本地数据库进行对比过滤重复数据。漫游功能独立于聊天页面,在QYCustomActionConfig单例中配置:

/**
 *  账号登录后是否拉取漫游消息
 */
@property (nonatomic, assign) BOOL pullRoamMessage;

默认关闭。

发送能力

七鱼 iOS SDK 对外提供一些标准能力,针对消息发送开放了文本、图片、视频、文件、商品、订单六种消息类型,企业可调用这些标准能力直接发送对应消息。

文本消息

可直接调用接口发送文本消息,传入字符串:

/**
 *  发送文本消息
 */
- (void)sendText:(NSString *)text; 

图片消息

可直接调用接口发送图片消息,传入UIImage对象:

/**
 *  发送图片消息
 */
- (void)sendPicture:(UIImage *)picture; 

视频消息

V5.2.0 版本之后,可直接调用接口发送视频消息,传入视频存储地址:

/**
 *  发送视频消息
 */
- (void)sendVideo:(NSString *)filePath;

同时,七鱼 iOS SDK 还提供拍摄视频功能,允许调用内部视频录制界面,注意该界面依赖于客服聊天界面,不可完全脱离此界面调用:

/**
 *  拍摄视频完成回调
 *  @param filePath 视频存储路径
 */
typedef void (^QYVideoCompletion)(NSString *filePath);

/**
 *  拍摄视频
 */
- (void)shootVideoWithCompletion:(QYVideoCompletion)completion;

接口提供视频拍摄完成回调,返回视频存储地址,可使用上述sendVideo:方法发送此视频给客服,或进行其他特殊化处理。

文件消息

V5.6.0 版本之后,新增发送文件类型消息,需传入文件名称及本地存储路径:

/**
 *  发送文件消息
 */
- (void)sendFileName:(NSString *)fileName filePath:(NSString *)filePath;

同时,七鱼 iOS SDK 提供选择系统文件功能,使用了UIDocumentPickerViewController控制器,并已指定部分常见文件类型,如仍未满足需求,可通过allowedUTIs参数补充文件类型:

/**
 *  选择文件完成回调
 *  @param filePath 文件存储路径
 */
typedef void (^QYFileCompletion)(NSString *fileName, NSString *filePath);

/**
 *  选择系统文件,调用系统控件UIDocumentPickerViewController,注意文件功能目前仅支持iOS11以上系统
 *  @param allowedUTIs 需增加支持的文件类型,已有部分默认类型,传nil时采用默认类型组;具体可参照UIDocumentPickerViewController的allowedUTIs参数
 *  @param completion 选择完成回调
 */
- (void)selectFileWithDocumentTypes:(NSArray <NSString *>*)allowedUTIs completion:(QYFileCompletion)completion;

调用接口会在客服界面调起系统文件选择页面,选择文件或点击取消后提供完成回调,返回文件名称fileName及拷贝至 Documents 目录下的文件路径filePath,可调用前面的sendFileName: filePath:方法发送文件消息给客服。

请注意,系统文件选择功能目前只支持 iOS11 及以上系统,因 iOS11 以下系统只能访问 iCloud 文件,App 需开启 iCloud Documents 功能。

商品消息

与上面进入聊天界面自动发送商品卡片不同,您也可以在任意时刻调用接口主动发送商品消息,传入QYCommodityInfo对象:

/**
 *  发送商品信息展示
 */
- (void)sendCommodityInfo:(QYCommodityInfo *)commodityInfo; 

订单消息

订单对象QYSelectedCommodityInfo提供更多属性字段方便信息展示,包括订单状态p_status、价格p_price、数量p_count、库存p_stock等等,接口如下:

/**
 *  发送订单列表中选中的商品信息
 */
- (void)sendSelectedCommodityInfo:(QYSelectedCommodityInfo *)commodityInfo; 

满意度评价

自定义评价界面

V5.0.0 版本之后,七鱼 iOS SDK 对外提供自定义满意度评价界面,方便客户实现带有企业特色的评价界面。要完成自定义评价功能,首先需修改 管理端-应用-在线系统-设置-会话流程-满意度评价-样式设置-评价样式 选项为 新页面,此处填入的页面链接对移动端无效。

修改完成后,SDK 会将满意度评价事件以 block 形式抛出,并提供相关满意度数据,随管理端配置更新:

/**
 *  满意度评价事件回调
 *
 *  @param data 评价数据,包括评价模式、选项及标签、上次评价结果等数据,据此构建评价界面
 */
typedef void (^QYEvaluationBlock)(QYEvaluactionData *data);

/**
 *  满意度评价事件
 */
@property (nonatomic, copy) QYEvaluationBlock evaluationBlock;

满意度评价数据QYEvaluactionData类提供了如下属性:

属性 类型 说明
sessionId long long 评价会话ID,提交评价结果时需透传
mode NSUInteger 评价模式,支持二/三/四/五级模式,管理端配置
optionList NSArray 选项数据,数组元素为QYEvaluationOptionData对象
resolvedEnabled BOOL 是否向访客收集 “您的问题是否解决”
resolvedRequired BOOL “您的问题是否解决”是否必填
lastResult QYEvaluactionResult 上次评价结果

其中,满意度选项数据QYEvaluationOptionData类提供如下属性:

属性 类型 说明
option NSUInteger 选项类型,非常满意/满意/一般/不满意/非常不满意
name NSString 选项名称
score NSInteger 选项分值
tagList NSArray 标签,每个选项限制10个
tagRequired BOOL 标签是否必填
remarkRequired BOOL 备注是否必填

同时提供上次评价结果QYEvaluactionResult对象,该对象提供如下属性:

属性 类型 说明
sessionId long long 评价会话ID,不可为空
selectOption QYEvaluationOptionData 选中的选项,不可为空
selectTags NSArray 选中的标签,若标签必填,则不可为空
remarkString NSString 评价备注,若备注必填,则不可为空
resolveStatus NSInteger 问题是否解决,若必填,则不可为None

获取到评价数据后,可根据数据配置构建不同模式的评价界面,然后使用sessionViewController弹出。

发送评价结果

当用户评价完成后,需将评价结果回传给 SDK,由 SDK 传递数据给后台并进行后续的评价反馈动作,发送结果接口如下:

/**
 *  满意度评价结果返回值
 */
typedef NS_ENUM(NSInteger, QYEvaluationState) {
    QYEvaluationStateSuccessFirst = 1,  //成功-首次评价
    QYEvaluationStateSuccessRevise,     //成功-修改评价
    QYEvaluationStateFailParamError,    //失败-发送参数错误
    QYEvaluationStateFailNetError,      //失败-网络错误
    QYEvaluationStateFailNetTimeout,    //失败-网络超时
    QYEvaluationStateFailTimeout,       //失败-评价超时
    QYEvaluationStateFailUnknown,       //失败-未知原因不可评价
};

/**
 *  评价结果回调
 *
 *  @param state 结果
 */
typedef void (^QYEvaluationCompletion)(QYEvaluationState state);

/**
 *  发送满意度评价结果
 */
- (void)sendEvaluationResult:(QYEvaluactionResult *)result completion:(QYEvaluationCompletion)completion;

接口提供评价成功/失败的结果回调,若评价成功,需收起评价界面,若评价失败,可提示用户失败原因。

其他

输入栏快捷入口

七鱼客服聊天界面提供输入栏上方快捷入口设置,区分机器人与人工两种模式。机器人模式下,快捷入口需在企业机器人相关配置页面进行按钮及事件的配置,不同节点可配置不同快捷入口,配置成功后快捷入口自动显示在输入栏上方,且根据配置自动更新,无需代码配置。

人工模式下,快捷入口按钮有两种配置方案,一种通过 管理端-应用-在线系统-设置-访客端-样式设置-App端-输入框上方快捷入口 配置按钮,并设置相应事件,注意此功能在 V5.2.0 版本后提供;在后台样式设置关闭情况下,可通过代码配置人工快捷入口。

快捷入口按钮QYButtonInfo类提供了如下属性:

属性 类型 必须 说明
buttonId id 快捷入口ID,未限制类型
title NSString 快捷入口标题
userData id 透传数据,未限制类型
actionType NSUInteger, Readonly 按钮响应事件传递信息,1-文本/2-链接或自定义行为
index NSUInteger, Readonly 响应按钮位置

添加按钮的示例代码:

QYButtonInfo *button_1 = [[QYButtonInfo alloc] init];
button_1.buttonId = [NSNumber numberWithLongLong:1001];
button_1.title = @"按钮标题1";

QYButtonInfo *button_2 = [[QYButtonInfo alloc] init];
button_2.buttonId = [NSNumber numberWithLongLong:1002];
button_2.title = @"按钮标题2";

sessionViewController.buttonInfoArray = @[button_1, button_2];

聊天窗口顶部区域自定义

V4.7.0 版本中,获取到 sessionViewController后,可自定义聊天界面顶部区域,支持外部注册入视图,可配置视图高度和边距;此视图悬停在聊天界面导航栏下方、消息列表上方,不随消息流滚动。注册接口为:

/**
 *  注册聊天界面顶部悬停视图
 *
 *  @param hoverView 顶部悬停视图
 *  @param height 视图高度
 *  @param insets 视图边距,默认UIEdgeInsetsZero;top表示视图与导航栏底部距离,bottom设置无效,left/right分别表示距离屏幕左右边距
 */
- (void)registerTopHoverView:(UIView *)hoverView height:(CGFloat)height marginInsets:(UIEdgeInsets)insets;

支持销毁此视图,支持设置是否有渐隐动画及动画时长,销毁接口如下:

/**
 *  销毁聊天界面顶部悬停视图
 */
- (void)destroyTopHoverViewWithAnmation:(BOOL)animated duration:(NSTimeInterval)duration;

自助提工单能力

V5.7.0 版本之后,新增人工模式下自助提工单能力,调用此接口效果与后台样式设置中的创建工单按钮点击效果一致,根据传入的工单模板ID请求工单数据并弹出工单页面,访客填写完成后,点击提交按钮发送工单结果数据,同时消息流会新增一条访客消息:信息已提交。接口如下:

/**
 *  弹出工单页面自助提工单
 *  @param templateID 工单模板ID
 */
- (void)presentWorkOrderViewControllerWithTemplateID:(long long)templateID;