文档中心 合规指南 开发者社区
极光文档 > 极光统一消息 > REST API > 普通消息发送
极光文档 > 极光统一消息 > REST API > 普通消息发送
普通消息发送 v1
最近更新：2022-3-22
展开全部

普通消息发送 v1

API 概述

功能说明

普通消息发送的 API 可以自由选择发送通道，填写消息内容，每个通道的消息字段完全遵循通道本身的要求。

可以选择向单个用户或用户列表发送一条消息。

调用地址

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

其他方式发送：POST https://api.ums.jiguang.cn/v1/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 发送目标部分。
msg_xxx Object Array 必填 各通道的消息内容，xxx 部分的取值详见下文 msg_xxx 消息内容部分。
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"], "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 } } }' > 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"],
    "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
         }
    }
}'

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

返回参数与示例

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

aud_xxx：发送目标

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

广播

当广播所有人时，请调用广播专用的 API https://api.ums.jiguang.cn/v1/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 * 企业微信互联企业：wechatwk_linkedcorp
          * App：app
* 微信公众号：wechatoa
* 微信小程序：wechatmp
* 短信：sms
* 邮箱：email
* 支付宝生活号：alipay_life
* 钉钉：dingtalk_cc
* 企业微信：wechatwk
* 企业微信互联企业：wechatwk_linkedcorp
此代码块在浮窗中显示

注意：在一条消息中，自定义通道注册 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": ["support@jiguang.cn"] }], "aud_alipay_life": [{ "instance": "alipaylife", "data": ["2088102733318286"] }], "aud_dingtalk_cc": [{ "instance": "dingtalkcc", "data": ["a3c213779d163837895b30f47aaa94c3"] }], "aud_wechatwk": [{ "instance": "wechatwk", "data": ["zhangsan"] }], "aud_wechatwk_linkedcorp": [{ "instance": "wechatwk_linkedcorp", "data": ["CorpId1/userid1","CorpId2/userid2"] }] }
          {
    "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": ["support@jiguang.cn"]
    }],
    "aud_alipay_life": [{
      "instance": "alipaylife",
      "data": ["2088102733318286"]
    }],
    "aud_dingtalk_cc": [{
      "instance": "dingtalkcc",
      "data": ["a3c213779d163837895b30f47aaa94c3"]
    }],
    "aud_wechatwk": [{
      "instance": "wechatwk",
      "data": ["zhangsan"]
    }],
    "aud_wechatwk_linkedcorp": [{
      "instance": "wechatwk_linkedcorp",
      "data": ["CorpId1/userid1","CorpId2/userid2"]
    }]
}
此代码块在浮窗中显示

msg_xxx：消息内容

普通消息发送时，消息内容完全遵循通道本身的要求。根据通道的不同，xxx 部分的取值为：

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

在请求体中填写的 msg_xxx 决定本次消息将发送给哪几种通道。

  • 如果使用自定义通道注册 ID 发送，aud_xxx 和 msg_xxx 需要一一对应。
  • 如果使用了发送策略，策略中包含的通道和 msg_xxx 中的通道信息需要一致。
  • 向企业微信的互联企业发送时，与企业微信共用 msg_wechatwk。

msg_app：App 消息

当前 UMS 默认对接极光推送，因此 App 的消息内容可参考 JPush REST API

JPush 支持发送的大部分参数均可在此传递，不支持的参数有： callback 、Audience 、VOIP

"msg_app":[{ "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e", "platform": "all", "notification": { "android": { "alert": "Hi, JPush!", "title": "Send to Android", "builder_id": 1, "large_icon": "http://www.jiguang.cn/largeIcon.jpg", "intent": { "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end", }, "extras": { "newsid": 321 } }, "ios": { "alert": "Hi, JPush!", "sound": "default", "badge": "+1", "thread-id": "default" "extras": { "newsid": 321 } } "quickapp": { "alert": "Hi, JPush!", "title": "Send to QuickApp", "page": "/page1" } }, "message": { "msg_content": "Hi,JPush", "content_type": "text", "title": "msg", "extras": { "key": "value" } }, "options": { "time_to_live": 60, "apns_production": false, "apns_collapse_id":"jiguang_test_201706011100" } }]
          "msg_app":[{
    "cid": "8103a4c628a0b98974ec1949-711261d4-5f17-4d2f-a855-5e5a8909b26e",
    "platform": "all",
    "notification": {
        "android": {
            "alert": "Hi, JPush!",
            "title": "Send to Android",
            "builder_id": 1,
            "large_icon": "http://www.jiguang.cn/largeIcon.jpg",
            "intent": {
                "url": "intent:#Intent;component=com.jiguang.push/com.example.jpushdemo.SettingActivity;end",
            },
            "extras": {
                "newsid": 321
            }
        },
        "ios": {
            "alert": "Hi, JPush!",
            "sound": "default",
            "badge": "+1",
            "thread-id": "default"
            "extras": {
                "newsid": 321
            }
        }
        "quickapp": {
            "alert": "Hi, JPush!",
            "title": "Send to QuickApp",
            "page": "/page1"
        }
    },
    "message": {
        "msg_content": "Hi,JPush",
        "content_type": "text",
        "title": "msg",
        "extras": {
            "key": "value"
        }
    },
    "options": {
        "time_to_live": 60,
        "apns_production": false,
        "apns_collapse_id":"jiguang_test_201706011100"
    }
}]
此代码块在浮窗中显示

