七鱼开发文档中心
总览服务端 APIWebiOSAndroid鸿蒙Uniapp微信小程序插件三方接入

会话管理

会话控制

本节说明主动请求客服、结束会话、转接客服、退出排队等会话控制能力。

主动请求客服(海外版不支持)

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;

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

主动结束会话(海外版不支持)

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

​

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

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

未读消息

本节说明未读消息数的获取、监听和清理方式。

消息未读数

可通过如下接口主动获取消息的未读数量,用于显示未读红点:

/**
 *  所有的未读数
 *
 *  @return 未读数
 */
- (NSInteger)allUnreadCount;

如需收到未读消息数量变化通知,通过如下接口设置委托:

/**
 *  设置会话委托
 *
 *  @param delegate 会话委托
 */
- (void)setDelegate:(id<QYConversationManagerDelegate>)delegate;

并实现该委托中如下方法即可监听数量变化:

/**
 *  会话未读数变化
 *
 *  @param count 未读数
 */
- (void)onUnreadCountChanged:(NSInteger)count;

该未读数为所有会话项的总未读数,如需分开需获取会话列表。如需清空消息未读数量,请调用如下接口:

/**
 *  清空未读数
 *
 */
- (void)clearUnreadCount;

消息接收与最后一条消息

本节说明如何监听新消息以及获取最后一条消息内容。

监听消息接收(海外版不支持)

如需实时监听消息接收情况,实现协议QYConversationManagerDelegate中的如下方法:

/**
 *  接收消息
 */
- (void)onReceiveMessage:(QYMessageInfo *)message;

接口提供接收到的最新消息对象QYMessageInfo类,该类提供如下属性:

属性类型说明
textNSString消息文本,可为空
typeNSInteger消息类型:文本(值0)/图片(值1)/语音(值2)/视频(值3)/文件(值4)/自定义(值5),默认0,除了这些值均无效
timeStampNSTimeInterval消息时间戳,单位微秒,默认为0

历史消息与漫游

本节说明历史消息加载、收起和服务端漫游消息拉取相关能力。

会话消息

七鱼客服系统 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;

默认关闭,开启后默认拉取最近7天最新20条消息。 为适应不同场景,V5.15.0 版本新增消息条数限制可配,默认20条,最大100条:

/** 拉取漫游消息条数,默认20条,最大100条 */
@property (nonatomic, assign) NSUInteger roamMessageLimit;

满意度评价

本节说明评价界面、评价结果上报和会话结束时邀评等能力。

满意度评价

自定义评价界面

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

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

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

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

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

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

属性类型说明
optionNSUInteger选项类型,非常满意/满意/一般/不满意/非常不满意
nameNSString选项名称
scoreNSInteger选项分值
tagListNSArray标签,每个选项限制10个
tagRequiredBOOL标签是否必填
remarkRequiredBOOL备注是否必填

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

属性类型说明
sessionIdlong long评价会话ID,不可为空
selectOptionQYEvaluationOptionData选中的选项,不可为空
selectTagsNSArray选中的标签,若标签必填,则不可为空
remarkStringNSString评价备注,若备注必填,则不可为空
resolveStatusNSInteger问题是否解决,若必填,则不可为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;
/** 发送机器人满意度评价结果 */
- (void)sendRobotEvaluationResult:(QYEvaluactionResult *)result completion:(QYEvaluationCompletion)completion;

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

再次邀评

为提高会话的参评率,七鱼客服界面支持在下一次会话开始前再次弹出评价弹框的配置。 要使用该功能,您需要在web配置界面开启再次邀评的开关:“设置-会话流程-满意度评价-再次邀评” 开启此开关后,每次新发起一通会话时,如果上一通有效会话存在待评价的内容,则会再次弹出评价的弹框。 特别注意: 如果您配置的评价样式是:自定义评价界面,意味着所有的评价弹框都是使用您自定义的视图。此时,您如果需要再次邀评的弹框也是自定义的,需要使用如下代码配置自定义视图效果:

/** 会话前强制人工满意度评价事件,自定义视图写在此回调中(web端可配置关闭,默认关闭) */
@property (nonatomic, copy) QYEvaluationBlock preSessionEvaluationBlock;

在您的自定义界面中,您需要将评价的结果上报给七鱼客服:

