接口调用说明
- 本接口支持自定义机器人在企业内部群和普通群中发送消息,调用本接口前需要创建自定义机器人,可参见开发机器人应用。
- 如果你有大量发消息的场景(譬如系统监控报警)可以将这些信息进行整合,通过markdown消息以摘要的形式发送到群里。
-
如果自定义机器人的安全设置使用的是自定义机器人安全设置,调用本接口发送消息时,需要拼接timestamp和sign参数,示例为:
- 每个机器人每分钟最多发送20条消息到群里,如果超过20条,会限流10分钟。
请求
| 基本信息 | |
|---|---|
| HTTP URL | https://oapi.dingtalk.io/robot/send |
| HTTP Method | POST |
| 支持的应用类型 | appType-企业内部应用appType-第三方企业应用 |
| 权限要求 | permission-qyapi_base-调用企业API基础权限 |
查询参数
| 名称 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| access_token | String | 是 | BE3xxxx | 自定义机器人调用接口的凭证。 自定义机器人安装后webhook地址中的access_token值。详情参考获取自定义机器人 Webhook 地址。 |
请求体
| 名称 | 类型 | 是否必填 | 示例值 | 描述 |
|---|---|---|---|---|
| msgtype | String | 是 | text | 消息类型,自定义机器人可发送的消息类型参见自定义机器人发送消息的消息类型。 |
| msgUuid | String | 否 | 123 | 消息幂等key,可用于控制消息幂等。 说明 典型的使用场景:发消息时接口调用超时或未知错误等报错,开发者可使用同一个msgUuid重试,避免重复发出消息。 |
| text | Object | 否 | 文本类型消息。 | |
| content | String | 否 | 钉钉,让进步发生 | 文本消息的内容。 |
| at | Object | 否 | 被@的群成员信息。 | |
| isAtAll | Boolean | 否 | false | 是否@所有人。 - true:是 - false:否 |
| atMobiles | String[] | 否 | [“15xxx,18xxx”] | 被@的群成员手机号。 |
| atUserIds | String[] | 否 | [“user001”,“user002”] | 被@的群成员userId。 说明 在@群成员时,最多只能@50个。 |
| link | Object | 否 | 链接类型消息。 | |
| messageUrl | String | 否 | https://www.dingtalk.io | 点击消息跳转的URL。 |
| title | String | 否 | 这是标题 | 链接消息标题。 |
| picUrl | String | 否 | @aubHxxxxx | 链接消息内的图片地址,建议使用上传媒体文件接口获取。 |
| text | String | 否 | 链接消息的内容 | 链接消息的内容。 |
| markdown | Object | 否 | markdown类型消息。 | |
| text | String | 否 | markdown消息内容 | markdown类型消息的文本内容。 |
| title | String | 否 | 会话列表展示的标题 | 消息会话列表中展示的标题,非消息体的标题。 |
| actionCard | Object | 否 | actionCard类型消息。 | |
| hideAvatar | String | 否 | 1 | 是否显示消息发送者头像。 - 0:正常发消息者头像 - 1:隐藏发消息者头像 |
| btnOrientation | String | 否 | 1 | 消息内按钮排列方式。 - 0:按钮竖直排列 - 1:按钮横向排列 |
| singleURL | String | 否 | https://www.dingtalk.io | 点击singleTitle按钮触发的URL。 说明 消息内只有一个按钮时,该参数必填。 |
| singleTitle | String | 否 | 这是一个按钮 | 单个按钮的方案。(设置此项和singleURL后btns无效。) 说明 消息内只有一个按钮时,该参数必填。 |
| text | String | 否 | 消息内容 | actionCard类型消息的正文内容,支持markdown语法。 |
| title | String | 否 | 显示到会话列表中的标题 | 消息会话列表中展示的标题,非消息体的标题。 |
| btns | Object[] | 否 | 按钮的信息列表。 说明 消息内不止一个按钮时,该参数必填。 | |
| actionURL | String | 否 | https://www.dingtalk.io | 按钮跳转的URL。 |
| title | String | 否 | 这是一个按钮 | 按钮上显示的文本。 |
| feedCard | Object | 否 | feedCard类型消息。 | |
| links | Object[] | 否 | feedCard消息的内容列表。 | |
| picURL | String | 否 | @aubHxxxxx | feedCard消息内每条内容的图片URL,建议使用上传媒体文件接口获取。 |
| messageURL | String | 否 | https://www.dingtalk.io | feedCard消息内每条内容上午跳转链接。 |
| title | String | 否 | 消息标题 | feedCard消息内每条内容的标题。 |
请求示例
响应
响应体
| 名称 | 类型 | 示例值 | 描述 |
|---|---|---|---|
| errmsg | String | ok | 错误码描述。 |
| errcode | Number | 0 | 错误码。 |
响应体示例
错误码
若调用该接口报错,可根据错误信息在全局错误码文档中查找解决方案。| 错误码(errorcode) | 错误码描述(errmsg) | 解决方案 |
|---|---|---|
| -1 | 系统繁忙 | 请稍后重试 |
| 40035 | 缺少参数 json | 请补充消息json |
| 43004 | 无效的HTTP HEADER Content-Type | 请设置具体的消息参数 |
| 400013 | 群已被解散 | 请向其他群发消息 |
| 400101 | access_token不存在 | 请确认access_token拼写是否正确 |
| 400102 | 机器人已停用 | 请联系管理员启用机器人 |
| 400105 | 不支持的消息类型 | 请使用文档中支持的消息类型 |
| 400106 | 机器人不存在 | 请确认机器人是否在群中 |
| 410100 | 发送速度太快而限流 | 请降低发送速度 |
| 430101 | 含有不安全的外链 | 请确认发送的内容合法 |
| 430102 | 含有不合适的文本 | 请确认发送的内容合法 |
| 430103 | 含有不合适的图片 | 请确认发送的内容合法 |
| 430104 | 含有不合适的内容 | 请确认发送的内容合法 |
| 错误码(errorcode) | 错误码描述(errmsg) | 解决方案 |
|---|---|---|
| 310000 | - keywords not in content - invalid timestamp - sign not match - ip X.X.X.X not in whitelist | - 消息内容中不包含任何关键词 - timestamp 无效 - 签名不匹配 - IP 地址不在白名单 |