Developer GuideAPI call description
Before calling this API, make sure that you have configured and enabled a message template in the developer backend. For details, see Create and configure a message template.
- The maximum number of recipients per send is 1,000.
- The maximum number of recipients per minute is 5,000.
- Only one message with the same content can be sent to the same employee per day.
- Each employee can receive a maximum of 100 messages per day.
Request
| Basic information | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate |
| HTTP Method | POST |
| Supported app type | appType-Third-party enterprise app |
| Permissions | permission-qyapi_base-Basic permission required to call enterprise APIs |
Query parameter
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| access_token | String | Yes | Be3xxxx | The app credential for calling this API. Obtain it by calling the API for getting the access_token of a third-party enterprise. |
Request body
| Name | Type | Required | Example | Description |
|---|---|---|---|---|
| agent_id | Number | Yes | 948060598 | The agentid of the app. Call the API for getting enterprise authorization information to obtain it. |
| template_id | String | Yes | e27a9eed42b34a14a2xxxx | The message template ID. View it on the Development Management page of your app in the developer backend. |
| userid_list | String | No | ”123,456” | The list of recipient user IDs. The maximum list length is 5,000. |
| dept_id_list | String | No | 421897262 | The list of recipient department IDs. The maximum list length is 500. Important dept_id_list and userid_list cannot both be empty. |
| data | String | No | {"name":"Taobao 6","name2":"http://www.taobao.com"} | The values assigned to the dynamic parameters of the message template. Note Both key and value must be strings. |
Request example
curl -X POST "https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate" \
-H 'Content-Type:application/x-www-form-urlencoded;charset=utf-8' \
-d 'access_token=bdefeb04-96ad-40d9-bb92-a62a99d2e8d3' \
-d 'agent_id=123' \
-d 'data=%7B%5C%22Name%5C%22%3A%5C%22John%5C%22%7D' \
-d 'dept_id_list=%5C%22123%2C456%5C%22' \
-d 'template_id=xxxx' \
-d 'userid_list=%5C%22123%2C456%5C%22'
DingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate");
OapiMessageCorpconversationSendbytemplateRequest req = new OapiMessageCorpconversationSendbytemplateRequest();
req.setAgentId(948060598L);
req.setDeptIdList("421897262");
req.setUseridList("123,456");
req.setTemplateId("e27a9eed42b34a14a2xxxx");
req.setData("{\"name\":\"Taobao6\",\"name2\":\"http://www.taobao.com\"}");
OapiMessageCorpconversationSendbytemplateResponse rsp = client.execute(req, access_token);
System.out.println(rsp.getBody());
import dingtalk.api
req=dingtalk.api.OapiMessageCorpconversationSendbytemplateRequest("https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate")
req.agent_id=123
req.userid_list=""123,456""
req.dept_id_list=""123,456""
req.template_id="xxxx"
req.data="{\"Name\":\"John\"}"
try:
resp= req.getResponse(access_token)
print(resp)
except Exception,e:
print(e)
include "TopSdk.php";
date_default_timezone_set('Asia/Shanghai');
$c = new DingTalkClient(DingTalkConstant::$CALL_TYPE_OAPI, DingTalkConstant::$METHOD_POST , DingTalkConstant::$FORMAT_JSON);
$req = new OapiMessageCorpconversationSendbytemplateRequest;
$req->setAgentId("123");
$req->setUseridList("\"123,456\"");
$req->setDeptIdList("\"123,456\"");
$req->setTemplateId("xxxx");
$req->setData("{\"Name\":\"John\"}");
$resp = $c->execute($req, $access_token, "https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate");
IDingTalkClient client = new DefaultDingTalkClient("https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate");
OapiMessageCorpconversationSendbytemplateRequest req = new OapiMessageCorpconversationSendbytemplateRequest();
req.AgentId = 123L;
req.UseridList = "\"123,456\"";
req.DeptIdList = "\"123,456\"";
req.TemplateId = "xxxx";
req.Data = "{\"Name\":\"John\"}";
OapiMessageCorpconversationSendbytemplateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
Response
Response body
| Name | Type | Example | Description |
|---|---|---|---|
| errmsg | String | ok | The description of the return code. |
| errcode | Number | 0 | The return code. |
| task_id | Number | 282632271040 | The ID of the created async send task. |
| request_id | String | 52izpwz1p0iw | The request ID. |
Response body example
{
"errcode": 0,
"errmsg": "ok",
"task_id": 282632271040,
"request_id": "52izpwz1p0iw"
}
Error codes
If an error is returned when calling this API, find the solution in the Global error codes document based on the error message.| Error code (errorcode) | Error message description (errmsg) | Solution |
|---|---|---|
| 885001 | The message template does not exist. | Confirm whether the message template is correct. |
| 885006 | The message template is unavailable. | The message template must be approved first. |
| 400002 | Invalid agentId. | Confirm whether the agentId is correct. |
| 500 | System error. | An unknown system error occurred. |