# 第三方客服系统接入 - 接收用户和机器人消息

## 配置信息

例如:

- APPID: xxxxxxxxxxxxxxx
- TOKEN: xxxxxxxxxxxxxxx
- EncodingAESKey: xxxxxxxxxxxxxxx

### 配置人工客服回调接口:

请按照下面路径配置好人工客服回调接口

```
发布管理 -> 应用绑定 -> 开放API -> 回调地址
```

![authentication](https://res8.wxqcloud.qq.com.cn/wxdoc/c5f559f7-b95c-4a4f-ac2c-df2c8757bf36.png)

> 注意：当客服接入状态为`1`已接入时，第三方客服系统将不会接收到机器人回答的数据上报

接口类型:

`POST请求`

> Content-type: application/json 的 json 请求

### 请求参数说明:

| 字段      | 类型   | 是否必填 | 描述                 |
| --------- | ------ | -------- | -------------------- |
| encrypted | string | 是       | 对话内容加密后字符串 |

### 消息加解密说明:

请参考
[消息加解密接入指引](/doc/oplatform/Third-party_Platforms/2.0/Before_Develop/Message_encryption_and_decryption.md)
进行消息的解密

> 注意在使用消息解密的过程中，`MsgSignature`,`TimeStamp`,`Nonce` 3 个字段直接填入空字符串,
> 仅进行解密既可，不需要进行签名校验, 另外再使用官方提供的解密 demo 时注意不能直接使用，因为返回的数据结果不是包在 xml 中的

```
<xml>
    <Encrypt>
    <![CDATA[LDFAmKFr7U/RMmwRbsR676wjym90byw7+hhh226e8bu6KVYy00HheIsVER4eMgz/VBtofSaeXXQBz6fVdkN2CzBUaTtjJeTCXEIDfTBNxpw/QRLGLq
    qMZHA3I+JiBxrrSzd2yXuXst7TdkVgY4lZEHQcWk85x1niT79XLaWQog+OnBV31eZbXGPPv8dZciKqGo0meTYi+fkMEJdyS8OE7NjO79vpIyIw7hMBtEXPBK/tJGN5m5SoAS
    6I4rRZ8Zl8umKxXqgr7N8ZOs6DB9tokpvSl9wT9T3E62rufaKP5EL1imJUd1pngxy09EP24O8Th4bCrdUcZpJio2l11vE6bWK2s5WrLuO0cKY2GP2unQ4fDxh0L4ePmNOVFJ
    wp9Hyvd0BAsleXA4jWeOMw5nH3Vn49/Q/ZAQ2HN3dB0bMA+6KJYLvIzTz/Iz6vEjk8ZkK+AbhW5eldnyRDXP/OWfZH2P3WQZUwc/G/LGmS3ekqMwQThhS2Eg5t4yHv0mAIei
    07Lknip8nnwgEeF4R9hOGutE9ETsGG4CP1LHTQ4fgYchOMfB3wANOjIt9xendbhHbu51Z4OKnA0F+MlgZomiqweT1v/+LUxcsFAZ1J+Vtt0FQXElDKg+YyQnRCiLl3I+GJ/c
    xSj86XwClZC3NNhAkVU11SvxcXEYh9smckV/qRP2Acsvdls0UqZVWnPtzgx8hc8QBZaeH+JeiaPQD88frNvA==]]> </Encrypt>
    <MsgSignature></MsgSignature>
    <TimeStamp>1411034505</TimeStamp>
    <Nonce></Nonce>
</xml>
```

> 而是直接将`Encrypt` 返回在 JSON 中,直接调用官方 Demo 示例中的`decrypt`方法就可以了 而不是 `decryptMsg`

解密后的数据格式如下:

```

<xml>
  <userid>用户的唯一ID，（通常为用户在微信的openid）</userid>
  <appid>应用的appid</appid>
  <content>
    <msg>机器人或用户的的内容</msg>
  </content>
  <event>userEnter</event>
  <from>对话来源ID 0/1/2</from>
  <kfstate>客服接入状态 0/1/2/3</kfstate>
  <channel>渠道id 0</channel>
  <assessment>用户评价0/1/2/3/4/5</assessment>
  <createtime>unix时间戳</createtime>
</xml>

```

> `content` 字段为复合型数据结构 , 当 `from === 0` 时为顾客发送的问题, 可能为[纯文本或富文本](/miniprogram/dev/server/API/cityservice/basic/api_cityservice_sendmsgdata.md)，
> 当 `from === 1` 时为[机器人自动回复的内容](recivemsg)，当 `from === 2` 时为人工客服回复的内容
### 返回值说明:

| 字段       | 类型   | 是否必填 | 描述                    |
| ---------- | ------ | -------- | ----------------------- |
| userid     | string | 是       | 用户的微信 openid       |
| appid      | string | 是       | 公众号或小程序的 appid  |
| content    | object | 是       | 机器人回复或顾客问题    |
| channel    | number | 是       | 渠道 ID，详见渠道对映表 |
| from       | number | 是       | 对话来源                |
| event      | string | 否       | 用户触发事件            |
| kfstate    | number | 否       | 客服接入状态            |
| assessment | number | 否       | 客户评价                |

### 客服接入状态(kfstate):

| 状态 ID | 描述                                      |
| ------- | ----------------------------------------- |
| 0       | 智能客服 -- 待接入 (asking)               |
| 1       | 人工客服  -- 已接入 (personserving)       |
| 2       | 结束人工客服(对话) -- 对话关闭 (complete) |
| 3       | 待人工接入 -- 待转人工 (needperson)       |

### 对话来源(from):

| 来源 ID | 描述                                     |
| ------- | ---------------------------------------- |
| 0       | 用户发出的内容                           |
| 1       | 机器人回复的内容                         |
| 2       | 客服在微信对话开放平台上进行回复时的内容 |

### 渠道说明(channel):

| 渠道 ID | 渠道描述                                               |
| ------- | ------------------------------------------------------ |
| 0       | 接入方式为，扫码绑定的公众号、小程序接入智能对话的渠道 |
| 2       | 接入方式为，通过开放接口方式接入智能对话的渠道         |
| 6       | 接入方式为，小程序插件接入智能对话的渠道               |
| 7       | 接入方式为，网页 H5 机器人智能对话的渠道               |

### 客服触发事件(event):

| 事件 Key           | 描述             | 支持的渠道 |
| ------------------ | ---------------- | ---------- |
| userEnter          | 用户进入         | H5 机器人  |
| userQuit           | 用户离开         | H5 机器人  |
| customerStuffEnter | 客服人员开始接入 | 所有渠道   |
| customerStuffQuit  | 客服人员关闭离开 | 所有渠道   |

> 事件 `customerStuffEnter/customerStuffQuit` 出现时 会额外补充一个字段 `customerInfo`
> | 字段名称 | 描述 |
> | ------------------ | ---------------- |
> | customerInfo.name | 客服人员的微信昵称 |
> | customerInfo.avatar | 客服人员的头像 |
> | customerInfo.openid | 客服人员的微信 openid |

### 客户评价(assessment):

| assessment | 描述           |
| ---------- | -------------- |
| 0          | 非客户评价消息 |
| 1          | 很满意         |
| 2          | 满意           |
| 3          | 一般           |
| 4          | 不满           |
| 5          | 很不满         |

### 错误码说明:

```
{
    errcode: 1001,
    errmsg: "TOKEN is not valid"
}
```