通过消息接口接入微信的方法

一、概述

当微信开发者后台绑定其他开发者的URL和Token时,如果想同时使用Udesk服务可以通过一个服务器与Udesk消息接口对接来实现。

通过Udesk消息接口对接服务器,消息的接收和发送均走服务器。(其中为了微信做了特别的优化,通过获得token可以直接生成符合微信规范的图片类消息无需服务器再上传到微信)

管理员登录Udesk后台【管理中心-即时通讯-消息接口接入】

udesk

二、测试接收消息通道是否正常

测试接口是否畅通:

curl https://xxxx.udesk.cn/spa1/im_callback/test?number=13574221234&email=894733082@qq.com&timestamp=20151124141451&sign=07131700A29AD987F5D9F0463CE7EFC7

传入参数

number=13574221234&email=894733082@qq.com&timestamp=20151124141451&sign=07131700A29AD987F5D9F0463CE7EFC7

参数说明

参数名称 说明
number 电话号码
email 邮箱
timestamp 时间戳
sign 按前面几个参数生成的md5 的结果

Sign 生成方式

返回参数

成功:{ "success": true }
失败:
{
  "success": false,
  "msg": "sign验证不通过"
}
参数名称 说明
success True/false,请求成功/失败
msg string格式的结果说明

三、接收消息接口

客户给客服发送消息

1、接收文本消息

接收消息接口

POST http://xxxx.udesk.cn/spa1/im_callback?number=13574221234&email=894733082@qq.com&timestamp=20151124141451&sign=07131700A29AD987F5D9F0463CE7EFC7

请求参数(Request Body)示例

<xml>

  <FromUserName>openid</FromUserName>

  <Number>phone number</Number>

  <Email>894733082@qq.com</Email>

  <Content>this is a test</Content>

  <CreateTime>1548348776</CreateTime>

  <MsgType>text</MsgType>

  <MsgId>1548348777</MsgId>

</xml>

参数说明

参数名称 说明
FromUserName 发送方帐号(一个OpenID)
Number 客户手机号或电话
Email 客户邮箱
Content 消息内容
CreateTime 消息创建时间 (整型)
MsgType text
MsgId 消息id,64位整型

2、接收图片消息

接收消息接口

POST http://xxxx.udesk.cn/spa1/im_callback?number=13574221234&email=894733082@qq.com&timestamp=20151124141451&sign=07131700A29AD987F5D9F0463CE7EFC7

请求参数(Request Body)示例

<xml>

 <FromUserName><![CDATA[fromUser]]></FromUserName>

 <Number>phone number</Number>

 <Email>894733082@qq.com</Email>

 <CreateTime>1348831860</CreateTime>

 <MsgType><![CDATA[image]]></MsgType>

 <PicUrl><![CDATA[this is a url]]></PicUrl>

 <MediaId><![CDATA[media_id]]></MediaId>

 <MsgId>1234567890123456</MsgId>

 </xml>

参数说明

参数名称 说明
FromUserName 发送方帐号(一个OpenID)
Number 客户手机号或电话
Email 客户邮箱
CreateTime 消息创建时间 (整型)
MsgType image
PicUrl 图片链接
MediaId 图片消息媒体id,可以调用多媒体文件下载接口拉取数据。
MsgId 消息id,64位整型

3、接收语音消息

接收消息接口

POST http://xxxx.udesk.cn/spa1/im_callback?number=13574221234&email=894733082@qq.com&timestamp=20151124141451&sign=07131700A29AD987F5D9F0463CE7EFC7

请求参数(Request Body)示例

<xml>

 <FromUserName><![CDATA[fromUser]]></FromUserName>

 <Number>phone number</Number>

 <Email>894733082@qq.com</Email>

 <CreateTime>1357290913</CreateTime>

 <MsgType><![CDATA[voice]]></MsgType>

 <MediaId><![CDATA[media_id]]></MediaId>

 <Format><![CDATA[Format]]></Format>

 <MsgId>1234567890123456</MsgId>

</xml>

参数说明

