目录

鸿蒙访客端SDK API文档

初始化SDK

//在主页面调用，以免重复初始化
    let mVisitorOptions = new VisitorOptions();
    mVisitorOptions.setKefuRestServer('${客服登录地址}')
      .setAppkey('${AppKey}')
      .setTenantId('${租户ID}')
      .setAppVersion('${app版本号}')
    VisitorClient.getInstance().init(mContext, visitorOptions)

注册

VisitorClient.getInstance()
      .getVisitorManager()
      .register(username, password)
      .then((value: string) => {
        console.info("注册成功" + value)
      })
      .catch((reason: VisitorError) => {
        console.error("注册失败" + reason.errorCode + "," + reason.description)
      });

密码登录

//调接口登录
    VisitorClient.getInstance()
      .getVisitorManager()
      .login(username, password)
      .then((value: string) => {
        console.info("登录成功" + value)
      })
      .catch((reason: VisitorError) => {
        console.error("登录失败" + reason.errorCode + "," + reason.description)
      })

Token登录

//调接口登录
    VisitorClient.getInstance()
      .getVisitorManager()
      .loginWithToken(username, token)
      .then((value: string) => {
        console.info("登录成功" + value)
      })
      .catch((reason: VisitorError) => {
        console.error("登录失败" + reason.errorCode + "," + reason.description)
      })

登录状态

//判断是否已登录，避免重复调用登录接口
    VisitorClient.getInstance().isLoggedInBefore()

退出登录

VisitorClient.getInstance()
      .getVisitorManager()
      .logout()
      .then(() => {
        console.info("退出成功")
      })
      .then(() => {
        //TODO 移除emitter事件，避免切换用户后重复执行事件
      })
      .catch((reason: VisitorError) => {
        console.error("退出失败" + reason.errorCode + "," + reason.description)
      })

长连接监听

connectListener:IMConnectListener = {
      onConnected: (): void => {
        // 长连接建立
      },
      onDisconnected: (errorCode: number): void => {
        // 长连接断开
        switch (errorCode){
          case VisitorError.USER_NOT_FOUND:
          case VisitorError.USER_LOGIN_ANOTHER_DEVICE:
          case VisitorError.USER_AUTHENTICATION_FAILED:
          case VisitorError.USER_REMOVED:
            VisitorClient.getInstance().getVisitorManager().logout()
          //TODO 跳转到登录页面
            break;
        }
      }
    } 
    //添加长连接监听
    VisitorClient.getInstance().addConnectionListener(connectListener)
    //移除长连接监听
    VisitorClient.getInstance().removeConnectionListener(connectListener)

消息监听

messageListener: MessageListener = {
      onMessage(msgs: ArrayList<Message>) {
        //收到上屏消息
      },
      onCmdMessage(msgs: ArrayList<Message>) {
        //收到cmd透传消息
      },
      onMessageStatusUpdate() {
      },
      onMessageSent() {
        //消息已发送
      }
    };
    //添加消息监听
    VisitorClient.getInstance().getVisitorManager().addMessageListener(messageListener);
    //移除消息监听
    VisitorClient.getInstance().getVisitorManager().removeMessageListener(messageListener);

绑定IM服务号

//发消息之前请点调用该API,以绑定IM服务号，可在进入聊天页面之后即调用
    VisitorClient.getInstance().getVisitorManager().bindChat(toChatUsername)

解绑IM服务号

//退出聊天页面调用该API,以解绑IM服务号
    VisitorClient.getInstance().getVisitorManager().unbindChat(toChatUsername)

修改AppKey

//newAppKey 新的AppKey
    VisitorClient.getInstance().changeAppKey(newAppKey)

修改租户ID

//newTenantId 新的租户ID
    VisitorClient.getInstance().changeTenantId(newTenantId)

消息

1.发送消息

VisitorClient.getInstance().getVisitorManager().sendMessage(message)

2.保存消息到本地

VisitorClient.getInstance().getVisitorManager().saveMessage(message)

3.删除消息

let messageId = message.messageId();
    VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername).removeMessage(messageId);

4.创建文本消息

//content:文本内容；toChatUsername：IM服务号；
    Message.createTxtSendMessage(content, toChatUsername)

5.创建图片消息

//imgPath:图片路径；imgSize:图片大小（宽,高）；toChatUsername：IM服务号；displayName：图片文件名称；
    let imgSize = new VisitorImageSize(480, 640);
    let message = Message.createImageSendMessage(imgPath, imgSize, toChatUsername, displayName);

6.创建语音消息

//voicePath:语音文件路径；duration:语音时长；toChatUsername：IM服务号；
    Message.createVoiceSendMessage(voicePath, duration, this.toChatUsername)

7.创建短视频消息

