文档中心 合规指南 开发者社区
极光文档 > 极光统一消息 > REST API > 模板消息发送
极光文档 > 极光统一消息 > REST API > 模板消息发送
模板消息发送 v1
最近更新：2021-12-15
展开全部

模板消息发送 v1

API 概述

功能说明

模板消息发送的 API 需要先在官网控制台创建一个通用模板，才可以进行发送。

模板消息发送的通道由创建模板时选择的通道决定。

使用模板消息发送的好处是一次变量传值对所有通道生效。

调用地址

广播发送：POST https://api.ums.jiguang.cn/v1/template/broadcast

其他方式发送：POST https://api.ums.jiguang.cn/v1/template/sent

调用验证

HTTP Header（头）里加一个字段（ Key/Value 对）：

Authorization: Basic base64_auth_string
          Authorization: Basic base64_auth_string
此代码块在浮窗中显示

其中 base64_auth_string 的生成算法为：base64(ChannelKey:MasterSecret)
即，对 ChannelKey 加上冒号，加上 MasterSecret 拼装起来的字符串，再做 base64 转换。

消息对象

一个消息对象，以 JSON 格式表达，表示一条消息相关的所有信息。

参数 类型 选项 说明
aud_xxx String Array 可选 1. 消息的发送目标，在调用广播发送的 API 时无需传递该字段。
2. xxx 部分的取值详见下文 aud_xxx 发送目标部分。
template_id int 必填 模板ID
template_para JSON Object 必填 模板参数 key-value,例如：{“user”:“xxx”,“url”:“xxx”}
app_para JSON Object 可选 App 通道的相关参数，模板中有 App 通道时必填
rule_id int 可选 发送策略 ID，如果是同时发送可传 0 或不传。当使用自定义通道 ID 发送时，该字段无效。
option JSON Object 可选 可选参数，用于黑白名单 ID、提交人等信息的填写
callback JSON Object 可选 回调参数

示例说明

请求示例

curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/sent -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d ' { "aud_userid": ["user1","user2"], "template_id":10001, "template_para":{"user":"xxx","url":"xxx"}, "app_para":{ "platform":"ios", "time_to_live":9999, "apns_production":true }, "rule_id": 1001, "option": { "sendno": "test", "owner":"admin", "black_id":1234, "priority":2 }, "callback": { "url":"https://www.jiguang.cn/ums-portal", "params":{ "name":"joe", "age":26 } } }' > POST /v3/push HTTP/1.1 > Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
          curl --insecure -X POST -v https://api.ums.jiguang.cn/v1/sent -H "Content-Type: application/json" -u "7d431e42dfa6a6d693ac2d04:5e987ac6d2e04d95a9d8f0d1" -d '
{
    "aud_userid": ["user1","user2"],
    "template_id":10001,
    "template_para":{"user":"xxx","url":"xxx"},
    "app_para":{
        "platform":"ios",
        "time_to_live":9999,
        "apns_production":true
    },
    "rule_id": 1001,
    "option": {
        "sendno": "test",
        "owner":"admin",
        "black_id":1234,
        "priority":2
    },
    "callback": {
        "url":"https://www.jiguang.cn/ums-portal",
        "params":{
            "name":"joe",
            "age":26
         }
    }
}'

> POST /v3/push HTTP/1.1
> Authorization: Basic N2Q0MzFlNDJkZmE2YTZkNjkzYWMyZDA0OjVlOTg3YWM2ZDJlMDRkOTVhOWQ4ZjBkMQ==
此代码块在浮窗中显示

返回参数与示例

参数 类型 选项 说明
code int 必填 业务状态码，0 代表成功，其他代表失败，详见调用返回码
msgid String 可选 消息唯一 ID，当失败时不返回。
message String 可选 失败原因，失败时返回
sendno String 可选 API 调用时传递的标识，在请求成功时将被原样返回
< HTTP/1.1 200 OK < Content-Type: application/json {"code":0,"sendno":"aeg-efd-0e","msgno":"v:1t:1603707455p:27133n:2"}
          < HTTP/1.1 200 OK
< Content-Type: application/json
{"code":0,"sendno":"aeg-efd-0e","msgno":"v:1t:1603707455p:27133n:2"}
此代码块在浮窗中显示
{"code":1015031,"message":"模板ID不存在"}
          {"code":1015031,"message":"模板ID不存在"}
此代码块在浮窗中显示

aud_xxx：发送目标

UMS 当前支持「 广播所有人、标签、用户 ID、用户分群、自定义通道注册 ID 」5 种目标

广播

当广播所有人时，请调用广播专用的 API https://api.ums.jiguang.cn/v1/template/broadcast ，无需传 Audience。

用户类目标

「广播、标签、用户 ID、用户分群」均基于 UMS 中的用户体系，需要先使用用户管理 API 上传用户、各通道注册 ID、用户与各通道注册 ID 的绑定关系。

