Skip to content

应用消息

消息推送

js
POST /v1/apps/mbox?access_token={access_token}&source_type={source_type}&for_all={for_all}

请求头部:

请求头说明
Content-Typeapplication/json

Url请求参数:

字段类型是否必填说明
access_tokenStringY访问令牌
directBooleanNdirect = true时,消息直推推送,用于推送少量人员(400人以内);只支持client_ids、usernames的推送;不支持范围scopes推送
direct = false时,消息队列推送,用于推送大范围人员;支持client_ids、usernames, scopes的推送;支持范围scopes推送
默认值: false
for_allBooleanN是否全员推送
client_ids、usernames、scopes三者均为空,for_all=true时,才全员推消息;
否则以范围参数为准[client_ids、usernames、scopes]
默认值: false

请求参数:

字段类型是否必填说明
source_typeStringN枚举,NATIVE/ISV,默认值为NATIVE,ISV应用时传ISV
typeStringY消息类型, text/iamge/file/article/template/rich_text
client_idsList<String>N消息推送的用户标识
scopesList<String>N发送范围,组织路径,例如/122/234/
usernamesList<String>N用户账号列表
platformsListN枚举,ANDROID/IOS/PC,默认值为IOS和ANDROID
bodyMapY推送消息体
body.at_allbooleanN是否AT所有人员
body.contentStringN发送内容,具体根据消息类型决定
body.is_gifintN是否gif图片,1代表是
body.sizeintN大小
body.widthintN图片宽度
body.heightintN图片高度
body.media_idStringN发送的媒体ID
body.pathStringN发送的媒体ID
body.file_statusintN文件状态,0为正常
body.nameStringN名称
body.articles.summaryStringN文章摘要
body.articles.cover_urlStringN封面URL 或 封面媒体Id
body.articles.cover_enabledbooleanN是否显示封面,true/false
body.articles.create_timelongN创建时间
body.articles.titleStringN文章标题
body.articles.urlStringN图文详情内容,有些获取url内容,为空时,图文详情显示content内容
body.template_idStringN模板ID,模板消息必填
body.dataJsonN模板数据,模板消息必填,value为变量值,color为颜色,font_size为字号大小.
详情见下面模板消息示例
body.emphasis_keywordStringN高亮属性,保留字段
body.top_colorStringN顶部颜色
body.top_avatarStringN顶部图标
body.top_titleStringN顶部标题
body.data.text_styleStringNnormal(正常)bold(粗体)
actionsJsonN消息按钮
第一层数据代表的多少行按钮[目前最多5个],
第二层数据代表一行有多少个按钮[目前最多5个]

参考按钮actions
action_aclJsonN按钮访问控制,参考按钮访问控制action_acl

请求示例:

js
/v1/apps/mbox?access_token=b646339e2f4f4234af6bae5f72db9879

文本示例:

点击查看文本示例
字段类型必填说明
typeStringY消息类型,文本消息值: text
bodyMapY推送消息体
body.contentStringY消息内容
json
{
  "type": "TEXT", 
  "body": {
    "at_all": false, 
    "content": "2"
  }, 
  "client_ids": [
    "c24b6a94cfb14b79af12a1399edc9e31"
  ],
  "usernames": [
    "username1"
  ],
  "platforms": [
    "ANDROID","IOS","PC"
  ]
}

文本消息显示效果:

text-message.png

Curl示例:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
    "type": "text",
    "body":
    {
        "content": "测试文本消息"
    },
    "usernames":
    [
        "username1","username2"
    ]
}' \
 'https://替换成你的域名/v1/apps/mbox?access_token={替换成你的access_token}'

图片示例:

点击查看图片示例
字段类型必填说明
typeStringY消息类型, 文本消息值: image
bodyMapY推送消息体
body.is_gifBooleanN是否是gif,默认值: false
body.media_idStringY发送的媒体ID
body.sizeIntN图片大小,默认值: 0
body.heightIntN图片高度,默认值: 0
body.widthIntN图片宽度,默认值: 0
json
{
  "type": "IMAGE", 
  "body": {
    "is_gif": 0, 
    "size": 1852, 
    "width": 280, 
    "media_id": "Z3JvdXAxL00wMC8wMC80OC9yQkFCR1ZkaFI5Q0FjNmp2QUFBSFBIRkhXSkk1NDEuanBn", 
    "content": "图片内容,base64编码", 
    "height": 280
  }, 
  "client_ids": [
    "c24b6a94cfb14b79af12a1399edc9e31"
  ],
  "usernames": [
    "username1"
  ],
  "platforms": [
    "ANDROID","IOS","PC"
  ]
}