参数名称 说明
FromUserName 发送方帐号(一个OpenID)
Number 客户手机号或电话
Email 客户邮箱
CreateTime 消息创建时间 (整型)
MsgType 语音为voice
MediaId 图片消息媒体id,可以调用多媒体文件下载接口拉取数据。
Format 语音格式,amr
MsgId 消息id,64位整型

4、接收消息时的Response 结果

参数说明

参数名称 说明
status 客服状态,queuing/chatting/offline/unknown( 排队 / 聊天 / 离线 / 未知错误 )
turn 排队在第几位
agent_name 客服名称
msg string 格式消息

示例

{
    "status": "chatting",
    "turn": 0,
    "agent_name": "测试客服1",
    "msg": "测试客服1为您服务!"
}

四、消息推送

客服给客户回复消息时,把回复的消息推送到配置的地址

推送地址配置方法

1、推送文本格式消息

数据格式示例

{status: 'chatting',

         turn: 0,

         agent_name: 'Tom',

         msg: {

               touser: customer_weixin_openid,

               msgtype: ‘text’,

               text: {content: "您好,客服 Tom 在线为您服务" }

          },

        kw_on:  enabled,

        kw_on2:  enabled,

        kw_msg: '' }

参数说明

参数名称 说明
status 客服状态,queuing/chatting/offline/unknown( 排队 / 聊天 / 离线 / 未知错误 )
turn 排队在第几位
agent_name 客服名称
msg JSON 格式消息
kw_on 忙碌状态,关键字是否启用 true/false
kw_on2 离线状态,关键字是否启用 true/false
kw_msg 关键字匹配回复

JSON 格式msg消息说明

参数名称 说明
touser 客户微信id
msgtype 消息类型( text/ image )
text 客服名称
msg 文本类型回复: {content: "您好,客服 Tom 在线为您服务" }

2、推送图片格式消息

格式示例

{status: 'chatting',

         turn: 0,

         agent_name: 'Tom',

         msg: {

               touser: customer_weixin_openid,

               msgtype: 'image',

               image: {media_id: 123432443 }

          },

        kw_on:  enabled,

        kw_on2:  enabled,

        kw_msg: '' }

参数说明

参数名称 说明
status 客服状态,queuing/chatting/offline/unknown( 排队 / 聊天 / 离线 / 未知错误 )
turn 排队在第几位
agent_name 客服名称
msg JSON 格式消息
kw_on 忙碌状态,关键字是否启用 true/false
kw_on2 离线状态,关键字是否启用 true/false
kw_msg 关键字匹配回复

JSON 格式msg消息说明

参数名称 说明
touser 客户微信id
msgtype 消息类型image
image 图片类型回复: {media_id: 123432443 }

3、推送语音格式消息

格式示例

{status: 'chatting',

         turn: 0,

         agent_name: 'Tom',

         msg: {

               touser: customer_weixin_openid,

               msgtype: 'voice',

               voice: {media_id: 123432443 }

          },

        kw_on:  enabled,

        kw_on2:  enabled,

        kw_msg: '' }

参数说明

参数名称 说明
status 客服状态,queuing/chatting/offline/unknown( 排队 / 聊天 / 离线 / 未知错误 )
turn 排队在第几位
agent_name 客服名称
msg JSON 格式消息
kw_on 忙碌状态,关键字是否启用 true/false
kw_on2 离线状态,关键字是否启用 true/false
kw_msg 关键字匹配回复

JSON 格式msg消息说明

参数名称 说明
touser 客户微信id
msgtype 消息类型voice
voice 语音类型回复: {media_id: 123432443 }

五、获取Token

用于获取消息推送地址的token值 - 注:需要在推送地址配置对应的鉴权方法,否则鉴权无效

请求url:

GET http://xxxxxx.com/getAccessToken?from=udesk&timestamp=12124234&sign=133d74d79aef117690f431f81d8df406

参数说明

返回json结果:

返回格式:

{
error_code: 0,
error_msg: "SUCCESS",
data:{
token: "rg9noa9Z9AqovM1bTJX_-5VUH9PCBlkQ5u91nEHJVJcu2fN"
}
}

参数说明:

参数名称 说明
error_code 值为0表示成功,其他值为失败,其中2表示验证通过,但是获取token失败
error_msg 返回的错误提示
data 包含token,即微信的access_token 值

注意事项