# 開發指引
[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失效時重新獲取的邏輯。