微信全模拟对接 - Udesk

基础信息

Udesk提供的一种独特的微信公众号接入方案，无需Udesk获取微信公众号权限，而是写一个中间件获取微信公众号权限，将符合客服场景的消息和事件转发到Udesk。

对于中间件的开发人员来说，需要处理以下几种情况。

1. 接收来自微信服务器的消息，将其转发给UDESK系统，并将UDESK系统的返回传给微信服务器  
2. 接收来自UDESK系统的请求，将其转发给微信服务器，并将微信服务器的返回传给UDESK系统  
  + 当收到POST请求，且无query参数时，视为推送消息  
  + 当收到POST请求，且带type=TYPE的query的参数，视为上传多媒体消息(即新增临时素材)  
  + 当收到GET请求，且带media_id=MEDIA_ID的query参数，视为请求获取多媒体消息(即获取临时素材)  
  + 当收到GET请求，且带openid=OPEN_ID的query参数，视为请求获取用户基本信息

注意 UDESK系统向模拟中间件推送消息时，不会带appid，如果客户有多个公众号接入，建议将模拟域名设置为以下格式。

1. http://udesk.simulate_weixin.com/APPID
2. http://udesk.simulate_weixin.com?appid=APPID

1. 接收消息

当微信服务器向模拟中间件发送消息后，模拟中间件将微信发送的消息透传给UDESK系统，并将UDESK系统的返回传递给微信服务器。

请求说明

发起方	接收方	请求方式
模拟中间件	UDESK系统	POST

POST 'UDESK提供的URL'

注 URL的查看位置：【管理中心-渠道管理-微信-管理】中的“URL”

请求参数

此处的请求参数应与微信开发者文档-消息管理-接收普通消息保持一致

返回值

UDESK系统的返回有两种情况，对这两种返回情况，模拟中间件都可直接将其透传给微信服务器
1. 空字符串， ""
2. 特定XML结构的信息，详见微信开发者文档-被动回复用户消息

示例

# 调用示例
curl udesk.udesk.com/weixin/olloowpoeakkskknx0ijm -d '{
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>1348831860</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[this is a test]]></Content>
  <MsgId>1234567890123456</MsgId>
</xml>
}'

<!-- 返回示例 -->
<xml>
  <ToUserName><![CDATA[toUser]]></ToUserName>
  <FromUserName><![CDATA[fromUser]]></FromUserName>
  <CreateTime>12345678</CreateTime>
  <MsgType><![CDATA[text]]></MsgType>
  <Content><![CDATA[你好]]></Content>
</xml>

2. 推送消息

UDESK系统向模拟中间件推送消息，模拟中间件请求微信服务器客服消息-发消息接口，并将微信服务器的返回值传给UDESK系统。

模拟中间件需要将请求体中的内容转成json格式再传给微信服务器。
模拟中间件给微信服务器推送消息方法，详见微信开发者文档-客服消息-客服接口.发消息

发起方	接收方	请求方式
UDESK系统	模拟中间件	POST

请求说明

POST '客户填写的模拟域名地址'

注：模拟域名配置位置：【管理中心-渠道管理-微信-管理】中的“模拟域名”

请求参数

发送文本消息

参数	说明
touser	客户的openid
msgtype	消息类型，此处为'text'
text[content]	消息内容

发送图片消息

参数	说明
touser	客户的openid
msgtype	消息类型，此处为'image'
image[media_id]	多媒体消息ID

发送语音消息

参数	说明
touser	客户的openid
msgtype	消息类型，此处为'voice'
voice[media_id]	多媒体消息ID

发送视频消息

参数	说明
touser	客户的openid
msgtype	消息类型，此处为'video'
video[media_id]	多媒体消息ID

发送图文消息

参数	说明
touser	客户的openid
msgtype	消息类型，此处为'news'
news[articles]	图文消息内容，是一个数组

articles详情

参数	说明
title	标题
description	描述
url	外链地址
picurl	图片地址

返回值

详见微信开发者文档-客服消息-客服接口.发消息的返回值

