消息群发

说明

调用本接口群发消息。
服务地址：https://oapi.dingtalk.com

权限

服务端API是以应用维度授权的，在调用接口前，确保已经为应用添加了接口权限。详情请参考权限申请。

应用类型	是否支持调用	权限申请方式	API Explorer调试
企业内部应用	是	开发者后台申请	调试
第三方企业应用	否	—	—
第三方个人应用	否	—	—

错误码

错误码	说明	排查方法
800003	unionid不合法	传入有效的服务号unionid。
800013	群发消息太过频繁，请稍后再试	调整发送频次，稍后重试。
800014	群发消息次数超过今日限制	当天群发次数额度用完了，明天再来。
800017	向该用户发送单聊次数超过今日限制	单人定向推送时，单日限制100次。
800019	接收人列表为空	检查是否漏传了userid_list和dep_id_list。
800020	消息参数错误	检查消息内容msg_type、media_id、text_content、msg_body等字段的格式是否正确。
800022	userId列表不合法	检查传入的userid_list是否有效。
800035	uuid重复	检测到重复请求，该uuid已经用过了。
800038	uuid不能为空	必填字段不能为空。
800039	用户列表长度超过限制	单次不能超过1000个。
800040	部门列表长度超过限制	单次不能超过1000个。
800055	服务号发消息qps超过限制	接口调用太快，稍后重试，注意重试时更换uuid。
800056	服务号发消息qpm超过限制	接口调用太快，稍后重试，注意重试时更换uuid。
800057	服务号今日发消息总人次超过限制：组织人数 * 50	当天群发人次额度用完了，明天再来。

请求参数

Query 参数

access_token

string

必需

调用服务端接口的授权凭证。企业内部应用可通过调用access_token接口获得。

示例值:

30c9a84136943eaxxxx

Body 参数application/json

unionid

string

必需

服务号的unionid，可以通过查询服务号列表接口获取。

media_id

string

可选

消息卡片素材id。当参数msg_type为news_card、image类型时，该参数为必填项。

is_to_all

boolean

必需

是否群发给所有订阅者：true：是false：否

msg_type

string

必需

消息类型：text：文本类型，文本内容填在text_content字段中news_card：消息卡片，可以通过查询消息卡片列表接口获取media_idimage：图片类型，可以通过上传媒体文件接口获取media_idmarkdown：markdown消息，需要设置msg_body中markdown对象的相关参数action_card：action_card卡片消息，需要设置msg_body中action_card对象的相关参数

text_content

string

可选

文本内容，当msg_type为text时有效。

uuid

string

必需

调用时填写随机生成的UUID，防止消息重复发送。

userid_list

string

可选

接收者的用户userid列表，列表最大长度1000。

dep_id_list

array[number]

可选

接收者的部门id列表，接收者是部门id下(包括子部门下)的所有用户，列表最大长度1000。

is_preview

boolean

可选

是否预览推送，预览推送只会发给单个用户，并且内容链接24小时后可能会失效。

msg_body

object

可选

消息体。当msg_type设置为markdown时，必须传入markdown对象的相关参数；当msg_type设置为action_card时，必须传入action_card对象的相关参数。

voice

object

语音消息。

可选

object

oa消息。

可选

file

文件消息。

可选

link

object

链接消息。

可选

markdown

object

可选

markdown消息。

action_card

object

可选

action_card卡片消息。

示例

{
    "is_to_all": false,
    "dep_id_list": [
        1958658,
        2324553
    ],
    "unionid": "IlrIsTHaiSYXluZP61h0zxgiEiE",
    "is_preview": true,
    "text_content": "hello",
    "msg_body": {
        "voice": {
            "duration": 1,
            "media_id": "@lALPDeC2uOPVEsvNAVjNAVg"
        },
        "oa": {
            "head": {
                "bgcolor": "11111111",
                "text": "head text"
            },
            "pc_message_url": "https://dingtalk.com",
            "body": {
                "file_count": 2,
                "image": "@lALPDeC2uOPVEsvNAVjNAVg",
                "form": {
                    "value": "value1",
                    "key": "key1"
                },
                "author": "rick",
                "rich": {
                    "unit": "kg",
                    "num": "10"
                },
                "title": "titile",
                "content": "hello"
            },
            "message_url": "https://dingtalk.com"
        },
        "file": {
            "media_id": "@lALPDeC2uOPVEsvNAVjNAVg"
        },
        "action_card": {
            "single_url": "https://dingtalk.com",
            "button_list": {
                "action_url": "btn_action_url1",
                "title": "btn_title1"
            },
            "btn_orientation": "0",
            "single_title": "single title",
            "markdown": "markdown text",
            "title": "title"
        },
        "link": {
            "text": "hello",
            "pic_url": "@lALPDeC2uOPVEsvNAVjNAVg",
            "title": "hello title",
            "message_url": "https://dingtalk.com"
        },
        "markdown": {
            "text": "markdown text",
            "title": "title"
        }
    },
    "media_id": "",
    "msg_type": "action_card",
    "uuid": "48566508-3fdsfsfdgdsd",
    "userid_list": "10203029011219896,manager4220"
}

示例代码

Shell

JavaScript

Java

Swift

PHP

Python

HTTP

Objective-C

Ruby

OCaml

Dart

curl --location --request POST 'http://127.0.0.1/topapi/message/mass/send?access_token=30c9a84136943eaxxxx' \
--header 'Content-Type: application/json' \
--data-raw '{
    "is_to_all": false,
    "dep_id_list": [
        1958658,
        2324553
    ],
    "unionid": "IlrIsTHaiSYXluZP61h0zxgiEiE",
    "is_preview": true,
    "text_content": "hello",
    "msg_body": {
        "voice": {
            "duration": 1,
            "media_id": "@lALPDeC2uOPVEsvNAVjNAVg"
        },
        "oa": {
            "head": {
                "bgcolor": "11111111",
                "text": "head text"
            },
            "pc_message_url": "https://dingtalk.com",
            "body": {
                "file_count": 2,
                "image": "@lALPDeC2uOPVEsvNAVjNAVg",
                "form": {
                    "value": "value1",
                    "key": "key1"
                },
                "author": "rick",
                "rich": {
                    "unit": "kg",
                    "num": "10"
                },
                "title": "titile",
                "content": "hello"
            },
            "message_url": "https://dingtalk.com"
        },
        "file": {
            "media_id": "@lALPDeC2uOPVEsvNAVjNAVg"
        },
        "action_card": {
            "single_url": "https://dingtalk.com",
            "button_list": {
                "action_url": "btn_action_url1",
                "title": "btn_title1"
            },
            "btn_orientation": "0",
            "single_title": "single title",
            "markdown": "markdown text",
            "title": "title"
        },
        "link": {
            "text": "hello",
            "pic_url": "@lALPDeC2uOPVEsvNAVjNAVg",
            "title": "hello title",
            "message_url": "https://dingtalk.com"
        },
        "markdown": {
            "text": "markdown text",
            "title": "title"
        }
    },
    "media_id": "",
    "msg_type": "action_card",
    "uuid": "48566508-3fdsfsfdgdsd",
    "userid_list": "10203029011219896,manager4220"
}'

application/json

Body

errmsg

string

返回码描述。

可选

errcode

number

返回码。

可选

task_id

string

推送任务id。

可选

string

请求ID。

可选

示例

{
    "errmsg": "string",
    "errcode": 0,
    "task_id": "string",
    "": "string"
}

说明#

权限#

错误码#

请求参数

示例代码

返回响应

说明

权限

错误码