微信小程序学习之路——API客服消息

其他 2019-04-10 03:09:14 阅读次数: 0

客服消息

在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

当用户在客服会话发送消息、或由某些特定的用户操作引发事件推送时，微信服务器会将消息或事件的数据包发送到开发者填写的 URL（详情请参考消息推送）。开发者收到请求后可以使用 发送客服消息 接口进行异步回复。

1.接入指引

1）填写开发者服务器配置

登陆微信公众平台，选择“客服”，查看“消息推送配置”，填写相应的服务器配置。其中URL是开发者服务端接收消息的接口URL地址，必须是http://或https://开头，分别支持80和443端口。Token为用户身份令牌用作生成签名，可由开发者任意填写，该Token会和接口URL中包含的Token进行对比，从而验证安全性。EncodingAESKey由开发者手动填写或随机生成，用作消息体加密解密密钥。在配置界面中可以选择消息加密方式和数据格式，加密方式默认为明文，数据个hi默认为XML。

开放数据校验与解密的相关官方文档：https://developers.weixin.qq.com/miniprogram/dev/framework/open-ability/signature.html

2）开发者服务器接收请求并返回指定信息，验证服务器地址有效性

仅仅填写配置信息是不能完全接入的，提交配置信息后，微信服务器将发送GET请求到填写的服务器地址，开发者服务器收到请求并按奥球返回才能完成介入，所以我们在配置前先完成后台服务器接口工作，GET请求参数如下：

  • signatrue:微信加密千米，signature节后了开发者填写的token参数和请求中的timestamp参数、nonce参数
  • timestamp:时间戳
  • nonce:随机数
  • echostr:随机字符串

后台可通过检验signature验收请求。收到GET请求后，开发者服务器需要原样返回echostr参数内容，才能接入生效。加密/校验流程如下:

1.将token、timestamp、nonce三个参数进行字典序排序

2.将三个参数字符串拼接成一个字符串进行sha1加密

3.开发者获得加密后的字符串可与signature对比，标识该请求来源于微信。

检验signature的PHP代码示例如下:

private function checkSignature()
{

    $signature = $_GET["signature"];
    $timestamp = $_GET["timestamp"];
    $token = TOKEN;
    $tmpArr = array($token,$timestamp,$nonce);
    sort($tmpArr,SORT_STRING);
    $tmpStr = implode($tmpArr);
    $tmpStr = sha1($tmpStr);
    if($tmpStr == #signature){
        return true;
    }else{
        return false;
    }
}

完成URL有效性验证后便接入生效。通过配置URL接口，开发者服务器可接收微信服务器推送过来的消息和事件，并根据业务进行相应。

2.接收消息和事件

在页面中使用 <button open-type="contact" /> 可以显示进入客服会话按钮。

当用户在客服会话发送消息（或进行某些特定的用户操作引发的事件推送时），微信服务器会将消息（或事件）的数据包（JSON或者XML格式）POST请求开发者填写的URL。开发者收到请求后可以使用发送客服消息接口进行异步回复。

微信服务器在将用户的消息发给小程序的开发者服务器地址（开发设置处配置）后，微信服务器在五秒内收不到响应会断掉连接，并且重新发起请求，总共重试三次，如果在调试中，发现用户无法收到响应的消息，可以检查是否消息处理超时。关于重试的消息排重，有msgid的消息推荐使用msgid排重。事件类型消息推荐使用FromUserName + CreateTime 排重。

服务器收到请求必须做出下述回复，这样微信服务器才不会对此作任何处理，并且不会发起重试，否则，将出现严重的错误提示。详见下面说明：

1、直接回复success（推荐方式）
2、直接回复空串（指字节长度为0的空字符串，而不是结构体中content字段的内容为空）

一旦遇到以下情况，微信都会在小程序会话中，向用户下发系统提示“该小程序客服暂时无法提供服务，请稍后再试”：

1、开发者在5秒内未回复任何内容
2、开发者回复了异常数据

如果开发者希望增强安全性，可以在开发者中心处开启消息加密，这样，用户发给小程序的消息以及小程序被动回复用户消息都会继续加密，详见消息加解密说明。

各消息类型的推送JSON、XML数据包结构如下：

1）进入会话事件

用户在客服会话中发送文本消息时将产生如下数据包：

XML 格式

<xml>
    <ToUserName><![CDATA[toUser]]></ToUserName>  
    <FromUserName><![CDATA[fromUser]]></FromUserName>  
    <CreateTime>1482048670</CreateTime>  
    <MsgType><![CDATA[event]]></MsgType>  
    <Event><![CDATA[user_enter_tempsession]]></Event>  
    <SessionFrom><![CDATA[sessionFrom]]></SessionFrom> 
</xml>

JSON格式

{
	"ToUserName": "toUser",
	"FromUserName": "fromUser",
	"CreateTime": 1482048670,
	"MsgType": "event",
	"Event": "user_enter_tempsession",
	"SessionFrom": "sessionFrom"
}