图片消息显示效果:

image-message.png

Curl示例:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
  "type": "IMAGE", 
  "body": {
    "is_gif": 0, 
    "size": 1852, 
    "width": 280, 
    "media_id": "Z3JvdXAxL00wMC8wMC80OC9yQkFCR1ZkaFI5Q0FjNmp2QUFBSFBIRkhXSkk1NDEuanBn", 
    "content": "图片内容,base64编码", 
    "height": 280
  }, 
  "usernames": [
    "username1","username2"
  ],
  "platforms": [
    "ANDROID","IOS","PC"
  ]
}' \
 'https://替换成你的域名/v1/apps/mbox?access_token={替换成你的access_token}'

文件示例:

点击查看文件示例
字段类型必填说明
typeStringY消息类型,文本消息值: file
bodyMapY推送消息体
body.nameStringN文件名
body.media_idStringY发送的媒体ID
body.sizeIntN图片大小,默认值: 0
json
{
  "type": "FILE", 
  "body": {
    "size": 71416, 
    "name": "IMG_0778.GIF", 
    "media_id": "Z3JvdXAxL00wMC8wMC80Ny9yQkFCR1ZkaEdBZUFYRkxmQUFFVy1JYmNRbTgwNjkuZ2lm", 
  }, 
  "client_ids": [
    "c24b6a94cfb14b79af12a1399edc9e31"
  ],
  "platforms": [
    "ANDROID","IOS","PC"
  ]
}

图文示例:

点击查看图文示例
字段类型必填说明
typeStringY消息类型, 文本消息值: article
bodyMapY推送消息体
body.articlesStringArrayYarticles数组为1时:代表单图文articles数组为大于1时:代表多图文
body.articles.summaryStringN发送的媒体ID
body.articles.cover_urlStringN图文封面URL 或 封面媒体Id
body.articles.cover_enabledBooleanN是否显示封面,true/false
body.articles.titleStringY文章标题
body.articles.urlStringY图文详情跳转链接
json
{
  "type": "article",
  "body":
  {
    "articles":
    [
      {
        "summary": "防汛关键期来临——新技术+“老把式”,提升监测预警能力",
        "cover_enabled": false,
        "cover_url": "https://inews.gtimg.com/news_bt/OStKexVGk5VtT7QWWMjPT19ZIDIb8RdIL5EoftBx2N7XoAA/641",
        "create_time": 1465205632846,
        "author": "凯里",
        "title": "防汛关键期来临——新技术+“老把式”,提升监测预警能力",
        "url": "https://news.qq.com/rain/a/20250716A09MG100"
      },
      {
        "summary": "水利部:今年防汛关键期 黄河、海河等流域可能发生较大洪水",
        "cover_enabled": false,
        "cover_url": "https://inews.gtimg.com/om_bt/OHBplHUS5Th8LO1zbNqthZdvLoF2h7_-H0YsERdvO0bosAA/0",
        "create_time": 1465205632846,
        "author": "凯里",
        "title": "水利部:今年防汛关键期 黄河、海河等流域可能发生较大洪水",
        "url": "https://news.qq.com/rain/a/20250716A06TH500"
      }
    ]
  },
  "usernames":
  [
    "524064"
  ],
  "platforms":
  [
    "ANDROID",
    "IOS",
    "PC"
  ]
}

模板消息--根据模板ID:

