# 开发指引
[TOC]
## 概述
### 什么是微信客服
微信客服由腾讯微信团队为企业打造，用于满足企业的客服需求，帮助企业做好客户服务。企业可以在微信内、外各个场景中接入微信客服，用户可以发起咨询，企业可通过API来收发消息。
企业可在[微信客服官网](https://work.weixin.qq.com/kf/ "微信客服官网")使用企业微信扫码开通微信客服，开通后即可使用。
* **注：**目前微信客服正在内测，若你的企业微信已完成主体验证，且最近有使用“客户联系”相关功能（如使用企业微信添加微信好友），即可开通参与内测。
### 微信客服提供哪些API
开发者通过微信客服提供的相关API，可实现通过API来管理微信客服帐号、收发客服消息，并可基于此定制丰富的客服管理功能，如实现接入客服机器人、自定义会话路由分配、统计客服数据等。
具体的接口能力包括：
1. 客服帐号管理
2. 客服消息收发
3. 客户基本信息获取
4. 在App或微信小程序里接入微信客服
当用户进入微信客服会话或向微信客服发送消息时，企业将收到来自微信客服推送过来的事件或消息，开发者可依据自身业务逻辑进行响应。
### 如何开启API
微信客服管理员可以在“微信客服管理后台-开发配置”处开启API。按照指引填写回调配置后即可开启成功。
开启API之后，微信客服的所有消息与事件都回调给企业，企业可以调用API来收发消息、分配会话等。
**注意：**
1. 企业须已在微信客服管理后台处使用微信客服且已开启API，才能正常调用微信客服相关API。
2. 开启API后，仅可通过API来管理客服帐号、分配客服会话和收发客服消息，开发者请做好处理。
### 帮助其他企业管理微信客服
微信客服还提供「[帮助其他企业管理微信客服](https://www.kancloud.cn/dabashan/qiwei/2376082 "帮助其他企业管理微信客服")」的能力。企业可以作为第三方帮助其他企业管理微信客服。当授权企业发起授权管理微信客服请求时，微信客服后台会将授权信息等推送给第三方后台。授权成功后，第三方可以接管来自该授权企业的微信客服的所有消息或事件，帮助该企业管理微信客服。
## 术语介绍
### 企业ID
企业开通的每个微信客服，都对应唯一的企业ID，企业可在微信客服管理后台的企业信息处查看。
### Secret
Secret是微信客服用于校验开发者身份的访问密钥，为了保证企业数据的安全，切记勿把密码直接交给第三方开发者或直接存储在代码中。企业成功注册微信客服后，可在「微信客服管理后台-开发配置」处获取。该信息在使用微信客服API时会用到。若不点击重置，该secret则一直保持不变。
### access\_token
access\_token是企业后台去微信微信客服后台获取信息时的重要票据，由企业ID和Secret产生。所有接口在通信时都需要携带此信息用于验证接口的访问权限。
## 回调配置
在集成微信客服与内部系统时，开发者往往需要搭建一个回调服务。
配置回调服务，需要有三个配置项，分别是：URL, Token, EncodingAESKey。
**首先，URL为回调服务地址，由开发者搭建，用于接收通知消息或者事件。**
**其次，Token用于计算签名，由英文或数字组成且长度不超过32位的自定义字符串。**
开发者提供的URL是公开可访问的，这就意味着拿到这个URL，就可以往该链接推送消息。
那么URL服务需要解决两个问题：
* 如何分辨出是否为微信客服来源
* 如何分辨出推送消息的内容是否被篡改
通过数字签名就可以解决上述的问题。具体为：约定Token作为密钥，仅开发者和微信客服后台知道，在传输中不可见，用于参与签名计算。微信客服后台在推送消息时，将消息内容与Token计算出签名。开发者接收到推送消息时，也按相同算法计算出签名。如果为同一签名，则可信任来源为微信客服，并且内容是完整的。
* 如果非微信客服来源，由于攻击者没有正确的Token，无法算出正确的签名；
* 如果消息内容被篡改，由于开发者会将接收的消息内容与Token重算一次签名，该值与参数的签名不一致，则会拒绝该请求。
**最后，EncodingAESKey用于消息内容加密，由英文或数字组成且长度为43位的自定义字符串。**
由于消息是在公开的因特网上传输，消息内容是可被截获的，如果内容未加密，则截获者可以直接阅读消息内容。若消息内容包含一些敏感信息，就非常危险了。EncodingAESKey就是在这个背景基础上提出，将发送的内容进行加密，并组装成一定格式后再发送。
## 获取调用凭证access\_token
有了微信客服Secret，就可以获取access\_token。获取access\_token是调用企业微信API接口的第一步，相当于创建了一个登录凭证，其它的业务API接口，都需要依赖于access\_token来鉴权调用者身份，流程大概如下：
**请求方式：**GET（**HTTPS**）
**请求地址：**https://qyapi.weixin.qq.com/cgi-bin/gettoken?corpid=ID&corpsecret=SECRET
*注：此处标注大写的单词ID和SECRET，为需要替换的变量，根据实际获取值更新。其它接口也采用相同的标注，不再说明。*
**参数说明：**
| 参数 | 必须 | 说明 |
| --- | --- | --- |
| corpid | 是 | 企业ID |
| corpsecret | 是 | 微信客服Secret |
**返回结果：**
~~~
{ "errcode": 0, "errmsg": "ok", "access_token": "accesstoken000001", "expires_in": 7200}
~~~
**参数说明：**
| 参数 | 说明 |
| --- | --- |
| errcode | 出错返回码，为0表示成功，非0表示调用失败 |
| errmsg | 返回码提示语 |
| access\_token | 获取到的凭证，最长为512字节 |
| expires\_in | 凭证的有效时间（秒） |
**注意事项：**
1. 微信客服开发者需要缓存access\_token，用于后续接口的调用（注意：不能频繁调用gettoken接口，否则会受到频率拦截）。当access\_token失效或过期时，需要重新获取。
2. access\_token的有效期通过返回的expires\_in来传达，正常情况下为7200秒（2小时），有效期内重复获取返回相同结果，过期后获取会返回新的access\_token。
3. access\_token至少保留512字节的存储空间。
4. 微信客服可能会出于运营需要，提前使access\_token失效，开发者应实现access\_token失效时重新获取的逻辑。
