Skip to main content
Call this API to send group chats using a custom bot.

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 timestamp and sign parameters when calling this API. Example:
    https://oapi.dingtalk.io/robot/send?access_token=XXXXXX&timestamp=XXX&sign=XXX
    
  • 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 URLhttps://oapi.dingtalk.io/robot/send
HTTP MethodPOST
Supported app typesappType-Internal app appType-Third-party enterprise app
Required permissionspermission-qyapi_base-Basic permission to call enterprise APIs

Query parameters

NameTypeRequiredExampleDescription
access_tokenStringYesBE3xxxxThe 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

NameTypeRequiredExampleDescription
msgtypeStringYestextThe chat type. For chat types supported by custom bots, see Chat types supported by custom bots.
msgUuidStringNo123The 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.
textObjectNoA text chat.
contentStringNoDingTalk makes progress happenThe content of the text chat.
atObjectNoInformation about the group members mentioned with @.
isAtAllBooleanNofalseWhether to mention @Everyone. - true: Yes - false: No
atMobilesString[]No[“15xxx,18xxx”]The mobile numbers of the group members to mention with @.
atUserIdsString[]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.
linkObjectNoA link chat.
messageUrlStringNohttps://www.dingtalk.ioThe URL to redirect to when the chat is tapped.
titleStringNoThis is the titleThe title of the link chat.
picUrlStringNo@aubHxxxxxThe image URL in the link chat. We recommend using the Upload media files API to obtain it.
textStringNoThe content of the link chatThe content of the link chat.
markdownObjectNoA markdown chat.
textStringNomarkdown chat contentThe text content of the markdown chat.
titleStringNoThe title shown in the chat listThe title shown in the chat list, not the title of the chat body.
actionCardObjectNoAn actionCard chat.
hideAvatarStringNo1Whether to display the profile photo of the sender. - 0: Display the sender’s profile photo - 1: Hide the sender’s profile photo
btnOrientationStringNo1The button layout in the chat. - 0: Buttons arranged vertically - 1: Buttons arranged horizontally
singleURLStringNohttps://www.dingtalk.ioThe URL triggered when the singleTitle button is tapped. Note Required when the chat contains only one button.
singleTitleStringNoThis is a buttonThe single-button option. (When this and singleURL are set, btns does not take effect.) Note Required when the chat contains only one button.
textStringNoChat contentThe body content of the actionCard chat. Markdown syntax is supported.
titleStringNoThe title shown in the chat listThe title shown in the chat list, not the title of the chat body.
btnsObject[]NoThe list of button information. Note Required when the chat contains more than one button.
actionURLStringNohttps://www.dingtalk.ioThe URL the button redirects to.
titleStringNoThis is a buttonThe text displayed on the button.
feedCardObjectNoA feedCard chat.
linksObject[]NoThe content list of the feedCard chat.
picURLStringNo@aubHxxxxxThe image URL for each item in the feedCard chat. We recommend using the Upload media files API to obtain it.
messageURLStringNohttps://www.dingtalk.ioThe redirect URL for each item in the feedCard chat.
titleStringNoChat titleThe title of each item in the feedCard chat.

Request example

curl -X POST "https://oapi.dingtalk.io/robot/send" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=c370586xxxxd65d506' \
-d 'actionCard=null' \
-d 'at=null' \
-d 'feedCard=null' \
-d 'link=null' \
-d 'markdown=null' \
-d 'msgtype=text' \
-d 'text=null'
Java
DingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/robot/send");
OapiRobotSendRequest req = new OapiRobotSendRequest();
req.setMsgtype("text");
Text obj1 = new Text();
obj1.setContent("123");
req.setText(obj1);
At obj2 = new At();
obj2.setIsAtAll(false);
obj2.setAtMobiles("");
obj2.setAtUserIds("");
req.setAt(obj2);
Link obj3 = new Link();
obj3.setMessageUrl("1");
obj3.setTitle("1");
obj3.setPicUrl("1");
obj3.setText("1");
req.setLink(obj3);
Markdown obj4 = new Markdown();
obj4.setText("1");
obj4.setTitle("1");
req.setMarkdown(obj4);
Actioncard obj5 = new Actioncard();
obj5.setHideAvatar("1");
obj5.setBtnOrientation("1");
obj5.setSingleURL("1");
obj5.setSingleTitle("1");
obj5.setText("1");
obj5.setTitle("1");
List<Btns> list7 = new ArrayList<Btns>();
Btns obj8 = new Btns();
list7.add(obj8);
obj8.setActionURL("1");
obj8.setTitle("1");
obj5.setBtns(list7);
req.setActionCard(obj5);
Feedcard obj9 = new Feedcard();
List<Links> list11 = new ArrayList<Links>();
Links obj12 = new Links();
list11.add(obj12);
obj12.setPicURL("1");
obj12.setMessageURL("1");
obj12.setTitle("1");
obj9.setLinks(list11);
req.setFeedCard(obj9);
OapiRobotSendResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
Python
# -*- coding: utf-8 -*-
import dingtalk.api

