微信开发模式-假Token方案

1. 方案说明

1.1 方案简介

1）由于微信只允许一个中转服务和微信进行数据交互，所以，在此基础上，小能是无法直接和微信进行数据交互的。
而想在此场景下，企业公众微信接入小能在线客服系统，只能由中转服务和小能进行交互。
所有数据由中转服务在中间连接微信和小能，进行数据中转。小能定义此对接模式为复杂开发模式。

2）开发工作量：
上行消息，消息推送给小能方
下行消息，需集成方开发5个接口用于数据交互 
消息接收URL、图片语音上传URL、图片语音下载URL、Token URL、用户基本信息URL

1.2 运行原理

上行消息：用户 ---- 微信 ---- 中转服务 ---- 小能

下行消息：小能 ---- 中转服务 ---- 微信 ---- 用户

1.3 方案流程

如上图所示，流程如下：

1）用户在微信聊窗中发起咨询，消息发给微信

2）微信把消息POST发送出去，将消息中转至第三方或管理后台

3）第三方或管理后台将消息转发送给小能服务器；小能自行处理连接到客服，显示到客户端上

4）客服在客户端中回复消息，小能服务器把消息回复给第三方或管理后台

5）第三方或管理后台转发消息推送给微信

6）微信将消息主动推送给微信用户

2. 名词解释

1）中转服务:和微信对接交互的服务。以配置到微信公众平台开发模式下的服务器url和token为主。一般配置此选项的对象为两个，一个是第三方，如：微盟、丁香 园、微信海。另一个是企业自行对接微信，开发的管理后台。小能把第三方和自行开发的管理后台，统称为中转服务。

2）接口：双方交互数据的一种约定。根据微信开发文档的要求，所有数据交互均采用接口进行互动。当A方调用B方接口发起请求，传递数据，B方收到数据之后，要及时给A方返回响应。接口说明

3）XML与JSON：最新微信公众开发文档要求，微信往外给接收方发送消息采用XML格式发送消息。当接收方给微信推送消息服务，需采用json格式。

3. 各消息流运行流程细节

3.1 文本消息

红色数字部分为开发任务

如上图所示，流程如下：（1-5为上行消息流程，6-12为下行消息流程）

1）用户发送文本消息给微信

2）微信将文本消息，以XML格式，发送至中转服务，微信发送的对象为：在开发模式基本信息项，配置的服务器地址Url和Token的XML消息微信给出规范要求文档：接收普通消息规范文档

示例格式：

<xml>
<ToUserName><![CDATA[toUser]]></ToUserName>  //开发者微信号
<FromUserName><![CDATA[fromUser]]></FromUserName>  //发送方帐号（一个OpenID）
<CreateTime>1348831860</CreateTime>  //消息创建时间（整型）
<MsgType><![CDATA[text]]></MsgType>  //text
<Content><![CDATA[this is a test]]></Content>  //文本消息内容
<MsgId>1234567890123456</MsgId>  //消息id，64位整型
</xml>

3）当中转服务收到微信的xml消息，请及时返回给微信一个响应。避免微信在5秒内收不到响应，提醒用户，该公众号暂时无法提供服务。（此过程在没有对接小能就应该处理好，已经处理过的，可忽略） 详细解释说明文档参考：接收普通消息规范文档

4）中转服务，需在自己的后台，定义一个方法，把微信的XML，转发给小能。这个时候需要小能提供接收消息的接口：

小能服务器人工对话接口，正式地址URL：https://thirdparty.ntalker.com/wechat

注意事项：

A：http请求小能方式：POST

B：Content-type类型需指定为：text/xml

C：可参考小能提供的demo，开发接口文档（仅供参考，php和java语言）

5）小能收到中转服务的请求，解析xml数据，然后呈现到小能客户端，同时返回响应给中转服务。 （返回的响应是一个空）截止到第五步，上行消息全部通过。联调标准以小能客户端收到消息为主。 中转服务在上行消息和小能交互，只需做第4步开发（第3步属于中转服务和微信的交互）

6）小能请求Token接口

小能是把和小能交互的一方，当做微信，所以在小能的角度，把中转服务当做了微信。

根据微信的开发文档规范要求，请求一个接收消息接口，需加上access_token，而access_token是通过接口获取。

所以这里中转服务，需模拟微信开发一个Token接口，模拟小能获取微信token，用于数据交互。此Token用于文本、图片、语音的交互。Token接口规范文档

示例：

A：http请求方式: GET

B：正确举例（请勿加参数）：

https://api.weixin.qq.com/cgi-bin/token

C：错误举例：

https://api.weixin.qq.com/cgi-bin/token?name=123

D：参数要求(小能访问token接口自动加的参数)：

其中appid和secret，这里是模拟微信的要求，所以，此处的这两个值，是假值，并非真的appid和secret

7）小能请求中转服务模拟的Token接口，中转服务返回响应，返回格式要求：

{
    "access_token":"ACCESS_TOKEN",
    "expires_in":7200
}

由于Token接口，appid和secret都是模拟出来的假的，所以，返回的响应，也是按照微信的格式要求,access_token也是假值。expires_in也是假值，并非固定的7200。凭证的有效时间可大可小

建议：

