1、消息订阅
1、消息类型
(1) 一次性订阅消息
用户自主订阅后,开发者可不限时间地下发一条对应的服务消息；每条消息可单独订阅或退订。
(2) 长期订阅消息
用户订阅一次后,开发者可长期下发多条消息。
目前长期性订阅消息仅向政务民生、医疗、交通、金融、教育等线下公共服务开放,后期将逐步支持到其他线下公共服务业务。
(3) 订阅消息语音提醒
当开发者调用wx.requestSubscribeMessage时仅订阅1条消息且该模板支持开启语音提醒,当用户开启了语音提醒,该模板的订阅状态为'acceptWithAudio'。
如:收款到账通知
2、配置模板并获取模板id
小程序后台->订阅消息中设置
3、发起订阅
一次性模板id和永久模板id不可同时使用
一次授权调用里,每个tmplId对应的模板标题不能存在相同的,若出现相同的,只保留一个
(1)wx.requestSubscribeMessage
wx.requestSubscribeMessage({
tmplIds ['id',...],一次调用最多可订阅3条消息,每个tmplId对应的模板标题需要不相同,否则会被过滤。
success
errMsg 接口调用成功时errMsg值为'requestSubscribeMessage:ok'
模板id 'accept'、'reject'、'ban'、'filter'
'accept'表示用户同意订阅该条id对应的模板消息
'reject'表示用户拒绝订阅该条id对应的模板消息
'ban'表示已被后台封禁
'filter'表示该模板因为模板标题同名被后台过滤。
例如 { errMsg: "requestSubscribeMessage:ok", zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: "accept"}
fail
complete
})
(2)获取用户对相关模板消息的订阅状态
当用户勾选了订阅面板中的“总是保持以上选择,不再询问”时,模板消息会被添加到用户的小程序设置页,通过wx.getSetting接口可获取用户对相关模板消息的订阅状态
wx.getSetting({
withSubscriptions 是否同时获取用户订阅消息的订阅状态,默认不获取,注意:withSubscriptions只返回用户勾选过订阅面板中的“总是保持以上选择,不再询问”的订阅消息。
success
authSetting 用户授权结果
subscriptionsSetting 用户订阅消息设置,接口参数withSubscriptions值为true时才会返回。
{
mainSwitch: true, 订阅消息总开关
itemSettings: { 每一项开关
SYS_MSG_TYPE_INTERACTIVE: 'accept', 小游戏系统订阅消息
SYS_MSG_TYPE_RANK: 'accept'
zun-LzcQyW-edafCVvzPkK4de2Rllr1fFpw2A_x0oXE: 'reject', 普通一次性订阅消息
ke_OZC_66gZxALLcsuI7ilCJSP2OJ2vWo2ooUPpkWrw: 'ban',
}
}
miniprogramAuthSetting 在插件中调用时,当前宿主小程序的用户授权结果
fail
complete
})
(3)服务端发送消息
方式一:
POST https://api.weixin.qq.com/cgi-bin/message/subscribe/send?access_token=ACCESS_TOKEN
请求体:
access_token|cloudbase_access_token 接口调用凭证
touser 接收者(用户)的openid
template_id 所需下发的订阅模板id
page 点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
data 模板内容,格式形如{"key1":{"value":any},"key2":{"value":any}}
参数类别 参数说明 参数值限制 说明
thing.DATA 事物 20个以内字符 可汉字、数字、字母或符号组合
number.DATA 数字 32位以内数字 只能数字，可带小数
letter.DATA 字母 32位以内字母 只能字母
symbol.DATA 符号 5位以内符号 只能符号
character_string.DATA 字符串 32位以内数字、字母或符号 可数字、字母或符号组合
time.DATA 时间 24小时制时间格式（支持+年月日），支持填时间段，两个时间点之间用“~”符号连接 例如：15:01，或：2019年10月1日 15:01
date.DATA 日期 年月日格式（支持+24小时制时间），支持填时间段，两个时间点之间用“~”符号连接 例如：2019年10月1日，或：2019年10月1日 15:01
amount.DATA 金额 1个币种符号+10位以内纯数字，可带小数，结尾可带“元” 可带小数
phone_number.DATA 电话 17位以内，数字、符号 电话号码，例：+86-0766-66888866
car_number.DATA 车牌 8位以内，第一位与最后一位可为汉字，其余为字母或数字 车牌号码：粤A8Z888挂
name.DATA 姓名 10个以内纯汉字或20个以内纯字母或符号 中文名10个汉字内；纯英文名20个字母内；中文和字母混合按中文名算，10个字内
phrase.DATA 汉字 5个以内汉字 5个以内纯汉字，例如：配送中
基本格式:
姓名: {{name01.DATA}}
金额: {{amount01.DATA}}
行程: {{thing01.DATA}}
日期: {{date01.DATA}}
示例:
"data": {
"number01": {
"value": '339208499'
},
"date01": {
"value": '2015年01月05日'
},
"site01": {
"value": 'TIT创意园'
},
"site02": {
"value": '广州市新港中路397号'
}
},
miniprogram_state 跳转小程序类型：developer为开发版；trial为体验版；formal为正式版；默认为正式版
lang "进入小程序查看"的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN
接口调用凭证ACCESS_TOKEN通过如下接口获取
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
方式二:云调用方式
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.subscribeMessage.send({
touser 接收者(用户)的openid
template_id 所需下发的订阅模板id
page 点击模板卡片后的跳转页面,仅限本小程序内的页面。支持带参数,(示例index?foo=bar)。该字段不填则模板无跳转。
data 模板内容,格式形如{"key1":{"value":any},"key2":{"value":any}}
miniprogram_state 跳转小程序类型：developer为开发版；trial为体验版；formal为正式版；默认为正式版
lang "进入小程序查看"的语言类型,支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文),默认为zh_CN
})
return result
} catch (err) {
return err
}
}
(4)服务端接收相关的订阅内容
1.当用户触发订阅消息弹框后,用户的相关行为事件结果会推送至开发者所配置的服务器地址。
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1620973045",
"MsgType": "event",
"Event": "subscribe_msg_popup_event",
"SubscribeMsgPopupEvent": [ {
"TemplateId": "hD-ixGOhYmUfjOnI8MCzQMPshzGVeux_2vzyvQu7O68",
"SubscribeStatusString": "accept",
"PopupScene": "0"
}],
}
ToUserName 小程序帐号ID
FromUserName用户openid
CreateTime 时间戳
TemplateId 模板id(一次订阅可能有多个id)
SubscribeStatusString 订阅结果(accept接收,reject拒收)
PopupScene 弹框场景,0代表在小程序页面内
2.当用户在手机端服务通知里消息卡片右上角“...”管理消息时,或者在小程序设置管理中的订阅消息管理页面内管理消息时,相应的行为事件会推送至开发者所配置的服务器地址。目前只推送取消订阅的事件，即对消息设置“拒收”
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5OI1Uej6Xixw1lA2H7XDVbc",
"CreateTime": "1610968440",
"MsgType": "event",
"Event": "subscribe_msg_change_event",
"SubscribeMsgChangeEvent": [ {
"TemplateId":"BEwX0BOT3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"SubscribeStatusString": "reject"
}],
}
ToUserName 小程序帐号ID
FromUserName用户openid
CreateTime 时间戳
TemplateId 模板id(一次订阅可能有多个id)
SubscribeStatusString 订阅结果(reject拒收)
3.调用订阅消息接口发送消息给用户的最终结果,会推送下发结果事件至开发者所配置的服务器地址。
{
"ToUserName": "gh_123456789abc",
"FromUserName": "o7esq5PHRGBQYmeNyfG064wEFVpQ",
"CreateTime": "1620963428",
"MsgType": "event",
"Event": "subscribe_msg_sent_event",
"SubscribeMsgSentEvent": {
"List": {
"TemplateId": "BEwX0BO-T3MqK3Uc5oTU3CGBqzjpndk2jzUf7VfExd8",
"MsgID": "1864323726461255680",
"ErrorCode": "0",
"ErrorStatus": "success"
}
}
}
ToUserName 小程序帐号ID
FromUserName用户openid
CreateTime 时间戳
TemplateId 模板id(一次订阅可能有多个id)
MsgID 消息id(调用接口时也会返回)
ErrorCode 推送结果状态码(0表示成功)
ErrorStatus 推送结果状态码对应的含义
2、统一服务消息
为便于开发者对用户进行服务消息触达,简化小程序和公众号模板消息下发流程,小程序提供统一的服务消息下发接口
服务端调用:
POST https://api.weixin.qq.com/cgi-bin/message/wxopen/template/uniform_send?access_token=ACCESS_TOKEN
请求体参数
access_token|cloudbase_access_token 接口调用凭证
touser 用户openid,可以是小程序的openid,也可以是mp_template_msg.appid对应的公众号的openid
weapp_template_msg 小程序模板消息相关的信息,可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息(小程序模板消息已下线,不用传此节点)
template_id 小程序模板ID
page 小程序页面路径
form_id 小程序模板消息formid
data 小程序模板数据
emphasis_keyword小程序模板放大关键词
mp_template_msg 公众号模板消息相关的信息,可以参考公众号模板消息接口；有此节点并且没有weapp_template_msg节点时,发送公众号模板消息
appid 公众号appid,要求与小程序有绑定且同主体
template_id 公众号模板id
url 公众号模板消息所要跳转的url
miniprogram 公众号模板消息所要跳转的小程序,小程序的必须与公众号具有绑定关系
data 公众号模板消息的数据
接口调用凭证ACCESS_TOKEN通过如下接口获取
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
示例:
{
"touser":"OPENID",
"weapp_template_msg":{ 模板消息可能已经不再需要,未验证
"template_id":"TEMPLATE_ID",
"page":"page/page/index",
"form_id":"FORMID",
"data":{
"keyword1":{
"value":"339208499"
},
"keyword2":{
"value":"2015年01月05日 12:30"
},
"keyword3":{
"value":"腾讯微信总部"
},
"keyword4":{
"value":"广州市海珠区新港中路397号"
}
},
"emphasis_keyword":"keyword1.DATA"
},
"mp_template_msg":{
"appid":"APPID ",
"template_id":"TEMPLATE_ID",
"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"
}
}
}
}
云函数方式
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.uniformMessage.send({
"touser": 'OPENID',
"weappTemplateMsg": {
"page": 'page/page/index',
"data": {
"keyword1": {
"value": '339208499'
},
"keyword2": {
"value": '2015年01月05日 12:30'
},
"keyword3": {
"value": '腾讯微信总部'
},
"keyword4": {
"value": '广州市海珠区新港中路397号'
}
},
"templateId": 'TEMPLATE_ID',
"formId": 'FORMID',
"emphasisKeyword": 'keyword1.DATA'
},
"mpTemplateMsg": {
"appid": 'APPID ',
"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'
}
},
"templateId": 'TEMPLATE_ID'
}
})
return result
} catch (err) {
return err
}
}
3、客服消息
(1)使用客服消息
<button open-type="contact" bindcontact="handleContact"></button>
open-type="contact"
session-from 会话来源，open-type="contact"时有效
send-message-title 当前标题 会话内消息卡片标题，open-type="contact"时有效
send-message-path 当前分享路径 会话内消息卡片点击跳转小程序路径，open-type="contact"时有效
send-message-img 截图 会话内消息卡片图片，open-type="contact"时有效
show-message-card 是显示会话内消息卡片，设置此参数为 true，用户进入客服会话会在右下角显示"可能要发送的小程序"提示，用户点击后可以快速发送小程序消息，open-type="contact"时有效
bindcontact 客服消息回调，open-type="contact"时有效
path 小程序消息指定的路径
query 小程序消息指定的查询参数
(2)后台接入消息服务
用户向小程序客服发送消息、或者进入会话等情况时,开发者填写的服务器配置URL(如果使用的是云开发,则是配置的云函数)将得到微信服务器推送过来的消息和事件,开发者可以依据自身业务逻辑进行响应。接入和使用方式请参考消息推送。
详见消息推送:https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/message-push.html
(3)接受到的消息格式
1.用户在客服会话中发送文本消息时将产生如下数据包：
{
"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位整型
2.用户在客服会话中发送图片消息时将产生如下数据包
{
"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,可以调用[获取临时素材]((getTempMedia)接口拉取数据。https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-message/customerServiceMessage.getTempMedia.html
MsgId 消息id,64位整型
3.小程序卡片消息：
{
"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
4.进入会话事件
{
"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 属性
(4)回复客服消息
用户给客服发了一次,客服回复的不能超过五次,第六次就报错
后端调用POST https://api.weixin.qq.com/cgi-bin/message/custom/send?access_token=ACCESS_TOKEN
请求体参数
access_token|cloudbase_access_token 接口调用凭证
touser 用户的OpenID
msgtype 消息类型
text 文本消息
image 图片消息
link 图文链接
miniprogrampage 小程序卡片
text 文本消息,msgtype="text"时必填
content:'文本内容'
文本内容可以是超链接跳回小程序,如:...<a href="http://www.qq.com" data-miniprogram-appid="appid" data-miniprogram-path="pages/index/index">点击跳小程序</a>
image 图片消息,msgtype="image"时必填
media_id 发送的图片的媒体ID,通过新增素材接口上传图片文件获得。https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-message/customerServiceMessage.uploadTempMedia.html
link 图文链接,msgtype="link"时必填
title 消息标题
description 图文链接消息
url 图文链接消息被点击后跳转的链接
thumb_url 图文链接消息的图片链接,支持JPG、PNG格式,较好的效果为大图640X320,小图80X80
miniprogrampage 小程序卡片,msgtype="miniprogrampage"时必填
title 消息标题
pagepath 小程序的页面路径,跟app.json对齐,支持参数,比如pages/index/index?foo=bar
thumb_media_id 小程序消息卡片的封面,image类型的media_id,通过新增素材接口上传图片文件获得,建议大小为520*416https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/customer-message/customerServiceMessage.uploadTempMedia.html
接口调用凭证ACCESS_TOKEN通过如下接口获取
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
云函数调用方式
参数和上面的方式一致,除了不用传递access_token
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.customerServiceMessage.send({
"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>
}
})
return result
} catch (err) {
return err
}
}
(5)转发客服消息
如果小程序设置了消息推送，普通微信用户向小程序客服发消息时，微信服务器会先将消息 POST 到开发者填写的 URL 上
如果希望将消息转发到网页版客服工具，则需要开发者在响应包中返回 MsgType 为 transfer_customer_service 的消息，微信服务器收到响应后会把当次发送的消息转发至客服系统。
用户被客服接入以后，客服关闭会话以前，处于会话过程中时，用户发送的消息均会被直接转发至客服系统。
当会话超过 30 分钟客服没有关闭时，微信服务器会自动停止转发至客服，而将消息恢复发送至开发者填写的 URL 上。
用户在等待队列中时，用户发送的消息仍然会被推送至开发者填写的 URL 上。
这里特别要注意，只针对微信用户发来的消息才进行转发，而对于其他事件（比如用户从小程序唤起客服会话）都不应该转发，否则客服在客服系统上就会看到一些无意义的消息了。
消息转发到网页版客服工具
开发者只要在响应包中返回 MsgType 为 transfer_customer_service 的消息，微信服务器收到响应后就会把当次发送的消息转发至客服系统。需返回如下格式的 XML 数据
<xml>
<ToUserName><![CDATA[touser]]></ToUserName>
<FromUserName><![CDATA[fromuser]]></FromUserName>
<CreateTime>1399197672</CreateTime>
<MsgType><![CDATA[transfer_customer_service]]></MsgType>
</xml>
ToUserName 接收方帐号(收到的OpenID)
FromUserName 开发者微信号
CreateTime 消息创建时间 (整型)
MsgType transfer_customer_service
如果是使用云函数接收的消息推送,则需在云函数被客服消息触发后返回同样格式的JSON数据：
// ...
exports.main = async (event, context) => {
// 判断处理客服消息 ...
// 最后返回 JSON
return {
MsgType: 'transfer_customer_service',
ToUserName: 'touser',
FromUserName: 'fromuser',
CreateTime: parseInt(+new Date / 1000),
}
}
(6)显示客服输入态
此接口需要客服消息接口权限。
如果不满足发送客服消息的触发条件，则无法下发输入状态。
下发输入状态，需要客服之前 30 秒内跟用户有过消息交互。
在输入状态中（持续 15 秒），不可重复下发输入态。
在输入状态中，如果向用户下发消息，会同时取消输入状态。
POST https://api.weixin.qq.com/cgi-bin/message/custom/typing?access_token=ACCESS_TOKEN
请求体参数
access_token|cloudbase_access_token 接口调用凭证
touser 用户的OpenID
command 命令
Typing 对用户下发"正在输入"状态
CancelTyping取消对用户的"正在输入"状态
接口调用凭证ACCESS_TOKEN通过如下接口获取
GET https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET
云函数调用方式
const cloud = require('wx-server-sdk')
cloud.init({
env: cloud.DYNAMIC_CURRENT_ENV,
})
exports.main = async (event, context) => {
try {
const result = await cloud.openapi.customerServiceMessage.setTyping({
"touser": 'OPENID',
"command": 'Typing'
})
return result
} catch (err) {
return err
}
}
4、消息推送
https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/message-push.html
扫一扫
01-24
874
874
04-18
9485
9485
01-07
被折叠的 条评论
为什么被折叠?
到【灌水乐园】发言