/** 发送人工满意度评价结果 */ 
(void)sendEvaluationResult:(QYEvaluactionResult *)result completion:(QYEvaluationCompletion)completion; 
/** 上报再次邀评功能,用户评价的结果 YES 成功评价 NO 放弃评价 需要配合preSessionEvaluationBlock使用,会话中的评价弹框不需要调用此方法 开启了再次邀评,不调用此方法会导致无法正常进线 */
(void)reportEvaluationResult:(BOOL)result data:(QYEvaluactionData *)data;

注意: 再次邀评仅对有效的人工会话生效,机器人会话不生效。

关闭会话时弹出满意度评价

会话过程中,点击导航栏左上角的返回按钮,可以在返回前邀请用户对会话进行评价。 您需要在您的返回按钮点击事件里面,调用下面的方法:

/** 导航栏左侧点击返回时,是否需要弹出满意度评价 isOpenAlert:是否弹出弹框(确认退出对话?) isOpenEvaluation:点击结束会话时,是否需要弹出满意度评价 注意:想要弹出评价的弹框,必须同时开启上述两个开关。 该方法需要在导航栏左侧返回按钮的点击事件时调用,并且将popViewControllerAnimated放在complete中;如果是present方式,则需要在关闭界面的点击事件中调用此方法 */ 
(void)showEvaluationAlert:(BOOL)isOpenAlert openEvaluation:(BOOL)isOpenEvaluation complete:(QYCompletion)complete;

示例代码如下:

- (void)onBack:(id)sender {
    [self.sessionViewController showEvaluationAlert:YES openEvaluation:YES complete:^(BOOL success, NSError *error) {
        __weak typeof(self) weakSelf = self;
        [[[QYSDK sharedSDK] customActionConfig] showQuitWaitingAlert:^(QYQuitWaitingType quitType) {
            if (quitType == QYQuitWaitingTypeNone) {
                [weakSelf dismissViewControllerAnimated:YES completion:nil];
            } else if (quitType == QYQuitWaitingTypeContinue) {
                [weakSelf dismissViewControllerAnimated:YES completion:nil];
            } else if (quitType == QYQuitWaitingTypeQuit) {
                dispatch_after(dispatch_time(DISPATCH_TIME_NOW, (int64_t)(1 * NSEC_PER_SEC)), dispatch_get_main_queue(), ^{
                    [weakSelf dismissViewControllerAnimated:YES completion:nil];
                });
            } else if (quitType == QYQuitWaitingTypeCancel) {
            }
        }];
    }];
}

多语言设置

本节说明 SDK 多语言能力和语言环境设置方式。

多语言设置

/**
 * 是否跟随系统语言自动变化,默认YES
 * @discussion 开启时设置language无效,仅跟随系统变化
 */
@property (nonatomic, assign) BOOL followSystemLanguage;
/**
 * 语言设置,默认简体中文
 * @discussion 目前仅支持简体中文、繁体中文、英、日、韩、德、法、泰、印尼语、越南语、菲律宾语、土耳其、葡萄牙、西班牙
 * @discussion 对应关系:zh-Hans(简体中文)、zh-Hant(繁体中文)、en(英)、ja(日)、ko(韩)、de(德)、fr(法)、th(泰)、id(印尼语)、vi(越南)、tl(菲律宾语)、tr(土耳其语)、es(西班牙语)、pt(葡萄牙语)
 * 传参时请使用上述对应关系的字符串,否则无效
 */
@property (nonatomic, copy) NSString *languageString;

缓存管理

本节说明 SDK 文件缓存或账号缓存的清理方式。

清理文件缓存

七鱼 iOS SDK 提供资源文件清理功能,主要包括接收及发送的图片、视频、文件等大体积缓存,通过调用QYSDK.h如下接口清理:

/**
 *  清理缓存回调
 */
typedef void(^QYCleanCacheCompletion)(NSError *error);

/**
 *  清理接收文件缓存
 *  @param completion 清理缓存完成回调
 */
- (void)cleanResourceCacheWithBlock:(QYCleanCacheCompletion)completion;

会话管理

本节收纳会话管理相关的基础说明和平台补充内容。

七鱼 iOS SDK 提供会话项相关信息,支持多会话,具体见 平台电商 相关说明。对于非平台企业,会话项一般只有一项,会话相关能力由 QYConversationManager 提供,单例通过如下方法获取:

[[QYSDK sharedSDK] conversationManager];

可获取会话消息未读数、清除未读数、获取会话列表、监听会话项变化等。

这篇文档有帮助吗?

目录