msg_wechatoa：微信公众号消息

微信公众号支持模板消息、订阅通知 2 种，通过 type 区分。除了接收者 openID 被 UMS 的目标字段替代外，官方文档中的相关参数均可在此传递

参数 类型 选项 说明
type int 必填 消息类型，0-模板消息，1-订阅通知

模板消息参数

参数 类型 选项 说明
type int 必填 消息类型，模板消息类型取值为 0
template_id String 必填 模板ID
url String 可选 模板跳转链接
miniprogram JSON Object 可选 跳小程序所需数据，不需跳小程序可不用传该数据，url 和 miniprogram 同时不填，无跳转；page 和 miniprogram 同时填写，优先跳转小程序
appid String 可选 所需跳转到的小程序appid（该小程序appid必须与发模板消息的公众号是绑定关联关系，暂不支持小游戏）
pagepath String 可选 所需跳转到小程序的具体页面路径，支持带参数,（示例index?foo=bar），要求该小程序已发布，暂不支持小游戏
data JSON Object 必填 模板内容，格式形如{"key1":{"value": any,"color":"#173177"},"key2":{"value":any}}
color String 可选 模板内容字体颜色，不填默认为黑色
"msg_wechatoa": [{ "type": 0, "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY", "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" } } }]
          "msg_wechatoa": [{
    "type": 0,
    "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
    "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"
            }
    }
}]
此代码块在浮窗中显示

订阅通知参数

参数 类型 选项 说明
type int 必填 消息类型，订阅通知类型取值为 1
template_id String 必填 模板ID
page String 可选 跳转网页
miniprogram JSON Object 可选 跳转小程序所需数据，不需跳转小程序可不用传该数据，page 和 miniprogram 同时不填，无跳转；page 和 miniprogram 同时填写，优先跳转小程序
appid String 可选 所需跳转到的小程序appid（该小程序appid必须与发模板消息的公众号是绑定关联关系，暂不支持小游戏）
pagepath String 可选 所需跳转到小程序的具体页面路径，支持带参数,（示例index?foo=bar），要求该小程序已发布，暂不支持小游戏
data JSON Object 必填 模板内容，格式形如{"key1":{"value": any,"color":"#173177"},"key2":{"value":any}}，其中参数的限制请参考官方文档
"msg_wechatoa": [{ "type": 1, "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY", "page":"http://weixin.qq.com/download", "miniprogram":{ "appid":"xiaochengxuappid12345", "pagepath":"index?foo=bar" }, "data": { "name1": { "value": "广州腾讯科技有限公司" }, "thing8": { "value": "广州腾讯科技有限公司" }, "time7": { "value": "2019年8月8日" } } }]
          "msg_wechatoa": [{
    "type": 1,
    "template_id":"ngqIpbwh8bUfcSsECmogfXcV14J0tQlEpBO27izEYtY",
    "page":"http://weixin.qq.com/download",
    "miniprogram":{
        "appid":"xiaochengxuappid12345",
        "pagepath":"index?foo=bar"
    },
    "data": {
      "name1": {
          "value": "广州腾讯科技有限公司"
      },
      "thing8": {
          "value": "广州腾讯科技有限公司"
      },
       "time7": {
          "value": "2019年8月8日"
      }
     }
}]
此代码块在浮窗中显示

msg_wechatmp：微信小程序消息

微信小程序支持模板消息 ，除了接收者 openID 被 UMS 的目标字段替代外，官方文档中的相关参数均可在此传递

