> ## Documentation Index
> Fetch the complete documentation index at: https://help.dingtalk.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Send a work notification with a template

> Call this API to send a Work Notification using a message template, covering request parameters and the response structure.

Call this API to send a work notification using a message template.

## API call description

<Warning>
  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.
</Warning>

* 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](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](https://open-dev.dingtalk.io/#/isveapp). |
| 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 theme={"theme":{"light":"github-light","dark":"github-dark"}}
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'
```

Java

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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());
```

Python

```python theme={"theme":{"light":"github-light","dark":"github-dark"}}
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)
```

PHP

```php theme={"theme":{"light":"github-light","dark":"github-dark"}}
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");
```

C#

```text theme={"theme":{"light":"github-light","dark":"github-dark"}}
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

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "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](/open/development/server-api-error-codes-1) 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.                |