//videoPath:短视频文件路径；duration:视频时长；toChatUsername：IM服务号；displayName：视频文件名称；thumbLocalPath：缩略图文件路径；
    Message.createVideoSendMessage(videoPath, duration, this.toChatUsername, displayName, thumbLocalPath);

8.创建文件消息

//filePath:文件路径；fileLength:文件大小；toChatUsername：IM服务号；displayName：文件名称；
    Message.createFileSendMessage(filePath, fileLength, this.toChatUsername, displayName);

9.创建位置消息

//latitude:维度；longitude:经度；toChatUsername：IM服务号；address：地址信息；buildingName：建筑物名称；
    Message.createLocationSendMessage(latitude, longitude, this.toChatUsername, address, buildingName);

10.创建点击菜单条目后回复的选择消息

//item：ChoiceItem 点击的机器人菜单条目或者询前引导菜单条目；toChatUsername：IM服务号；transferMode:string Choice.mode 从Choice中获取的转接模式
    Message.createSendMessageForMenu(item, this.toChatUsername, transferMode)

11.创建订单消息

//发送订单消息
    let message = Message.createTxtSendMessage("订单",this.toChatUsername)
    let orderInfo:OrderInfo = {
      title:"订单消息",
      order_title:"订单号：611088888",
      desc:"短裤",
      price:"￥200",
      img_url:"https://xxx",
      item_url:"https://www.easemob.com"
    }
    message.addOrderInfo(orderInfo)
    VisitorClient.getInstance().getVisitorManager().saveMessage(message)

12.创建轨迹消息

//发送轨迹消息
    let message = Message.createTxtSendMessage("轨迹",this.toChatUsername)
    let trackInfo:TrackInfo = {
      title:"轨迹消息",
      desc:"衬衫",
      price:"￥200",
      img_url:"https://xxx",
      item_url:"https://www.easemob.com"
    }
    message.addTrackInfo(trackInfo)
            VisitorClient.getInstance().getVisitorManager().sendMessage(message)

从消息中获取坐席信息

//用于显示坐席头像、昵称
    MessageHelper.getAgentInfo(message)

会话相关

获取所有本地会话

ChatClient.getInstance().chatManager().getAllConversations();

从本地会话中获取最后一条消息

//toChatUsername:IM服务号
    VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername)?.latestMessage()

从本地会话中获取最近的坐席信息

//根据业务需求，在会话列表中调用以显示最近坐席信息
let agentInfo = conversation.getAgentInfo();
      if (agentInfo) {
        this.nickName = agentInfo.userNickname ? agentInfo.userNickname : ""
        this.img = agentInfo.avatar ? agentInfo.avatar : ""
      }

从本地会话中获取未读消息数

//toChatUsername:IM服务号
    VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername)?.unreadMessagesCount()

标记IM服务号对应的本地会话中所有消息为已读

//只改变本地会话中消息状态
    VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername).markAllMessagesAsRead()
    //TODO 本地标记后需要调用14来通知坐席消息已读

标记本地消息为已读

//本地设置消息已读，只改变本地消息状态
    message.setUnRead(false)

标记该通会话中所有消息已读

//从消息中获取客服系统会话ID
    let sessionId = MessageHelper.getSessionIdFromMessage(message);
    //通知坐席消息已读
    VisitorClient.getInstance()
      .getVisitorManager()
      .asyncMarkAllMessagesAsRead(VisitorClient.getInstance().getTenantId(), sessionId)

获取正在进行中的会话信息

VisitorClient.getInstance().getVisitorManager().asyncGetCurrentSessionInfo()
      .then((result) => {
        //result为空，没有正在进行中的会话
        //result不为空，result.serviceSessionId就是正在进行中的会话ID
      })

从本地会话中获取缓存的消息列表

let conversation = VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername);
    if(conversation){
        conversation.getAllMessages();
    }

从本地数据库加载会话的消息列表

//toChatUsername:IM服务号；startMsgId：开始的消息id，往前加载；pageSize:分页加载的消息数量；
    //startMsgId为undefined时，从最新消息往前加载
    VisitorClient.getInstance().getConversationManager().getConversation(toChatUsername).loadMessages(msgId, pageSize)

清空IM服务号对应的本地会话中的聊天记录

//toChatUsername IM服务号
    VisitorClient.getInstance().getConversationManager().clearConversation(toChatUsername)

设置访客属性

设置访客通用属性

//会设置在ext的weichat字段下
    //sendMessage之前调用
    let visitorInfo = new VisitorInfo()
      .setTrueName('真实姓名')
      .setUserNickname('昵称')
      .setPhone('188888888888')
      .setCompanyName('公司名称')
      .setEmail('88888888@qq.com')
      .setQq('88888888')
      .setDesc('访客描述')
      .setTags(['vip1'])//vip客户
    message.addVisitorInfo(visitorInfo)

