API 呼び出し説明
本 API を呼び出す前に、開発者管理画面でチャットテンプレートを設定し、有効化していることを確認してください。詳細はチャットテンプレートの作成と設定をご参照ください。
- 1 回あたりの送信人数は最大 1000 人です。
- 1 分間あたりの受信人数は最大 5000 人です。
- 同一社員に対して、毎日同じ内容のチャットを 1 通のみ送信できます。
- 各社員に対して、毎日最大 100 通まで送信できます。
リクエスト
| 基本情報 | |
|---|---|
| HTTP URL | https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate |
| HTTP Method | POST |
| 対応アプリタイプ | appType-サードパーティ社内アプリ |
| 権限要件 | permission-qyapi_base-企業 API を呼び出す際に必要な基本権限 |
クエリパラメータ
| 名前 | タイプ | 必須 | 例 | 説明 |
|---|---|---|---|---|
| access_token | String | はい | Be3xxxx | 本 API を呼び出すためのアプリ認証情報。サードパーティ企業の access_token を取得する API から取得します。 |
リクエストボディ
| 名前 | タイプ | 必須 | 例 | 説明 |
|---|---|---|---|---|
| agent_id | Number | はい | 948060598 | アプリの agentid。企業の権限付与情報を取得する API を呼び出して取得します。 |
| template_id | String | はい | e27a9eed42b34a14a2xxxx | チャットテンプレート ID。開発者管理画面のアプリの 開発管理 ページで確認できます。 |
| userid_list | String | いいえ | ”123,456” | 受信者のユーザー ID リスト。リストの最大長は 5000 です。 |
| dept_id_list | String | いいえ | 421897262 | 受信者の部門 id リスト。リストの最大長は 500 です。 重要 dept_id_list と userid_list を同時に空にすることはできません。 |
| data | String | いいえ | {"name":"サンプル 6","name2":"http://www.taobao.com"} | チャットテンプレートの動的パラメータ代入データ。説明 key と value はいずれも文字列形式です。 |
リクエスト例
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%22%E5%90%8D%E5%89%8D%5C%22%3A%5C%22%E5%B1%B1%E7%94%B0%E5%A4%AA%E9%83%8E%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\":\"サンプル6\",\"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="{\"名前\":\"山田太郎\"}"
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("{\"名前\":\"山田太郎\"}");
$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 = "{\"名前\":\"山田太郎\"}";
OapiMessageCorpconversationSendbytemplateResponse rsp = client.Execute(req, access_token);
Console.WriteLine(rsp.Body);
レスポンス
レスポンスボディ
| 名前 | タイプ | 例 | 説明 |
|---|---|---|---|
| errmsg | String | ok | 戻りコードの説明。 |
| errcode | Number | 0 | 戻りコード。 |
| task_id | Number | 282632271040 | 作成された非同期送信タスク ID。 |
| request_id | String | 52izpwz1p0iw | リクエスト ID。 |
レスポンスボディの例
{
"errcode": 0,
"errmsg": "ok",
"task_id": 282632271040,
"request_id": "52izpwz1p0iw"
}
エラーコード
本 API の呼び出し時にエラーが発生した場合、エラーメッセージをもとにグローバルエラーコードドキュメントから解決方法を検索できます。| エラーコード(errorcode) | エラーメッセージの説明(errmsg) | 解決方法 |
|---|---|---|
| 885001 | チャットテンプレートが存在しません | チャットテンプレートが正しいか確認してください |
| 885006 | チャットテンプレートが利用できません | チャットテンプレートは事前に承認を通過させる必要があります |
| 400002 | agentId が不正です | agentId が正しいか確認してください |
| 500 | システムエラー | 不明なシステムエラーが発生しました |