模拟中间件需将微信服务器的返回值透传给UDESK系统，UDESK系统会根据返回值判断消息是否成功发送.

示例

# 调用示例，以文本消息为例
# Content-Type : application/x-www-form-urlencoded
curl www.simulate_weixin.com -d 'touser=o2IGD0a1OvYAEBfPRa8t34Wc2nUo&msgtype=text&text[content]=123'

3. 上传多媒体文件

UDESK系统上传多媒体文件，模拟中间件请求微信服务器新增临时素材接口，并将微信服务器的返回值透传给UDESK系统。

模拟中间件向微信服务器上传文件的方法，详见微信开发者文档-素材管理-新增临时素材

发起方	接收方	请求方式
UDESK系统	模拟中间件	POST

请求说明

POST '客户填写的模拟域名地址?type=TYPE'

请求参数

参数	说明
type	文件类型，image/voice/video
media	值为文件流

返回值

详见微信开发者文档-素材管理-新增临时素材的返回值

示例

# 调用示例(使用curl命令，用FORM表单方式上传一个多媒体文件):
# Content-Type: multipart/form-data
curl -F media=@test.jpg "www.simulate_weixin.com?type=TYPE"

4. 获取多媒体文件

UDESK系统获取多媒体文件，模拟中间件请求微信服务器获取临时素材接口，并将微信服务器的返回值透传给UDESK系统。

模拟中间件请求微信服务器获取文件的方法，详见微信开发者文档-素材管理-获取临时素材

发起方	接收方	请求方式
UDESK系统	模拟中间件	GET

请求说明

GET '客户填写的模拟域名地址?media_id=MEDIA_ID&access_token=ACCESS_TOKEN'

请求参数

参数	说明
access_token	虚拟的access_token
media_id	微信服务器中的媒体文件ID

返回值

详见微信开发者文档-素材管理-获取临时素材的返回值

示例

# 调用示例
curl www.simulate_weixin.com?media_id=abc&access_token=123

备注

为什么UDESK系统要上传和获取多媒体文件?

在收发消息时,图片,语音等多媒体消息的获取和调用等操作,是通过微信内部的media_id来进行的.  
发送图片,语音等消息时,需上传文件内容到微信服务器获取media_id  
收到图片,语音等消息时,需向微信服务器获取实际的文件内容

5. 获取客户头像昵称

当UDESK系统需要获取客户头像昵称时，UDESK系统会请求模拟中间件，模拟中间件请求微信服务器获取用户基本信息接口，并将微信服务器的返回值传给UDESK系统。

模拟中间件去微信服务器请求客户基本信息的方法，详见微信开发者文档-用户管理-获取用户基本信息(UnionID机制)

发起方	接收方	请求方式
UDESK系统	模拟中间件	GET

请求说明

GET '客户填写的模拟域名地址?openid=OPEN_ID&lang=zh_CN'

请求参数

参数名	备注
openid	客户的openid
lang	返回国家地区语言版本，目前仅支持zh_CN 简体

返回值

模拟中间件将微信服务器返回的信息透传给UDESK系统

详见微信开发者文档-用户管理-获取用户基本信息(UnionID机制)

示例

# 请求示例
curl 'www.simulate_weixin.com?openid=o-NbF1HPuegFK5sa1psr7EEeSTSg&lang=zh_CN'

备注

UDESK系统会删除nickname中特殊字符

6. 获取模板消息

当UDESK系统需要获取模板消息时，UDESK系统会请求模拟中间件，模拟中间件请求微信服务器获取模板列表接口，并将微信服务器的返回值传给UDESK系统。

模拟中间件去微信服务器获取模板消息的方法，详见微信开发者文档-消息管理-获取模板列表

发起方	接收方	请求方式
UDESK系统	模拟中间件	GET

请求说明

GET '客户填写的模拟域名地址/template/get_all_private_template'

请求参数

无

返回值

模拟中间件将微信服务器返回的信息透传给UDESK系统

详见微信开发者文档-消息管理-获取模板列表

示例

# 请求示例
curl 'www.simulate_weixin.com/template/get_all_private_template'