点击查看模板消息示例
字段类型必填说明
typeStringY消息类型 ,文本消息值: image
bodyMapY推送消息体
body.template_idStringY模板消息ID
body.top_colorStringN顶部颜色
body.top_avatarStringN顶部图标
body.top_titleStringN顶部标题
body.dataJsonN模板数据,模板消息必填,value为变量值,color为颜色,font_size为字号大小.
详情见下面模板消息示例
json
{
  "type": "TEMPLATE", 
  "body": {
    "template_id": "152891af-1bec-4a18-8201-a58e08a7afad", 
    "top_color": "#00ff00",
    "top_avatar": "Z3JvdXAxL00wMC8wMC80MC9yQkFCR1ZkWDQ0ZUFRY21LQUFBZXVHZDBHS0U4MTkuanBn",
    "top_title": "流程大师",
    "data": [
      {
        "key": "keyword1", 
        "value": "339208499", 
        "color": "#00ff00", 
        "font_size": "12", 
        "text_style": "normal"
      }, 
      {
        "key": "keyword2", 
        "value": "2016年01月05日", 
        "color": "#00ff00", 
        "font_size": "12", 
        "text_style": "normal"
      }, 
      {
        "key": "keyword3", 
        "value": "830138013810", 
        "color": "#00ff00", 
        "font_size": "12", 
        "text_style": "normal"
      }, 
      {
        "key": "keyword4", 
        "value": "8310380131", 
        "color": "#00ff00", 
        "font_size": "12", 
        "text_style": "bold"
      }
    ],
    "emphasis_keyword": "keyword1.DATA"
  }, 
  "client_ids": [
    "a86e83a26be44eb59806901cc8be5d5c"
  ], 
  "platforms": [
    "ANDROID"
  ]
}

模板消息设置:

template-template.png

模版消息显示效果:template-message.png

Curl示例:

curl -i -X POST \
   -H "Content-Type:application/json" \
   -d \
'{
    "type": "TEMPLATE",
    "body":
    {
        "template_id": "0196ec87c52376598999e17768c59e17",
        "top_color": "#ffff00",
        "top_avatar": "01971626be367cb3b57ac2313b07eb43",
        "top_title": "流程大师",
        "data":
        [
            {
                "key": "sn",
                "value": "339208499",
                "color": "#00ff00",
                "font_size": "14",
                "text_style": "normal"
            },
            {
                "key": "type",
                "value": "缴存业务",
                "color": "#00ff00",
                "font_size": "14",
                "text_style": "normal"
            },
            {
                "key": "data",
                "value": "2016年01月05日",
                "color": "#00ff00",
                "font_size": "12",
                "text_style": "normal"
            },
            {
                "key": "url",
                "value": "https://www.baidu.com",
                "color": "#00ff00",
                "font_size": "12",
                "text_style": "bold"
            }
        ]
    },
    "usernames": [
    "username1","username2"
  ],
  "platforms": [
    "ANDROID","IOS","PC"
  ]
}' \
 'https://替换成你的域名/v1/apps/mbox?access_token={替换成你的access_token}'

富文本消息示例:

请前往富文本消息页面查看详细说明。

返回数据:

字段类型说明
idString推送计划ID
app_idString推送应用ID
plan_timeLong推送时间
recipientsList<String>消息推送的用户标识
include_usernamesList<String>消息推送的用户名
exclude_usernamesList<String>消息未推送的用户名(用户不存在或不在使用范围)
include_client_idsList<String>消息推送的用户标识
exclude_client_idsList<String>消息未推送的用户标识(用户不存在或不在使用范围)

返回示例:

json
{
  "status": 0,
  "message": "ok",
  "result":
  {
    "recipients":
    [
      "a673e99a034646dd9ee458fa1c08b87f"
    ],
    "plan_time": 1753493160759,
    "include_usernames":
    [
      "kf13"
    ],
    "id": "0198445643377e99a5c4d95e7044d61a",
    "exclude_client_ids":
    [],
    "app_id": "2777878f6bff481882d221df5b57139dA7Zork2YLw6DoYpn",
    "conversation_id": "5afc0ccbffca95eec7c1b128a0492d5bf8cf0e9d7c95ad94c80695c3d40d909de0db8b0fb4a0c8009bfc88a2968c7ff6407861a09b35e329acdabb8000162b06",
    "org_id": "b276533349664385b31181fa3455ef8c",
    "create_time": 1753493160759,
    "domain_id": "workplus",
    "include_client_ids":
    [],
    "plan_id": "0198445643377e99a5c4d95e7044d61a",
    "exclude_usernames":
    []
  }
}

错误返回值:

statusmessage说明
10011token not found.访问令牌不存在
202012没有对应的雇员没有对应的雇员

错误返回值:

statusmessage说明
10011token not found.访问令牌不存在