# 開發指引
[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來管理客服帳號、分配客服會話和收發客服消息，開發者請做好處理。
### 幫助其他企業管理微信客服
微信客服還提供「[幫助其他企業管理微信客服](http://www.hmoore.net/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失效時重新獲取的邏輯。