# 返回示例
{
  "template_list": [
    {
      "template_id": "iPk5sOIt5X_flOVKn5GrTFpncEYTojx6ddbt8WYoV5s",
      "title": "领取奖金提醒",
      "primary_industry": "IT科技",
      "deputy_industry": "互联网|电子商务",
      "content": "{ {result.DATA} }\n\n领奖金额:{ {withdrawMoney.DATA} }\n领奖  时间:    { {withdrawTime.DATA} }\n银行信息:{ {cardInfo.DATA} }\n到账时间:  { {arrivedTime.DATA} }\n{ {remark.DATA} }",
      "example": "您已提交领奖申请\n\n领奖金额：xxxx元\n领奖时间：2013-10-10 12:22:22\n银行信息：xx银行(尾号xxxx)\n到账时间：预计xxxxxxx\n\n预计将于xxxx到达您的银行卡"
    }
  ]
}

7. 发送模板消息

当UDESK系统需要发送模板消息时，UDESK系统会请求模拟中间件，模拟中间件请求微信服务器发送模板列表接口，并将微信服务器的返回值传给UDESK系统。

模拟中间件去微信服务器发送模板消息的方法，详见微信开发者文档-消息管理-发送模板列表

发起方	接收方	请求方式
UDESK系统	模拟中间件	POST

请求说明

POST '客户填写的模拟域名地址/message/template/send'

请求参数

详见微信开发者文档-消息管理-发送模板列表

{
  "touser": "OPENID",
  "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
  "url": "http://weixin.qq.com/download",
  "miniprogram": {
    "appid": "xiaochengxuappid12345",
    "pagepath": "index?foo=bar"
  },
  "data": {
    "first": {
      "value": "恭喜你购买成功！",
      "color": "#173177"
    },
    "keyword1": {
      "value": "巧克力",
      "color": "#173177"
    },
    "keyword2": {
      "value": "39.8元",
      "color": "#173177"
    },
    "keyword3": {
      "value": "2014年9月22日",
      "color": "#173177"
    },
    "remark": {
      "value": "欢迎再次购买！",
      "color": "#173177"
    }
  }
}

返回值

模拟中间件将微信服务器返回的信息透传给UDESK系统

详见微信开发者文档-消息管理-发送模板列表

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

示例

# 请求示例
curl 'www.simulate_weixin.com/message/template/get_all_private_template' -d '
  {
    "touser": "OPENID",
    "template_id": "ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
    "url": "http://weixin.qq.com/download",
    "miniprogram": {
      "appid": "xiaochengxuappid12345",
      "pagepath": "index?foo=bar"
    },
    "data": {
      "first": {
        "value": "恭喜你购买成功！",
        "color": "#173177"
      },
      "keyword1": {
        "value": "巧克力",
        "color": "#173177"
      },
      "keyword2": {
        "value": "39.8元",
        "color": "#173177"
      },
      "keyword3": {
        "value": "2014年9月22日",
        "color": "#173177"
      },
      "remark": {
        "value": "欢迎再次购买！",
        "color": "#173177"
      }
    }
  }'

# 返回示例
{
  "errcode":0,
  "errmsg":"ok",
  "msgid":200228332
}

8. access_token的获取

UDESK系统不直接与微信服务器交互，无需access_token。

模拟中间件从微信获取access_token方法，详见微信开发者文档-开始开发-获取Access token

Keys	Action
`?`	Open this help
`n`	Next page
`p`	Previous page
`s`	Search

基础信息

1. 接收消息

请求说明

请求参数

返回值

示例

2. 推送消息

请求说明

请求参数

返回值

示例

3. 上传多媒体文件

请求说明

请求参数

返回值

示例

4. 获取多媒体文件

请求说明

请求参数

返回值

示例

备注

5. 获取客户头像昵称

请求说明

请求参数

返回值

示例

6. 获取模板消息

请求说明

请求参数

返回值

示例

7. 发送模板消息

请求说明

请求参数

返回值

示例

8. access_token的获取

文档反馈