参数 类型 选项 说明
template_id String 必填 模板ID
page String 可选 点击模板卡片后的跳转页面，仅限本小程序内的页面。支持带参数,（示例index?foo=bar）。该字段不填则模板无跳转。
data JSON Object 必填 模板内容，格式形如{"key1":{"value": any},"key2":{"value":any}}
miniprogram_state String 可选 跳转小程序类型：developer为开发版；trial为体验版；formal为正式版；默认为正式版
lang String 可选 进入小程序查看”的语言类型，支持zh_CN(简体中文)、en_US(英文)、zh_HK(繁体中文)、zh_TW(繁体中文)，默认为zh_CN
"msg_wechatmp": [{ "template_id": "TEMPLATE_ID", "page": "index", "miniprogram_state":"developer", "lang":"zh_CN", "data": { "number01": { "value": "339208499" }, "date01": { "value": "2015年01月05日" }, "site01": { "value": "TIT创意园" } , "site02": { "value": "广州市新港中路397号" } } }]
          "msg_wechatmp": [{
  "template_id": "TEMPLATE_ID",
  "page": "index",
  "miniprogram_state":"developer",
  "lang":"zh_CN",
  "data": {
      "number01": {
          "value": "339208499"
      },
      "date01": {
          "value": "2015年01月05日"
      },
      "site01": {
          "value": "TIT创意园"
      } ,
      "site02": {
          "value": "广州市新港中路397号"
      }
  }
}]
此代码块在浮窗中显示

msg_sms：短信消息

极光短信

当前 UMS 默认对接极光短信，因此使用极光短信时的消息内容可参考 短信发送 API 中的单条模板消息

参数 类型 选项 说明
sign_id String 可选 签名ID，该字段为空则使用应用默认签名
temp_id int 必填 模板ID
temp_para JSON Object 必填 模板参数,需要替换的参数名和 value 的键值对
"msg_sms": [{ "sign_id": "1", "temp_id": 1, "temp_para": {"code":"1234"} }]
          "msg_sms": [{
      "sign_id": "1",
      "temp_id": 1,
      "temp_para": {"code":"1234"}
    }]
此代码块在浮窗中显示

CMPP 短信

使用 CMPP 对接的短信平台只需传递短信内容 content ，示例如下：

"msg_sms": [{ "content":"您登录系统的动态码为：111 ，动态码有效时间为1分钟，请注意保密。" }]
          "msg_sms": [{
      "content":"您登录系统的动态码为：111 ，动态码有效时间为1分钟，请注意保密。"
    }]
此代码块在浮窗中显示

msg_email：邮件消息

邮件消息支持传递邮件标题、邮件内容。

参数 类型 选项 说明
subject string 必填 邮件标题
text string 必填 邮件内容，支持 HTML 格式
files Object Array 选填 邮件附件
1、使用素材管理接口上传附件，然后将获得的URL传值在此
2、将任意URL地址传值在此，需保证该地址可被UMS访问
"msg_email": [{ "subject": "hello, ums email!", "text": "ums email test. reply", "files": ["填写url1","填写url2"] }]
            "msg_email": [{
    "subject": "hello, ums email!",
    "text": "ums email test. reply",
    "files": ["填写url1","填写url2"]
  }]
此代码块在浮窗中显示

msg_alipay_life：支付宝生活号消息

当前支付宝生活号支持发送模板消息，参数说明如下：

参数 类型 选项 说明
template_id String 必填 消息模板 ID，最大长度 128
context JSON Object 必填 消息模板上下文，即模板中定义的参数及参数值

context 字段

context 中可传参数如下：