参数说明如下：

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 事件创建时间(整型）
MsgType event
Event 事件类型，user_enter_tempsession
SessionFrom 开发者在客服会话按钮设置的session-from属性

2）文本消息

用户在客服会话中发送文本消息时将产生如下数据包：

XML格式：

<xml>
   <ToUserName><![CDATA[toUser]]></ToUserName>
   <FromUserName><![CDATA[fromUser]]></FromUserName>
   <CreateTime>1482048670</CreateTime>
   <MsgType><![CDATA[text]]></MsgType>
   <Content><![CDATA[this is a test]]></Content>
   <MsgId>1234567890123456</MsgId>
</xml>

JSON格式：

{
	"ToUserName": "toUser",
	"FromUserName": "fromUser",
	"CreateTime": 1482048670,
	"MsgType": "text",
	"Content": "this is a test",
	"MsgId": 1234567890123456
}

参数如下：

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型）
MsgType text
Content 文本消息内容
MsgId 消息id，64位整型

3）图片消息

用户在客服会话中发送图片消息时将产生如下数据包：

XML格式

<xml>
      <ToUserName><![CDATA[toUser]]></ToUserName>
      <FromUserName><![CDATA[fromUser]]></FromUserName>
      <CreateTime>1482048670</CreateTime>
      <MsgType><![CDATA[image]]></MsgType>
      <PicUrl><![CDATA[this is a url]]></PicUrl>
      <MediaId><![CDATA[media_id]]></MediaId>
      <MsgId>1234567890123456</MsgId>
</xml>

JSON 格式

{
	"ToUserName": "toUser",
	"FromUserName": "fromUser",
	"CreateTime": 1482048670,
	"MsgType": "image",
	"PicUrl": "this is a url",
	"MediaId": "media_id",
	"MsgId": 1234567890123456
}

参数说明如下：

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型）
MsgType image
PicUrl 图片链接（由系统生成）
MediaId 图片消息媒体id，可以调用获取临时素材接口拉取数据。
MsgId 消息id，64位整型

4）小程序卡片消息

用户在客服会话中发送小程序卡片消息时将产生如下数据包：

XML格式

<xml>
	<ToUserName><![CDATA[toUser]]></ToUserName>
	<FromUserName><![CDATA[fromUser]]></FromUserName>
	<CreateTime>1482048670</CreateTime>
	<MsgType><![CDATA[miniprogrampage]]></MsgType>
	<MsgId>1234567890123456</MsgId>
	<Title><![CDATA[Title]]></Title>
	<AppId><![CDATA[AppId]]></AppId>
	<PagePath><![CDATA[PagePath]]></PagePath>
	<ThumbUrl><![CDATA[ThumbUrl]]></ThumbUrl>
	<ThumbMediaId><![CDATA[ThumbMediaId]]></ThumbMediaId>
</xml>

JSON格式

{
	"ToUserName": "toUser",
	"FromUserName": "fromUser",
	"CreateTime": 1482048670,
	"MsgType": "miniprogrampage",
	"MsgId": 1234567890123456,
	"Title":"title",
	"AppId":"appid",
	"PagePath":"path",
	"ThumbUrl":"",
	"ThumbMediaId":""
}

参数说明：

参数 说明
ToUserName 小程序的原始ID
FromUserName 发送者的openid
CreateTime 消息创建时间(整型）
MsgType miniprogrampage
MsgId 消息id，64位整型
Title 标题
AppId 小程序appid
PagePath 小程序页面路径
ThumbUrl 封面图片的临时cdn链接
ThumbMediaId 封面图片的临时素材id

3.发送消息

当用户和小程序客服产生特定动作的交互时（具体动作列表请见下方说明），微信将会把消息数据推送给开发者，开发者可以在一段时间内（目前修改为48小时）调用客服接口，通过POST一个JSON数据包来发送消息给普通用户。此接口主要用于客服等有人工消息处理环节的功能，方便开发者为用户提供更加优质的服务。

目前允许的动作列表如下，不同动作触发后，允许的客服接口下发消息条数和下发时限不同。下发条数达到上限后，会收到错误返回码，具体请见返回码说明页：

用户动作 允许下发条数限制 下发时限
用户发送信息 5条 48小时

接口调用请求说明

http请求方式: POST
https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN

发送文本消息

{
    "touser":"OPENID",
    "msgtype":"text",
    "text":
    {
         "content":"Hello World"
    }
}

发送文本消息时，支持添加可跳转小程序的文字链

文本内容....<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>

说明：

  1. data-miniprogram-appid 项，填写小程序appid，则表示该链接跳转小程序；
  2. data-miniprogram-path项，填写小程序路径，路径与app.json中保持一致，可带参数；
  3. 对于不支持data-miniprogram-appid 项的客户端版本，如果有herf项，则仍然保持跳href中的链接；
  4. 小程序发带小程序文字链的文本消息，data-miniprogram-appid必须是该小程序的appid。

发送图片消息

{
    "touser":"OPENID",
    "msgtype":"image",
    "image":
    {
      "media_id":"MEDIA_ID"
    }
}

发送图文链接

每次可以发送一个图文链接

{

    "touser": "OPENID",
    "msgtype": "link",
    "link": {
          "title": "Happy Day",
          "description": "Is Really A Happy Day",
          "url": "URL",
          "thumb_url": "THUMB_URL"
    }
}

发送小程序卡片

{
	"touser":"OPENID",
	"msgtype":"miniprogrampage",
	"miniprogrampage":{
		"title":"title",
		"pagepath":"pagepath",
		"thumb_media_id":"thumb_media_id"
	}
}

参数说明

参数 是否必须 说明
access_token 是 调用接口凭证
touser 是 普通用户(openid)
msgtype 是 消息类型，文本为text，图文链接为link
content 是 文本消息内容
media_id 是 发送的图片的媒体ID，通过新增素材接口上传图片文件获得。
title 是 消息标题
description 是 图文链接消息
url 是 图文链接消息被点击后跳转的链接
picurl 是 图文链接消息的图片链接，支持 JPG、PNG 格式，较好的效果为大图 640 X 320，小图 80 X 80
pagepath 是 小程序的页面路径，跟app.json对齐，支持参数，比如pages/index/index?foo=bar
thumb_media_id 是 小程序消息卡片的封面， image类型的media_id，通过新增素材接口上传图片文件获得，建议大小为520*416

返回码说明

参数 说明
-1 系统繁忙，此时请开发者稍候再试
0 请求成功
40001 获取 access_token 时 AppSecret 错误，或者 access_token 无效。请开发者认真比对 AppSecret 的正确性，或查看是否正在为恰当的小程序调用接口
40002 不合法的凭证类型
40003 不合法的 OpenID，请开发者确认OpenID否是其他小程序的 OpenID
45015 回复时间超过限制
45047 客服接口下行条数超过上限
48001 api功能未授权，请确认小程序已获得该接口

4.临时素材接口

小程序可以使用本接口获取客服消息内的临时素材（即下载临时的多媒体文件）。目前小程序仅支持下载图片文件。

1）新增临时素材

小程序可以使用本接口把媒体文件（目前仅支持图片）上传到微信服务器，用户发送客服消息或被动回复用户消息。

接口调用请求说明

HTTP 请求方式：POST/FORM，HTTPS 调用

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

调用示例（使用curl命令，用FORM表单方式上传一个多媒体文件）：

curl -F [email protected] "https://api.weixin.qq.com/cgi-bin/media/upload?access_token=ACCESS_TOKEN&type=TYPE"

参数说明

参数 是否必须 说明
access_token 是 调用接口凭证
type 是 image
media 是 form-data中媒体文件标识，有filename、filelength、content-type等信息

返回说明

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

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

错误情况下的返回JSON数据包示例如下（示例为无效媒体类型错误）：

{
  "errcode":40004,
  "errmsg":"invalid media type"
}

参数如下：

参数 描述
type image
media_id 媒体文件上传后，获取标识
created_at 媒体文件上传时间戳

2）获取临时素材

小程序可以使用本接口获取客服消息内的临时素材（即下载临时的多媒体文件）。目前小程序仅支持下载图片文件。

HTTP 请求方式: GET，HTTPS 调用

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

请求示例（示例为通过curl命令获取多媒体文件）

curl -I -G "https://api.weixin.qq.com/cgi-bin/media/get?access_token=ACCESS_TOKEN&media_id=MEDIA_ID"

参数说明

参数 是否必须 说明
access_token 是 调用接口凭证
media_id 是 媒体文件ID

返回说明

正确情况下的返回 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"

如果返回的是视频消息素材，则内容如下：

{
 "video_url":DOWN_URL
}

错误情况下的返回JSON数据包示例如下（示例为无效媒体ID错误）：

{
  "errcode":40007,
  "errmsg":"invalid media_id"
}

猜你喜欢

转载自blog.csdn.net/CSDN_XUWENHAO/article/details/89160163
今日推荐
《美国对全球网络空间安全与发展的威胁和破坏》报告发布
火速冲上 GitHub 热榜 —— 开源编程语言、框架哪有这么可爱？
北京人形机器人创新中心发布全球首个纯电驱拟人奔跑的全尺寸人形机器人“天工”
LFOSSA 源来如此公开课 | 掌握云原生未来：CNCF 认证全面攻略与备考秘籍
周排行
让自己的头脑极度开放
CentOS 6.5(x64) 和Redhat6.5操作系误删libc
高可用注册中心
【日记】12.28/【题解】AtCoder AGC041
XML（5）_XML 约束_DTD
Java集合Map（四）
树梅派安装桌面环境教程
pipenv 的 使用和安装
小程序白屏问题和内存研究
C语言简单选择排序
每日归档
更多
2024-05-02(0)
2024-05-01(4)
2024-04-30(1)
2024-04-29(40)
2024-04-28(0)
2024-04-27(56)
2024-04-26(39)
2024-04-25(22)
2024-04-24(36)
2024-04-23(26)

代码天地 © 2018 codetd.com

境外服务器   最新电视剧2022