使用此种方式发送消息，UMS 在向各通道下发消息前，将根据特定的规则筛选出通道注册 ID，说明如下：

  • 标签发送时，先筛选出设置了该标签的 userID（对该标签优先选择绑定标识为本渠道 Channelkey 的 userID，若本渠道无此标签，才会选择绑定标识为全局 all 的 userID），再筛选对应的通道注册 ID 进行下发。
  • 对于 App、微信公众号、微信小程序、支付宝生活号通道，userID 是通过通道编码与通道注册 ID 绑定，因此在用户信息中选择「本渠道授权的通道」绑定的通道注册 ID 进行下发。
  • 对于短信和邮件通道，在用户信息中优先选择与本渠道 Channelkey 绑定的手机号码、邮箱，没有的情况下选择全局绑定的手机号码、邮箱。
  • 对于钉钉通道，ID 全局唯一，因此在用户信息中选择全局绑定的钉钉注册 ID 进行下发

对于「标签、用户 ID、用户分群」的传参说明如下：

参数 类型 选项 说明
aud_tag String Array 可选 标签列表，一次发送最多 20 个。有效性说明：
  • 中英文、数字、下划线、特殊字符@!#$&*+=.|￥。
  • 长度不超过 40 字节（UTF-8 编码）
aud_userid String Array 可选 用户列表，一次发送最多 1000 个。有效性说明：
  • 大小写字母、数字、下划线、特殊字符@!#$&*+=.|￥。
  • 长度不超过 64 字符
aud_segment String Array 可选 在页面创建的用户分群的 ID。定义为数组，但目前限制一次只能推送一个。

自定义通道注册 ID

如果不上传用户，UMS 也支持直接使用各通道的注册 ID 直接发送消息，根据通道的不同，xxx 部分的取值为：

* App：app * 微信公众号：wechatoa * 微信小程序：wechatmp * 短信：sms * 邮箱：email * 支付宝生活号：alipay_life * 钉钉：dingtalk_cc * 企业微信：wechatwk
          * App：app
* 微信公众号：wechatoa
* 微信小程序：wechatmp
* 短信：sms
* 邮箱：email
* 支付宝生活号：alipay_life
* 钉钉：dingtalk_cc
* 企业微信：wechatwk
此代码块在浮窗中显示

注意：在一条消息中，自定义通道注册 ID 和用户类目标（标签、用户 ID、用户分群）不允许同时存在

可以同时给多个通道发送，每个通道一次发送最多传 1000 个 ID

当使用自定义通道 ID 发送消息时，aud_xxx 的类型为 Object Array ，说明如下：

参数 类型 选项 说明
instance String 可选 目标标识，预留字段，目前无效
data String Array 必填 通道注册 ID 列表。一次发送最多 1000 个。有效性遵循各通道的要求即可。

示例

  • 使用标签发送
{ "aud_tag": ["tag1","tag2"] }
          {
    "aud_tag": ["tag1","tag2"]
}
此代码块在浮窗中显示
  • 使用用户 ID 发送
{ "aud_userid": ["user1","user2"] }
          {
    "aud_userid": ["user1","user2"]
}
此代码块在浮窗中显示
  • 使用用户分群发送
{ "aud_segment": ["1000"] }
          {
    "aud_segment": ["1000"]
}
此代码块在浮窗中显示
  • 使用自定义通道注册 ID 发送：
{ "aud_app": [{ "instance": "app", "data": ["170976fa8a9277fac6e"] }], "aud_wechatoa": [{ "instance": "wechatoa", "data": ["oMtZu6kApZYEPJJWwyIHpWQ2L_DI"] }], "aud_wechatmp": [{ "instance": "wechatmp", "data": ["oXNQs5B3LGA3xkU7-g2SdK3SsUaw"] }], "aud_sms": [{ "instance": "sms", "data": ["18866007799"] }], "aud_email": [{ "instance": "email", "data": ["wujb@jpush.cn"] }], "aud_alipay_life": [{ "instance": "alipaylife", "data": ["2088102733318286"] }], "aud_dingtalk_cc": [{ "instance": "dingtalkcc", "data": ["a3c213779d163837895b30f47aaa94c3"] }], "aud_wechatwk": [{ "instance": "wechatwk", "data": ["zhangsan"] }] }
          {
    "aud_app": [{
      "instance": "app",
      "data": ["170976fa8a9277fac6e"]
    }],
    "aud_wechatoa": [{
      "instance": "wechatoa",
      "data": ["oMtZu6kApZYEPJJWwyIHpWQ2L_DI"]
    }],
    "aud_wechatmp": [{
      "instance": "wechatmp",
      "data": ["oXNQs5B3LGA3xkU7-g2SdK3SsUaw"]
    }],
    "aud_sms": [{
      "instance": "sms",
      "data": ["18866007799"]
    }],
    "aud_email": [{
      "instance": "email",
      "data": ["wujb@jpush.cn"]
    }],
    "aud_alipay_life": [{
      "instance": "alipaylife",
      "data": ["2088102733318286"]
    }],
    "aud_dingtalk_cc": [{
      "instance": "dingtalkcc",
      "data": ["a3c213779d163837895b30f47aaa94c3"]
    }],
     "aud_wechatwk": [{
      "instance": "wechatwk",
      "data": ["zhangsan"]
    }]
}
此代码块在浮窗中显示