参数 类型 选项 说明
head_color String 必填 顶部色条的色值，最大长度 10
url String 必填 点击消息后承接页的地址，最大长度 256
action_name String 必填 底部链接描述文字，如“查看详情”，最多能传8个汉字或16个英文字符
keyword1 JSON Object 可选 模板中占位符的值（value）及文字颜色（color），如果申请的模板中含有该占位符，则必填。如有多个则需填写多个，如keyword2、keyword3 等。value 最大长度 128
first JSON Object 可选 模板中占位符的值（value）及文字颜色（color），first 一般为开头语的占位符，如果申请的模板中含有该占位符，则必填
remark JSON Object 可选 模板中占位符的值（value）及文字颜色（color），remark 一般为结束语的占位符，如果申请的模板中含有该占位符，则必填
"msg_alipay_life": [{ "template_id": "e5326c1d5c71419893646ad9571a93e8", "context":{ "head_color": "#85be53", "url":"http://www.baidu.com", "action_name": "查看详情", "keyword1": { "color": "#85be53", "value": "你已经激活了上火星指令"}, "keyword2": { "color": "#85be53", "value": "2020 09-29"}, "first": { "color": "#85be53", "value": "HI.真的 已经激活了指令"}, "remark": { "color": "#85be53", "value": "指令已经通过"} } }]
            "msg_alipay_life": [{
      "template_id": "e5326c1d5c71419893646ad9571a93e8",
      "context":{
        "head_color": "#85be53",
        "url":"http://www.baidu.com",
        "action_name": "查看详情",
        "keyword1": {
            "color": "#85be53",
            "value": "你已经激活了上火星指令"},
        "keyword2": {
            "color": "#85be53",
            "value": "2020 09-29"},
        "first": {
            "color": "#85be53",
            "value": "HI.真的 已经激活了指令"},
        "remark": {
            "color": "#85be53",
            "value": "指令已经通过"}
        }
    }]
此代码块在浮窗中显示

msg_dingtalk_cc：钉钉工作通知

当前钉钉工作通知支持发送文本消息

文本消息

参数 类型 选项 说明
msgtype String 必填 消息类型，文本消息类型为：text。
content String 必填 消息内容，建议500字符以内。
"msg_dingtalk_cc": [{ "msg":{ "msgtype": "text", "text": { "content":"test" } } }]
          "msg_dingtalk_cc": [{
      "msg":{
        "msgtype": "text",
        "text": {
          "content":"test"
        }
      }
    }]
此代码块在浮窗中显示

msg_wechatwk：企业微信

企业微信支持的消息类型包含：文本消息、图片消息、文件消息、外链图文、图文消息、小程序通知消息。参考官方文档。

企业微信同时支持向企微互联用户发送，消息格式与本企业的发送是一致的，参考官方文档，因此你只需传 1 次消息内容，UMS 系统将会根据 aud 的设置自动路由到互联企业用户或者本企业用户。

文本消息

