普通消息发送 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

其中 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==

返回参数与示例

参数 类型 选项 说明
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"}
{"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

注意:在一条消息中,自定义通道注册 ID 和用户类目标(标签、用户ID、用户分群)不允许同时存在

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

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

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

示例

  • 使用标签发送
{
    "aud_tag": ["tag1","tag2"]
}
  • 使用用户 ID 发送
{
    "aud_userid": ["user1","user2"]
}
  • 使用用户分群发送
{
    "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"]
    }]
}

template_para:模板参数

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

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

{
     "template_para":{"user":"xxx","url":"xxx"}
}

app_para:App 参数

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

参数 类型 选项 说明
platform String/Arry String 必填 App 推送平台设置,取值:"android","ios","quickapp","winphone","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
    }
}

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

callback 包含如下字段:

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

调用返回

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

参考


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

Documentation built with MkDocs.