基础信息

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'

请求参数

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

返回值

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