template_para：模板参数

在创建通用模板时，可以对多个通道设置同样的变量，在发送消息时，对同一个变量仅需传值一次，即可自动匹配到各个通道中。

模板参数中的 key 取决于创建模板时自定义的变量值，传值时需要注意不要超过各个通道的长度上限。

{ "template_para":{"user":"xxx","url":"xxx"} }
          {
     "template_para":{"user":"xxx","url":"xxx"}
}
此代码块在浮窗中显示

app_para：App 参数

创建模板时仅定义发送通道和对应的消息内容，对于 App 通道来说，发送消息时还需要指定平台等特殊的参数，因此提供专门的 app_para 字段进行填写，在模板中含有 App 通道时，该字段必填，支持的参数如下：

参数 类型 选项 说明
platform String/Arry String 必填 App 推送平台设置，取值："android","ios","quickapp","web"，需发送所有平台时设为“all”, 部分平台使用 json 数组
time_to_live int 可选 离线消息保留时长(秒)，默认 86400 （1 天），最长 10 天。
apns_production boolean 可选 APNs 是否生产环境，True 表示推送生产环境，False 表示要推送开发环境；如果不指定则为推送生产环境。
{ "app_para":{ "platform":"ios", "time_to_live":9999, "apns_production":true } }
          {
      "app_para":{
        "platform":"ios",
        "time_to_live":9999,
        "apns_production":true
    }
}
此代码块在浮窗中显示

rule_id：发送策略

如不需要进行补发，仅进行单通道、多通道同时发送，则不需填写策略 ID，或者设置为 0。

在官网控制台-渠道-发送策略中创建一个补发策略后，调 API 时可使用策略 ID 进行指定。

  • 在使用自定义通道注册 ID 发送时，发送策略不生效。
  • 如果使用了发送策略，策略中包含的通道和 msg_xxx 中的通道信息需要一致。

option：可选参数

当前包含如下几个可选参数：

参数 类型 选项 说明
sendno String 可选 纯粹用来作为 API 调用标识，API 返回时被原样返回，以方便 API 调用方匹配请求与返回。
owner String 可选 提交者用户名，当渠道开启了 api 消息审核时必填
black_id int 可选 黑名单id，黑名单ID和白名单ID不允许同时存在
white_id int 可选 白名单id，黑名单ID和白名单ID不允许同时存在
priority int 可选 消息优先级，取值：1（高）、2（中）、3（低）

callback：回调参数

调 API 发送消息时，可以指定 callback 参数，方便用户临时变更回调 URL 或者回调带上其自定义参数，满足其日常业务需求。详细使用说明请阅读消息回调设置

此功能仅针对极光 VIP 用户提供，提供「目标有效/无效、提交成功/失败、送达成功/失败、点击、撤回成功/失败」9 种消息状态，需在官网控制台设置所需回调的状态。

如需要开通此功能，请联系：商务客服

示例：

{ "aud_userid": ["user1","user2"], "msg_app": [{"platform":"android", "notification":{"android":{"alert":"Hi,JPush !"}}}], "rule_id": 1001, "option": { "sendno": "test", "owner":"admin", "black_id":1234, "priority":2 }, "callback": { "url":"https://www.jiguang.cn/ums-portal", "params":{ "name":"joe", "age":26 } } }
          {
    "aud_userid": ["user1","user2"],
    "msg_app": [{"platform":"android", "notification":{"android":{"alert":"Hi,JPush !"}}}],
    "rule_id": 1001,
    "option": {
        "sendno": "test",
        "owner":"admin",
        "black_id":1234,
        "priority":2
    },
    "callback": {
        "url":"https://www.jiguang.cn/ums-portal",
        "params":{
            "name":"joe",
            "age":26
         }
    }
}
此代码块在浮窗中显示

callback 包含如下字段：

关键字 类型 选项 含义
url string 可选 数据临时回调地址，仅针对这一次消息发送请求生效，该地址必须在极光后台有校验通过方可使用；不指定则以极光后台配置的默认地址为准
params JSON Object 可选 需要回调给用户的自定义参数

调用返回

调用 API 后的返回码请参考业务返回码

参考

文档内容是否对您有帮助？

Copyright 2011-2022, jiguang.cn, All Rights Reserved. 粤ICP备12056275号-13 深圳市和讯华谷信息技术有限公司

在文档中心打开