一洽客服系统·工单系统-接收事件通知

在开发API-服务器交互-业务数据接收处开启接收工单数据后,当工单被更新(包括新建)时,一洽会向服务器配置处的URL推送对应的事件。

目录

  1. 选择数据接收模式
  2. 消息加解密说明
  3. 接收工单数据
  4. 工单创建
  5. 工单更新

1. 选择数据接收模式

使用管理者的权限登录一洽软件后,在更多设置-开放API页面中配置appId,消息加解密key(encodingAesKey),token.
如图:

配置信息说明:

appId:一洽系统自动生成的应用唯一值,用于接口交互时判断用户身份。

encodingAesKey(消息加解密key):由开发者手动填写或随机生成,将用作JSON/XML数据加解密密钥,为保证数据安全推荐使用密文方式传输数据。

Token:Token可由开发者可以任意填写,用作生成签名

数据传输模式:明文:原始数据字符串 密文:通过AES加密过后的字符串

名词介绍:

apiServer:一洽提供给用户的接口服务器地址,例如:api.echatsoft.com

accessToken:调用一洽接口的授权令牌

ip白名单:允许访问一洽接口服务器的来源IP

2. 消息加解密说明

什么是EncodingAESKey?
一洽采用AES对称加密算法对消息体对行加密,EncodingAESKey则是加密所用的秘钥。消息接收方用此秘钥对收到的密文消息体进行解密。

消息加解密过程和微信公众平台的消息加解密方式一致。
示例代码(包括C++、php、Java、Python和C#版本)示例代码
注:一洽的签名信息在GET请求中,微信的示例代码签名在XML结构中,Encrypt节点的加解密方式是一样的。

Java要求jdk 1.6及1.6以上
异常java.security.InvalidKeyException:illegal Key Size的解决方案:在官方网站下载JCE无限制权限策略文件(请到官网下载对应的版本, 例如JDK7的下载地址:http://www.oracle.com/technetwork/java/javase/downloads/jce-7-download-432124.html 下载后解压,可以看到local_policy.jar和US_export_policy.jar以及readme.txt,如果安装了JRE,将两个jar文件放到%JRE_HOME%\lib\security目录下覆盖原来的文件;如果安装了JDK,将两个jar文件放到%JDK_HOME%\jre\lib\security目录下覆盖原来文件

3.接收工单数据

接工单数据收>向开发者服务器URL推送相关数据,基础字段:

参数 参数类型 描述
jobId long 工单id
jobAttribute byte 工单属性,1=内部工单,2=外部工单

4. 工单创建

当工单创建时推送此消息,除了工单相关数据,开发者可登录一洽控制台,在开发API-服务器交互-工单数据处选择业务数据,包括:
会员数据、扩展数据、访客数据、路由数据,其中除了扩展数据,其它数据均只在web端创建外部工单有效。
GET参数追加:dataType=jobCreated

请求地址示例:

工单基础xml属性解释:

工单基础xml属性解释:

参数 参数类型 描述
title String 工单标题
requesterLan String 工单请求语言
requesterUserId String 请求者id,访客vipId或客服id
requesterUserType byte 请求者类型,小于0表示客服,否则为访客
styleId long 样式id
jobType byte 工单类型, 1:问题,2:事务,3:故障,4:任务
departmentId long 工单指派分组
distributeUserId long 工单指派客服
priority byte 工单优先级,1:低,2:正常,3:高,4:紧急
jobTemplateId long 工单模板id
status byte 工单状态,1:新建,2:已开启,3:待回应,4:已挂起,5:已解决,6:已关闭
replyEmail String 回复邮箱
replyPhone String 回复短信
memo String 工单备注
attachments json 工单附件列表,对象列表,格式见后Attachment字段定义
name String crm字段-姓名
phone String crm字段-手机号
qq String crm字段-qq
wechat String crm字段-微信
email String crm字段-邮箱
address String crm字段-地址
nickName String crm字段-昵称
gender byte crm字段-性别
crmMemo String crm字段-备注
maritalStatus byte crm字段-婚姻状态
age byte crm字段-年龄
birthday String crm字段-生日
jobLink String 工单链接
c1-c20 String crm自定义字段
t1-t10 String 工单自定义字段

Attachment字段定义:

对象 参数 参数类型 描述
  type byte 文件类型,固定为1
fileValue url String 文件url
  name String 文件名称
  size long 文件大小,单位:字节
  fileType int 0:其它,1:语音,2:视频,3:地理位置,4:图片

示例:

<xml>
  <jobId>1088</jobId>
  <jobAttribute>2</jobAttribute>
  <jobData>
    <title><![CDATA[标题]]></title>
    <requesterLan><![CDATA[en]]></requesterLan>
    <requesterUserId><![CDATA[79]]></requesterUserId>
    <requesterUserType>1</requesterUserType>
    <styleId>225</styleId>
    <jobType>1</jobType>
    <departmentId>2</departmentId>
    <distributeUserId>78</distributeUserId>
    <priority>3</priority>
    <jobTemplateId>4</jobTemplateId>
    <status>2</status>
    <replyEmail><![CDATA[huangzhilin2015@outlook.com]]></replyEmail>
    <replyPhone><![CDATA[18349975744]]></replyPhone>
    <memo><![CDATA[备注]]></memo>
    <attachments>
      <attachment>
        <type>1</type>
        <fileValue>
          <url><![CDATA[http://x.xx/a.png]]></url>
          <name><![CDATA[a.png]]></name>
          <size>12442</size>
          <fileType>0</fileType>
        </fileValue>
      </attachment>
      <attachment>
        <type>1</type>
        <fileValue>
          <url><![CDATA[http://x.xx/b.png]]></url>
          <name><![CDATA[b.png]]></name>
          <size>115487</size>
          <fileType>0</fileType>
        </fileValue>
      </attachment>
    </attachments>
  </jobData>
</xml>

5. 工单更新

GET参数追加:dataType=jobUpdated

请求地址示例:

当工单更新时推送此消息,消息包含更新的字段和更新的内容,目前支持通知以下字段:

参数 参数类型 描述
status byte 工单状态,1:新建,2:已开启,3:待回应,4:已挂起,5:已解决,6:已关闭,
replyTpe byte 工单回复类型,1=内部回复,2=外部回复,3=内部回复和外部回复
priority byte 工单优先级,1:低,2:正常,3:高,4:紧急
jobType byte 工单类型, 1:问题,2:事务,3:故障,4:任务
topic   主题
topicId long 主题ID
topicName String 主题名
distributeUser   处理人
staffId long 客服id
staffName String 客服名
staffRole String 客服角色名
staffLogname String 客服登录名

示例:

<xml>
  <jobId>1063</jobId>
  <jobAttribute>2</jobAttribute>
  <jobData>
    <status>5</status>
    <replyTpe>2</replyTpe>
    <priority>3</priority>
    <jobType>4</jobType>
    <topic>
      <topicId>35243</topicId>
      <topicName><![CDATA[VOC悟、如影>DJI电池管理站(TB50适用)>排查中客户掉线]]></topicName>
    </topic>
    <distributeUser>
      <staffId>79</staffId>
      <staffName><![CDATA[客服1号]]></staffName>
      <staffRole><![CDATA[超级管理员]]></staffRole>
      <staffLogname><![CDATA[11111111111]]></staffLogname>
    </distributeUser>
  </jobData>
</xml>