A：access_token,由于只有小能和中转服务交互使用，最好做成固定的，并非一定要做成动态的

B：多个公众号接入小能，可根据appid和secret，返回access_token做成不同的值，用于openid做映射，区别此openid对应的真实微信原始ID

8）小能取出access_token，并将客服的消息发送给中转服务，此时中转服务要提供：消息接收接口

消息接收接口规范：(需注意，提供的接口，不能带参数)
正确举例：
https://api.weixin.qq.com/cgi-bin/message/custom/send
错误举例：
https://api.weixin.qq.com/cgi-bin/message/custom/send?name=123
小能发的消息是一个json包，并非XML，格式参考微信规范文档要求：
Json数据类型：Content-type=application/json
各消息类型所需的JSON数据包如下： 
发送文本消息 
{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    }
}
发送图片消息 
{
    "touser":"OPENID",
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"
    }
}
发送语音消息 
{
    "touser":"OPENID",
    "msgtype":"voice",
    "voice":
    {
      "media_id":"MEDIA_ID"
    }
}

9）中转服务收到小能的文本消息，要返回响应给小能，返回信息格式如下：

{
     "errcode" : 0,
     "errmsg" : "ok",
}

10）中转服务把消息，发送给微信

11）微信接收到消息，返回给中转服务器响应

12）微信把消息发送给用户

3.2 用户发图片、语音给小能流程

红色数字部分为开发任务

如上图所示，流程如下：

1）用户发送一个语音给微信

2）微信把语音XML消息发给中转服务

3）中转服务返回微信响应，到此过程，只是XML消息在运转，但是语音源文件，还是在微信服务器那里，需要中转服务把语音源文件下载到本地服务器上

4）中转服务把语音XML消息，转发小能

5）小能返回响应

6）小能请求token接口

7）中转服务返回token

8）小能从XML消息里面，取出media_id，按照微信的规范要求，去中转服务那里下载此语音文件。这里需要集成方的中转服务开发一个多媒体文件下载接口：下载临时多媒体文件文档

（下面多媒体文件文档说明）

A：http请求方式：GET

B：请勿在接口地址后面添加参数（小能会自动添加）

正确接口样例：

https://api.weixin.qq.com/cgi-bin/media/get

错误接口样例：

https://api.weixin.qq.com/cgi-bin/media/get?name=123

C：小能请求下载接口地址的示例格式:

http://file.api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID

9）中转服务返回响应，返回相应说明

返回说明：

正确情况下的返回HTTP头如下：

HTTP/1.1 200 OK
Connection: close
Content-Type: image/jpeg
Content-disposition: attachment; filename="MEDIA_ID.jpg"
Date: Sun, 06 Jan 2013 10:20:18 GMT
Cache-Control: no-cache, must-revalidate
Content-Length: 339721
curl -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

3.3 客服发送图片给用户流程

红色数字部分为开发任务

如上图所示，流程如下：

1）小能请求中转服务token接口

2）中转服务返回token

3）小能请求中转服务上传多媒体文件接口，需要集成方的中转服务开发此接口。上传临时多媒体文件文档

A：http请求方式：POST/FORM

B：接口避免添加参数（小能会自动添加参数）

正确格式：

http://api.weixin.qq.com/cgi-bin/media/upload

错误格式：

http://api.weixin.qq.com/cgi-bin/media/upload?name=123

C：调用示例

http://file.api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE

4）小能把图片上传给中转服务之后，需中转服务，实时上传给微信

5）微信收到中转服务上传的图片，返回给中转服务一个响应

正确情况下的返回JSON数据包结果如下：

{
  "type":"TYPE",
  "media_id":"MEDIA_ID",
  "created_at":123456789
}

6）中转服务把微信返回的json数据，返回给小能

7）小能取出json数据里面的media_id，整理成文本消息发送给中转服务

8）中转服务返回接收文本消息的响应

9）中转服务把json消息，转发给微信

10）微信返回响应

11）微信把消息发给用户，呈现图片

3.4 获取微信用户昵称信息接口

用于在客服端显示访客微信昵称（不开发默认显示访客openID），需集成方中转服务开发一个用户信息接口：获取用户昵称文档

返回说明，昵称取自nickname字段的值：

{
  "subscribe": 1, 
  "openid": "o6_bmjrPTlm6_2sgVt7hMZOPfL2M", 
  "nickname": "Band", 
  "sex": 1, 
  "language": "zh_CN", 
  "city": "广州", 
  "province": "广东", 
  "country": "中国", 
  "headimgurl":"http://wx.qlogo.cn/mmopen/g3MonUZtNHkdmzicIlibx6iaFqAc56vxLSUfpb6n5WKSYVY0ChQKkiaJSgQ1dZuTOgvLLrhJbERQQ4eMsv84eavHiaiceqxibJxCfHe/0", 
  "subscribe_time": 1382694957,
  "unionid": " o6_bmasdasdsad6_2sgVt7hMZOPfL"
  "remark": "",
  "groupid": 0
}

4. 客服端配置接口地址

4.1 选择"接入微信号"后，点击"开发模式"

4.2 填写：微信服务号名称、微信原始ID、微信APPID、AppSecret

4.3 填写五个接口地址URL