设置访客自定义属性

//设置在visitorInfo访客属性对象中
    //customColumn为json字符串，可自行定义其内容
    let customColumn = "{\"custom\":\"自定义参数内容\",\"age\":18,\"test\":true}"
    visitorInfo.setCustomColumn(customColumn)

设置进线路由指定

指定坐席技能组接待

//会设置在ext的weichat字段下
    //sendMessage之前调用
    message.addQueueIdentityInfo("技能组名称")

指定坐席接待

//会设置在ext的weichat字段下
    //sendMessage之前调用
    message.addAgentIdentityInfo("qby@77909.com")

设置业务路由标识

//会设置在ext的weichat字段下
    //sendMessage之前调用
    message.addRoutingRuleFlag("testFlag")

获取欢迎语

获取企业欢迎语

//获取企业欢迎语,一般需要先调用asyncGetCurrentSessionInfo判断没有正在进行中会话时调用
    VisitorClient.getInstance().getVisitorManager().asyncGetEnterpriseWelcome()
      .then((result) => {
        if (result) {
          //创建接收消息并保存在数据库
          VisitorClient.getInstance().getVisitorManager().saveMessage(this.createReceiveTxtMessage(result))
          //TODO 更新消息列表
        }
      })

获取机器人欢迎语

//获取机器人欢迎语,一般需要先调用asyncGetCurrentSessionInfo判断没有正在进行中会话时调用
    VisitorClient.getInstance().getVisitorManager().asyncGetRobotWelcome()
      .then((result) => {
        if (result) {
          let welcomeObj: RobotWelcomeData = JSON.parse(result);
          if (welcomeObj) {
            let welcomeStr = welcomeObj.greetingText
            if (welcomeStr) {
              //欢迎语内容
              welcomeStr = welcomeStr.replaceAll("&amp;quot;", "\"");
              if (welcomeStr != "null") {
                //欢迎语类型,TODO 根据类型创建想要展示的Message并保存在数据库，UI做相应显示
                switch (welcomeObj.greetingTextType) {
                //type为0代表是文字消息的机器人欢迎语
                //type为1代表是菜单消息的机器人欢迎语
                //type为2代表是图片消息的机器人欢迎语
                //type为4代表是图文消息的机器人欢迎语
                //type为5代表是答案组消息的机器人欢迎语
                }
              }
            }
          }
        }
      })

满意度评价

1.主动获取满意度评价邀请消息

//serviceSessionId为当前客服系统会话ID,需要先调用asyncGetCurrentSessionInfo获取
    VisitorClient.getInstance().getVisitorManager().asyncGetInviteEvaluation(serviceSessionId)

2.发送评价信息

//从消息中获取满意度相关信息，例如：级别、标签列表等。
    let evaluationInfo = MessageHelper.getChatEvaluation(currentMessage)
    // visitor访客主动评价，agent坐席邀请，system强制邀请访客，点击关闭窗口或会话结束
    let evaluateWay = "agent"
    if (evaluationInfo && evaluationInfo.inviteId != undefined) {
      let inviteId = this.evaluationInfo.inviteId
      if (Number(inviteId) == 0) {
        evaluateWay = "visitor"
      }
    }
    //detail为评价的文字内容信息，currentDegree为选择星标后从evaluationInfo查到的对应level的AppraiseTags
    //selectedTags 为选中的标签信息AppraiseTagItem的集合；selectResolutionParams为选中的问题解决评价标签集合
    MessageHelper.sendEvalMessage(currentMessage, evaluateWay, detail, currentDegree,
      selectedTags,
      selectResolutionParams, {
        onSuccess() {
          //发送成功
        },
        onError(errCode, errDesc) {
          //发送失败
        }
      })

3.是否显示问题解决评价

VisitorClient.getInstance()
      .getVisitorManager()
      .asyncGetIfShowResolution()
      .then((value) => {
        //true/false
        this.showResolution = value
      })

4.获取问题解决评价引导语

VisitorClient.getInstance()
      .getVisitorManager()
      .asyncGetResolutionWord(serviceSessionId)
      .then((value) => {
        //引导语，如:请问客服是否解决了您的问题？
        if (value) {
          this.resolutionTip = value
        }
      })

5.获取问题解决评价列表

VisitorClient.getInstance()
      .getVisitorManager()
      .asyncResolutionParams(serviceSessionId)
      .then((value:ResolutionParam[] | undefined) => {
        //返回问题解决评价列表
        if (value && value.length > 1) {
          //给第一个显示的标签赋值，如：已解决
          let param0 = value[0].name
          if (param0) {
            this.solve = param0
          }
          //给第二个显示的标签赋值，如：未解决
          let param1 = value[1].name
          if (param1) {
            this.reject = param1
          }
        }
      })

