API call description
- This API allows a custom bot to send chats in Internal Groups and Standard Groups within your organization. Before calling this API, create a custom bot. For details, see Develop bot apps.
- If you have a large volume of chats to send (for example, system monitoring alerts), consolidate the information and send it to the group as a summary in a markdown chat.
-
If the custom bot uses the custom bot security settings, append the
timestampandsignparameters when calling this API. Example: - Each bot can send up to 20 chats per minute to a group. Exceeding 20 chats triggers a 10-minute rate limit.
Request
| Basic information | |
|---|---|
| HTTP URL | https://oapi.dingtalk.io/robot/send |
| HTTP Method | POST |
| Supported app types | appType-Internal app appType-Third-party enterprise app |
| Required permissions | permission-qyapi_base-Basic permission to call enterprise APIs |
Query parameters
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| access_token | String | Yes | BE3xxxx | The credential used by the custom bot to call the API. The access_token value from the Webhook URL generated after the custom bot is installed. For details, see Obtain the Webhook URL of a custom bot. |
Request body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| msgtype | String | Yes | text | The chat type. For chat types supported by custom bots, see Chat types supported by custom bots. |
| msgUuid | String | No | 123 | The idempotency key for the chat, used to control idempotency. Note Typical use case: when an API call times out or returns an unknown error, retry with the same msgUuid to avoid sending duplicate chats. |
| text | Object | No | A text chat. | |
| content | String | No | DingTalk makes progress happen | The content of the text chat. |
| at | Object | No | Information about the group members mentioned with @. | |
| isAtAll | Boolean | No | false | Whether to mention @Everyone. - true: Yes - false: No |
| atMobiles | String[] | No | [“15xxx,18xxx”] | The mobile numbers of the group members to mention with @. |
| atUserIds | String[] | No | [“user001”,“user002”] | The userId of the group members to mention with @. Note When mentioning group members with @, you can mention up to 50 members. |
| link | Object | No | A link chat. | |
| messageUrl | String | No | https://www.dingtalk.io | The URL to redirect to when the chat is tapped. |
| title | String | No | This is the title | The title of the link chat. |
| picUrl | String | No | @aubHxxxxx | The image URL in the link chat. We recommend using the Upload media files API to obtain it. |
| text | String | No | The content of the link chat | The content of the link chat. |
| markdown | Object | No | A markdown chat. | |
| text | String | No | markdown chat content | The text content of the markdown chat. |
| title | String | No | The title shown in the chat list | The title shown in the chat list, not the title of the chat body. |
| actionCard | Object | No | An actionCard chat. | |
| hideAvatar | String | No | 1 | Whether to display the profile photo of the sender. - 0: Display the sender’s profile photo - 1: Hide the sender’s profile photo |
| btnOrientation | String | No | 1 | The button layout in the chat. - 0: Buttons arranged vertically - 1: Buttons arranged horizontally |
| singleURL | String | No | https://www.dingtalk.io | The URL triggered when the singleTitle button is tapped. Note Required when the chat contains only one button. |
| singleTitle | String | No | This is a button | The single-button option. (When this and singleURL are set, btns does not take effect.) Note Required when the chat contains only one button. |
| text | String | No | Chat content | The body content of the actionCard chat. Markdown syntax is supported. |
| title | String | No | The title shown in the chat list | The title shown in the chat list, not the title of the chat body. |
| btns | Object[] | No | The list of button information. Note Required when the chat contains more than one button. | |
| actionURL | String | No | https://www.dingtalk.io | The URL the button redirects to. |
| title | String | No | This is a button | The text displayed on the button. |
| feedCard | Object | No | A feedCard chat. | |
| links | Object[] | No | The content list of the feedCard chat. | |
| picURL | String | No | @aubHxxxxx | The image URL for each item in the feedCard chat. We recommend using the Upload media files API to obtain it. |
| messageURL | String | No | https://www.dingtalk.io | The redirect URL for each item in the feedCard chat. |
| title | String | No | Chat title | The title of each item in the feedCard chat. |
Request example
Response
Response body
| Name | Type | Example | Description |
|---|---|---|---|
| errmsg | String | ok | The error code description. |
| errcode | Number | 0 | The error code. |
Response body example
Error codes
If an error is returned when calling this API, look up the solution in the Global error codes documentation based on the error message.| Error code (errorcode) | Error description (errmsg) | Solution |
|---|---|---|
| -1 | System busy | Try again later |
| 40035 | Missing parameter json | Add the chat json |
| 43004 | Invalid HTTP HEADER Content-Type | Set the specific chat parameters |
| 400013 | The group has been disbanded | Send the chat to another group |
| 400101 | access_token does not exist | Verify that the access_token is spelled correctly |
| 400102 | The bot is disabled | Contact the admin to enable the bot |
| 400105 | Unsupported chat type | Use a chat type supported in the documentation |
| 400106 | The bot does not exist | Verify that the bot is in the group |
| 410100 | Rate limit triggered by sending too fast | Reduce the sending rate |
| 430101 | Contains an unsafe external link | Verify that the content sent is compliant |
| 430102 | Contains inappropriate text | Verify that the content sent is compliant |
| 430103 | Contains an inappropriate image | Verify that the content sent is compliant |
| 430104 | Contains inappropriate content | Verify that the content sent is compliant |
| Error code (errorcode) | Error description (errmsg) | Solution |
|---|---|---|
| 310000 | - keywords not in content - invalid timestamp - sign not match - ip X.X.X.X not in whitelist | - The chat content does not contain any keywords - The timestamp is invalid - The signature does not match - The IP address is not in the allowlist |