req=dingtalk.api.OapiRobotSendRequest("https://oapi.dingtalk.io/robot/send")

req.msgtype="text"
req.text=""
req.at=""
req.link=""
req.markdown=""
req.actionCard=""
req.feedCard=""
try:
	resp= req.getResponse(access_token)
	print(resp)
except Exception,e:
	print(e)
PHP
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');

$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiRobotSendRequest;
$req->setMsgtype("text");
$text = new Text;
$text->content="123";
$req->setText($text);
$at = new At;
$at->isAtAll="false";
$at->atMobiles="[]";
$at->atUserIds="[]";
$req->setAt($at);
$link = new Link;
$link->messageUrl="1";
$link->title="1";
$link->picUrl="1";
$link->text="1";
$req->setLink($link);
$markdown = new Markdown;
$markdown->text="1";
$markdown->title="1";
$req->setMarkdown($markdown);
$actionCard = new Actioncard;
$actionCard->hideAvatar="1";
$actionCard->btnOrientation="1";
$actionCard->singleURL="1";
$actionCard->singleTitle="1";
$actionCard->text="1";
$actionCard->title="1";
$btns = new Btns;
$btns->actionURL="1";
$btns->title="1";
$actionCard->btns = array($btns);
$req->setActionCard($actionCard);
$feedCard = new Feedcard;
$links = new Links;
$links->picURL="1";
$links->messageURL="1";
$links->title="1";
$feedCard->links = array($links);
$req->setFeedCard($feedCard);
$resp = $c->execute($req, $access_token, "https://oapi.dingtalk.io/robot/send");
C#
IDingTalkClient client = new DefaultDingTalkClient("https://oapi.dingtalk.io/robot/send");
OapiRobotSendRequest req = new OapiRobotSendRequest();
req.Msgtype = "text";
OapiRobotSendRequest.TextDomain obj1 = new OapiRobotSendRequest.TextDomain();
obj1.Content = "123";
req.Text_ = obj1;
OapiRobotSendRequest.AtDomain obj2 = new OapiRobotSendRequest.AtDomain();
obj2.IsAtAll = false;
obj2.AtMobiles = "";
obj2.AtUserIds = "";
req.At_ = obj2;
OapiRobotSendRequest.LinkDomain obj3 = new OapiRobotSendRequest.LinkDomain();
obj3.MessageUrl = "1";
obj3.Title = "1";
obj3.PicUrl = "1";
obj3.Text = "1";
req.Link_ = obj3;
OapiRobotSendRequest.MarkdownDomain obj4 = new OapiRobotSendRequest.MarkdownDomain();
obj4.Text = "1";
obj4.Title = "1";
req.Markdown_ = obj4;
OapiRobotSendRequest.ActioncardDomain obj5 = new OapiRobotSendRequest.ActioncardDomain();
obj5.HideAvatar = "1";
obj5.BtnOrientation = "1";
obj5.SingleURL = "1";
obj5.SingleTitle = "1";
obj5.Text = "1";
obj5.Title = "1";
List<OapiRobotSendRequest.BtnsDomain> list7 = new List<OapiRobotSendRequest.BtnsDomain>();
OapiRobotSendRequest.BtnsDomain obj8 = new OapiRobotSendRequest.BtnsDomain();
list7.Add(obj8);
obj8.ActionURL = "1";
obj8.Title = "1";
obj5.Btns= list7;
req.ActionCard_ = obj5;
OapiRobotSendRequest.FeedcardDomain obj9 = new OapiRobotSendRequest.FeedcardDomain();
List<OapiRobotSendRequest.LinksDomain> list11 = new List<OapiRobotSendRequest.LinksDomain>();
OapiRobotSendRequest.LinksDomain obj12 = new OapiRobotSendRequest.LinksDomain();
list11.Add(obj12);
obj12.PicURL = "1";
obj12.MessageURL = "1";
obj12.Title = "1";
obj9.Links= list11;
req.FeedCard_ = obj9;
OapiRobotSendResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);

Response

Response body

NameTypeExampleDescription
errmsgStringokThe error code description.
errcodeNumber0The error code.

Response body example

{
  "errcode":"0",
  "errmsg":"ok"
}

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
-1System busyTry again later
40035Missing parameter jsonAdd the chat json
43004Invalid HTTP HEADER Content-TypeSet the specific chat parameters
400013The group has been disbandedSend the chat to another group
400101access_token does not existVerify that the access_token is spelled correctly
400102The bot is disabledContact the admin to enable the bot
400105Unsupported chat typeUse a chat type supported in the documentation
400106The bot does not existVerify that the bot is in the group
410100Rate limit triggered by sending too fastReduce the sending rate
430101Contains an unsafe external linkVerify that the content sent is compliant
430102Contains inappropriate textVerify that the content sent is compliant
430103Contains an inappropriate imageVerify that the content sent is compliant
430104Contains inappropriate contentVerify that the content sent is compliant
When the following errors occur, the chat failed validation. Check the bot’s security settings.
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