Panduan pengembangDeskripsi panggilan API
Sebelum memanggil API ini, pastikan Anda telah mengonfigurasi dan mengaktifkan templat pesan di backend developer. Untuk detailnya, lihat Buat dan konfigurasikan templat pesan.
- Jumlah maksimum penerima per pengiriman adalah 1.000.
- Jumlah maksimum penerima per menit adalah 5.000.
- Hanya satu pesan dengan konten yang sama yang dapat dikirim ke karyawan yang sama per hari.
- Setiap karyawan dapat menerima maksimum 100 pesan per hari.
Permintaan
| Informasi dasar | |
|---|---|
| URL HTTP | https://api.dingtalk.io/topapi/message/corpconversation/sendbytemplate |
| Metode HTTP | POST |
| Jenis aplikasi yang didukung | appType-Aplikasi perusahaan pihak ketiga |
| Izin | permission-qyapi_base-Izin dasar yang diperlukan untuk memanggil API perusahaan |
Parameter kueri
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| access_token | String | Ya | Be3xxxx | Kredensial aplikasi untuk memanggil API ini. Dapatkan dengan memanggil API untuk memperoleh access_token dari perusahaan pihak ketiga. |
Isi permintaan
| Nama | Tipe | Wajib | Contoh | Deskripsi |
|---|---|---|---|---|
| agent_id | Number | Ya | 948060598 | agentid dari aplikasi. Panggil API untuk memperoleh informasi otorisasi perusahaan untuk mendapatkannya. |
| template_id | String | Ya | e27a9eed42b34a14a2xxxx | ID templat pesan. Lihat di halaman Development Management aplikasi Anda di backend developer. |
| userid_list | String | Tidak | ”123,456” | Daftar ID pengguna penerima. Panjang maksimum daftar adalah 5.000. |
| dept_id_list | String | Tidak | 421897262 | Daftar ID departemen penerima. Panjang maksimum daftar adalah 500. Penting dept_id_list dan userid_list tidak boleh keduanya kosong. |
| data | String | Tidak | {"name":"Taobao 6","name2":"http://www.taobao.com"} | Nilai yang diberikan ke parameter dinamis templat pesan. Catatan Baik key maupun value harus berupa string. |
Contoh permintaan
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);
Respons
Isi respons
| Nama | Tipe | Contoh | Deskripsi |
|---|---|---|---|
| errmsg | String | ok | Deskripsi kode pengembalian. |
| errcode | Number | 0 | Kode pengembalian. |
| task_id | Number | 282632271040 | ID tugas pengiriman async yang dibuat. |
| request_id | String | 52izpwz1p0iw | ID permintaan. |
Contoh isi respons
{
"errcode": 0,
"errmsg": "ok",
"task_id": 282632271040,
"request_id": "52izpwz1p0iw"
}
Kode error
Jika error dikembalikan saat memanggil API ini, temukan solusinya di dokumen Kode error global berdasarkan pesan error.| Kode error (errorcode) | Deskripsi pesan error (errmsg) | Solusi |
|---|---|---|
| 885001 | Templat pesan tidak ada. | Konfirmasi apakah templat pesan sudah benar. |
| 885006 | Templat pesan tidak tersedia. | Templat pesan harus disetujui terlebih dahulu. |
| 400002 | agentId tidak valid. | Konfirmasi apakah agentId sudah benar. |
| 500 | Error sistem. | Terjadi error sistem yang tidak diketahui. |