参数 类型 选项 说明
msgtype String 必填 消息类型，文本消息类型为：text。
content String 必填 消息内容，最长不超过 2048 个字节。
safe int 选填 表示是否是保密消息，0 表示可对外分享，1 表示不能分享且内容显示水印，默认为 0
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval int 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "text", "text": { "content": "你的快递已到，请携带工卡前往邮件中心领取,聪明避开排队。" }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "text",
    "text": {
        "content": "你的快递已到，请携带工卡前往邮件中心领取,聪明避开排队。"
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

图片消息

参数 类型 选项 说明
msgtype String 必填 消息类型，图片消息类型为：image。
media_id String 必填 图片媒体文件 id，可以调用上传临时素材接口获取。
safe int 选填 表示是否是保密消息，0 表示可对外分享，1 表示不能分享且内容显示水印，默认为 0
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval int 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "image", "image": { "media_id": "MEDIA_ID" }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "image",
    "image": {
        "media_id": "MEDIA_ID"
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

文件消息

参数 类型 选项 说明
msgtype String 必填 消息类型，文件消息类型为：file。
media_id String 必填 文件 id，可以调用上传临时素材接口获取。
safe int 选填 表示是否是保密消息，0 表示可对外分享，1 表示不能分享且内容显示水印，默认为 0
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval int 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "file", "file": { "media_id": "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o" }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "file",
    "file": {
        "media_id": "1Yv-zXfHjSjU-7LH-GwtYqDGS-zz6w22KmWAT5COgP7o"
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

外链图文

参数 类型 选项 说明
msgtype String 必填 消息类型，外链图文消息类型为：news。
articles JSON Object 必填 图文消息，一个图文消息支持 1 到 8 条图文
title String 必填 标题，不超过128个字节
description String 选填 描述，不超过512个字节
url String 选填 点击后跳转的链接，最长2048字节。请确保包含了协议头(http/https)，小程序或者url必须填写一个
picurl String 选填 图文消息的封面图片链接，支持JPG、PNG格式，较好的效果为大图 1068*455，小图150*150。
appid String 选填 小程序appid，必须是与当前应用关联的小程序，appid和pagepath必须同时填写，填写后会忽略url字段
pagepath String 选填 点击消息卡片后的小程序页面，仅限本小程序内的页面。appid和pagepath必须同时填写，填写后会忽略url字段
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval int 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "news", "news": { "articles": [{ "title": "中秋节礼品领取", "description": "今年中秋节公司有豪礼相送", "url": "URL", "picurl": "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png" }] }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "news",
    "news": {
        "articles": [{
                "title": "中秋节礼品领取",
                "description": "今年中秋节公司有豪礼相送",
                "url": "URL",
                "picurl": "http://res.mail.qq.com/node/ww/wwopenmng/images/independent/doc/test_pic_msg1.png"
        }]
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

图文消息

图文消息与外链图文的区别是可以填写具体的内容，该内容将存储在企业微信

参数 类型 选项 说明
msgtype String 必填 消息类型，图文消息类型为：mpnews。
articles JSON Object 必填 图文消息，一个图文消息支持 1 到 8 条图文
thumb_media_id String 必填 图文消息缩略图的 media_id, 可以通过素材管理接口获得。此处 thumb_media_id 即上传接口返回的 media_id
title String 必填 标题，不超过 128 个字节
content String 必填 图文消息的内容，支持 html 标签，不超过 666 K个字节
digest String 选填 图文消息的描述，不超过 512 个字节
author String 选填 图文消息的作者，不超过 64 个字节
content_source_url String 选填 图文消息点击“阅读原文”之后的页面链接
safe int 选填 表示是否是保密消息，0表示可对外分享（默认），1表示不能分享且内容显示水印，2表示仅限在企业内分享
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval String 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "mpnews", "mpnews": { "articles": [{ "thumb_media_id": "MEDIA_ID", "title": "Title", "content": "Content", "digest": "Digest description", "author": "Author", "content_source_url": "URL" }] }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "mpnews",
    "mpnews": {
        "articles": [{
            "thumb_media_id": "MEDIA_ID",
            "title": "Title",
            "content": "Content",
            "digest": "Digest description",
            "author": "Author",
            "content_source_url": "URL"
        }]
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

小程序通知消息

参数 类型 选项 说明
msgtype String 必填 消息类型，小程序通知消息类型为：miniprogram_notice。
appid String 必填 小程序appid，必须是与当前应用关联的小程序
page String 选填 点击消息卡片后的小程序页面，仅限本小程序内的页面。该字段不填则消息点击后不跳转。
title String 必填 消息标题，长度限制 4-12 个汉字
description String 选填 消息描述，长度限制 4-12 个汉字
emphasis_first_item String 选填 是否放大第一个 content_item
content_item String 选填 消息内容键值对，最多允许 10 个 item
key String 必填 长度10个汉字以内
value String 必填 长度30个汉字以内
safe int 选填 表示是否是保密消息，0表示可对外分享（默认），1表示不能分享且内容显示水印，2表示仅限在企业内分享
enable_duplicate_check int 选填 表示是否开启重复消息检查，0表示否，1表示是，默认0
duplicate_check_interval String 选填 表示是否重复消息检查的时间间隔，默认1800s，最大不超过4小时
"msg_wechatwk": [{ "msgtype": "miniprogram_notice", "miniprogram_notice": { "appid": "wx123123123123123", "page": "pages/index?userid=zhangsan&orderid=123123123", "title": "会议室预订成功通知", "description": "4月27日 16:16", "emphasis_first_item": true, "content_item": [ { "key": "会议室", "value": "402" }, { "key": "会议地点", "value": "广州TIT-402会议室" }, { "key": "会议时间", "value": "2018年8月1日 09:00-09:30" }, { "key": "参与人员", "value": "周剑轩" } ] }, "safe": 0, "enable_duplicate_check": 1, "duplicate_check_interval": 1800 }]
          "msg_wechatwk": [{
    "msgtype": "miniprogram_notice",
    "miniprogram_notice": {
        "appid": "wx123123123123123",
        "page": "pages/index?userid=zhangsan&orderid=123123123",
        "title": "会议室预订成功通知",
        "description": "4月27日 16:16",
        "emphasis_first_item": true,
        "content_item": [
            {
                "key": "会议室",
                "value": "402"
            },
            {
                "key": "会议地点",
                "value": "广州TIT-402会议室"
            },
            {
                "key": "会议时间",
                "value": "2018年8月1日 09:00-09:30"
            },
            {
                "key": "参与人员",
                "value": "周剑轩"
            }
        ]
    },
    "safe": 0,
    "enable_duplicate_check": 1,
    "duplicate_check_interval": 1800
}]
此代码块在浮窗中显示

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 深圳市和讯华谷信息技术有限公司

在文档中心打开