6.获取邀请评价引导语

VisitorClient.getInstance().getVisitorManager().asyncGetEnquiryInviteWord(this.sessionId)
      .then((value) => {
        //邀请引导语，如：请对我的服务做出评价
        if (value) {
          this.inviteTip = value
        }
      })

留言功能

1.创建留言

let creator: CreatorBean = {
      name: this.labelName,//标题
      phone: this.phone,//电话
      email: this.email//邮箱
    }
    let leaveMsg: LeaveMsg = {
      content: this.content,//留言内容
      subject: this.theme,//留言主题
      creator: creator,
    }
    //toChatUsername:IM服务号；projectId：租户留言ID
    VisitorClient.getInstance()
      .getLeaveMsgManager()
      .asyncCreateLeaveMessage(leaveMsg, toChatUsername, projectId)

2.获取留言列表

//toChatUsername:IM服务号；projectId：租户留言ID
    VisitorClient.getInstance()
          .getLeaveMsgManager()
          .asyncGetLeaveMessages(toChatUsername, projectId)

3.创建留言评论

let attachments:ArrayList<AttachmentData> = new ArrayList()
    //评论里可添加附件，type为image、audio或file
    let attachment:AttachmentData = {
      name:"附件名称",
      url:"https://xxx",//附件url
      type:"img",
    }
    attachments.add(attachment)
    let creatorBen: CreatorBean = {
      name: "评论人姓名",
      username: VisitorClient.getInstance().currentUserName(),//当前用户ID
      type: "VISITOR"//固定为”VISITOR“，不可更改
    }
    let commentData: NewCommentData = {
      content: this.content,//评论内容
      creator: creatorBen,
      attachments: attachments.convertToArray()
    }
    //toChatUsername:IM服务号；projectId：租户留言ID；ticketId:评论的留言条目ID
    VisitorClient.getInstance()
      .getLeaveMsgManager()
      .asyncCreateLeaveMsgComment(commentData, toChatUsername, projectId, ticketId)

4.获取留言评论列表

//toChatUsername:IM服务号；projectId：租户留言ID；ticketId:评论的留言条目ID
    VisitorClient.getInstance()
          .getLeaveMsgManager()
          .asyncGetLeaveMsgComments(toChatUsername, projectId, ticketId)

自定义iframe参数 {updateVisitorInfoSrc}

//会在ext下设置{"cmd":{"updateVisitorInfoSrc":{"params":paramsObj}}}
    //action:命令，这里可随便传个值，如：”cmd“；toChatUsername:IM服务号；
    let message = Message.createCmdSendMessage(action, this.toChatUsername)
    if (message) {
      let paramsObj:VisitorInfoParams = {
        "param1": 12,
        "param2": "你好"
      };
      //paramsObj内的key/value可自行定义
      message.updateIframeParams(paramsObj)
      VisitorClient.getInstance().getVisitorManager().sendMessage(message)
    }

高级功能

显示排队人数

//初始化前设置
    //需要开通sessionCreatedNoticeEnable、sessionOpenedNoticeEnable、sessionTransferNoticeEnable、sessionAbortedNoticeEnable、sessionClosedNoticeEnable事件
    mVisitorOptions.showVisitorWaitCount()
    //聊天页面添加
    waitCountListener: VisitorWaitListener = {
      waitCount(num: number) {
        //TODO 更新排队人数
      }
    }
    VisitorClient.getInstance().getVisitorManager().addVisitorWaitListener(this.waitCountListener);

显示坐席输入状态

//初始化前设置
    //需要开通sessionOpenedNoticeEnable、sessionAbortedNoticeEnable、sessionClosedNoticeEnable事件
    mVisitorOptions.showAgentInputState()

坐席实现消息预知功能

//初始化前设置
    mVisitorOptions.showMessagePredict()

访客状态通知

//开始状态上报
    CecOfflineReportUtil.getInstance().startReport(toChatUsername)
    //结束状态上报
    CecOfflineReportUtil.getInstance().stopReport(toChatUsername)

开启/关闭本地日志（默认开启）

//初始化时调用
    let mVisitorOptions = new VisitorOptions();
    mVisitorOptions.setConsoleLog(false)
    VisitorClient.getInstance().init(mContext, visitorOptions)

取本地日志

//在控制台使用hdc命令
    hdc file recv /data/app/el2/100/base/{包名}/{AppKey}/core_log
    //例：hdc file recv /data/app/el2/100/base/com.easemob.helpdesk.huawei/1197231114210800#demo/core_log