统一服务消息【公众号和小程序模板消息下发统一openId解惑】

迈不过友情╰ 2022-10-16 07:46 806阅读 0赞

# 总结： #

> # 统一主体下的公众号和小程序，并且公众号已经经关联小程序，此时小程序的OpenId可以使用公众号的消息模板进行下发。 #

# uniformMessage.send #

> 本接口应在服务器端调用，详细说明参见[服务端API][API]。

> 本接口支持[云调用][Link 1]。需开发者工具版本 >= `1.02.1904090`（最新[稳定版下载][Link 2]），`wx-server-sdk` >= `0.4.0`

下发小程序和公众号统一的服务消息

调用方式：

*  [HTTPS 调用][HTTPS]
 *  [云调用][Link 3]

## HTTPS 调用 ##

### 请求地址 ###

POST https://api.weixin.qq.com/cgi-bin/message/wxopen/template/uniform_send?access_token=ACCESS_TOKEN

### 请求参数 ###

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>access_token</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td><a href="https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/access-token/auth.getAccessToken.html" rel="nofollow">接口调用凭证</a></td> 
  </tr> 
  <tr> 
   <td>touser</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>用户openid，可以是小程序的openid，也可以是mp_template_msg.appid对应的公众号的openid</td> 
  </tr> 
  <tr> 
   <td>weapp_template_msg</td> 
   <td>Object</td> 
   <td>&nbsp;</td> 
   <td>否</td> 
   <td>小程序模板消息相关的信息，可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息</td> 
  </tr> 
  <tr> 
   <td>mp_template_msg</td> 
   <td>Object</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息相关的信息，可以参考公众号模板消息接口；有此节点并且没有weapp_template_msg节点时，发送公众号模板消息</td> 
  </tr> 
 </tbody> 
</table>

**weapp\_template\_msg 的结构**

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>template_id</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板ID</td> 
  </tr> 
  <tr> 
   <td>page</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序页面路径</td> 
  </tr> 
  <tr> 
   <td>form_id</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板消息formid</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板数据</td> 
  </tr> 
  <tr> 
   <td>emphasis_keyword</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板放大关键词</td> 
  </tr> 
 </tbody> 
</table>

**mp\_template\_msg 的结构**

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>appid</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号appid，要求与小程序有绑定且同主体</td> 
  </tr> 
  <tr> 
   <td>template_id</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板id</td> 
  </tr> 
  <tr> 
   <td>url</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息所要跳转的url</td> 
  </tr> 
  <tr> 
   <td>miniprogram</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息所要跳转的小程序，小程序的必须与公众号具有绑定关系</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息的数据</td> 
  </tr> 
 </tbody> 
</table>

### 返回值 ###

### Object ###

返回的 JSON 数据包

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>errcode</td> 
   <td>number</td> 
   <td>错误码</td> 
  </tr> 
  <tr> 
   <td>errmsg</td> 
   <td>string</td> 
   <td>错误信息</td> 
  </tr> 
 </tbody> 
</table>

### 错误 ###

<table> 
 <thead> 
  <tr> 
   <th>错误码</th> 
   <th>错误信息</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>40037</td> 
   <td>&nbsp;</td> 
   <td>模板id不正确，weapp_template_msg.template_id或者mp_template_msg.template_id</td> 
  </tr> 
  <tr> 
   <td>41028</td> 
   <td>&nbsp;</td> 
   <td>weapp_template_msg.form_id过期或者不正确</td> 
  </tr> 
  <tr> 
   <td>41029</td> 
   <td>&nbsp;</td> 
   <td>weapp_template_msg.form_id已被使用</td> 
  </tr> 
  <tr> 
   <td>41030</td> 
   <td>&nbsp;</td> 
   <td>weapp_template_msg.page不正确</td> 
  </tr> 
  <tr> 
   <td>45009</td> 
   <td>&nbsp;</td> 
   <td>接口调用超过限额</td> 
  </tr> 
  <tr> 
   <td>40003</td> 
   <td>&nbsp;</td> 
   <td>touser不是正确的openid</td> 
  </tr> 
  <tr> 
   <td>40013</td> 
   <td>&nbsp;</td> 
   <td>appid不正确，或者不符合绑定关系要求</td> 
  </tr> 
 </tbody> 
</table>

### 请求数据示例 ###

{
        "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"
                }
            }
        }
    }

### 返回数据示例 ###

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

## 云调用 ##

> [云调用][Link 1]是小程序·云开发提供的在云函数中调用微信开放接口的能力，需要在云函数中通过 `wx-server-sdk` 使用。

### 接口方法 ###

openapi.uniformMessage.send

> 需在 `config.json` 中配置 `uniformMessage.send` API 的权限，[详情][Link 4]

### 请求参数 ###

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>touser</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>用户openid，可以是小程序的openid，也可以是mp_template_msg.appid对应的公众号的openid</td> 
  </tr> 
  <tr> 
   <td>weappTemplateMsg</td> 
   <td>Object</td> 
   <td>&nbsp;</td> 
   <td>否</td> 
   <td>小程序模板消息相关的信息，可以参考小程序模板消息接口; 有此节点则优先发送小程序模板消息</td> 
  </tr> 
  <tr> 
   <td>mpTemplateMsg</td> 
   <td>Object</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息相关的信息，可以参考公众号模板消息接口；有此节点并且没有weapp_template_msg节点时，发送公众号模板消息</td> 
  </tr> 
 </tbody> 
</table>

**weappTemplateMsg 的结构**

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>templateId</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板ID</td> 
  </tr> 
  <tr> 
   <td>page</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序页面路径</td> 
  </tr> 
  <tr> 
   <td>formId</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板消息formid</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板数据</td> 
  </tr> 
  <tr> 
   <td>emphasisKeyword</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>小程序模板放大关键词</td> 
  </tr> 
 </tbody> 
</table>

**mpTemplateMsg 的结构**

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>默认值</th> 
   <th>必填</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>appid</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号appid，要求与小程序有绑定且同主体</td> 
  </tr> 
  <tr> 
   <td>templateId</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板id</td> 
  </tr> 
  <tr> 
   <td>url</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息所要跳转的url</td> 
  </tr> 
  <tr> 
   <td>miniprogram</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息所要跳转的小程序，小程序的必须与公众号具有绑定关系</td> 
  </tr> 
  <tr> 
   <td>data</td> 
   <td>string</td> 
   <td>&nbsp;</td> 
   <td>是</td> 
   <td>公众号模板消息的数据</td> 
  </tr> 
 </tbody> 
</table>

### 返回值 ###

### Object ###

返回的 JSON 数据包

<table> 
 <thead> 
  <tr> 
   <th>属性</th> 
   <th>类型</th> 
   <th>说明</th> 
  </tr> 
 </thead> 
 <tbody> 
  <tr> 
   <td>errCode</td> 
   <td>number</td> 
   <td>错误码</td> 
  </tr> 
  <tr> 
   <td>errMsg</td> 
   <td>string</td> 
   <td>错误信息</td> 
  </tr> 
 </tbody> 
</table>

### 异常 ###

### Object ###

抛出的异常

**errCode 的合法值**

### 错误 ###

### 请求数据示例 ###

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
      }
    }

### 返回数据示例 ###

{
      "errCode": 0,
      "errMsg": "openapi.uniformMessage.send:ok"
    }

[API]: https://developers.weixin.qq.com/miniprogram/dev/framework/server-ability/backend-api.html
[Link 1]: https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html
[Link 2]: https://developers.weixin.qq.com/miniprogram/dev/devtools/stable.html
[HTTPS]: https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/uniform-message/uniformMessage.send.html#method-http
[Link 3]: https://developers.weixin.qq.com/miniprogram/dev/api-backend/open-api/uniform-message/uniformMessage.send.html#method-cloud
[Link 4]: https://developers.weixin.qq.com/miniprogram/dev/wxcloud/guide/openapi/openapi.html#usage-3