API Tugas Terjadwal
Lapisan API mendukung fitur penjadwalan tugas, dengan objek Schedule yang memungkinkan eksekusi tugas secara mandiri.
Catatan: Tugas terjadwal yang dibuat melalui API hanya dapat diambil, diubah, atau dihapus melalui API.
Autentikasi
Lihat metode autentikasi pada ringkasan REST API untuk detailnya.
Penjelasan Parameter Schedule
Setiap tugas terjadwal terdiri dari empat bagian: name, enabled, trigger, dan push.
| Parameter | Tipe | Opsional | Deskripsi |
|---|---|---|---|
| name | String | Tidak | Nama tugas terjadwal, maksimal 255 byte, boleh huruf, angka, garis bawah, dan karakter Tionghoa. |
| enabled | Boolean | Tidak | Status tugas saat ini; harus true saat membuat tugas. |
| trigger | JSON Object | Tidak | Kondisi pemicu dan waktu tugas terjadwal. Mendukung sekali jalan (single), berkala (periodical), dan Pengiriman Cerdas (intelligent). Lihat penjelasan single untuk detailnya. |
| push | JSON Object | Tidak | Konten push, lihat field pada dokumentasi app push. |
Penjelasan Single
Kondisi pemicu tugas terjadwal, termasuk waktu pemicu dan tipe tugas.
| Parameter | Tipe | Opsional | Deskripsi |
|---|---|---|---|
| time | String | Tidak | Waktu pemicu, format "yyyy-mm-dd hh:mm:ss", misal "2014-02-15 13:16:59". Format tidak lengkap tidak diterima. Waktu tugas tidak boleh lebih dari satu tahun ke depan. |
| zone_type | Int | Tidak | Jenis zona waktu: 1 untuk zona waktu server, 2 untuk zona waktu pengguna. |
Penjelasan Periodical
| Parameter | Tipe | Opsional | Deskripsi |
|---|---|---|---|
| start | String | Tidak | Waktu mulai efektif, format "yyyy-MM-dd HH:mm:ss", wajib jam 24. |
| end | String | Tidak | Waktu berakhir, format sama seperti start. Maksimal rentang satu tahun. |
| time | String | Tidak | Waktu spesifik pemicu, format "HH:mm:ss", wajib jam 24. |
| time_unit | String | Tidak | Satuan waktu terkecil: "day", "week", atau "month". Tidak case sensitive. |
| point | String | Tidak | Daftar sesuai time_unit, lihat tabel di bawah. |
| zone_type | Int | Tidak | Jenis zona waktu: 1 server, 2 pengguna. |
Detail parameter point:
| time_unit | point | Deskripsi |
|---|---|---|
| day | NULL | Untuk day, point tidak berlaku. |
| week | "MON","TUE","WED","THU","FRI","SAT","SUN" | Untuk week, point bisa satu atau beberapa hari, tidak case sensitive. |
| month | "01"..."31" | Untuk month, point sesuai tanggal valid, tanggal tidak valid tidak akan dipicu. |
Penjelasan Intelligent
| Parameter | Tipe | Wajib/Opsional | Makna |
|---|---|---|---|
| backup_time | String | Wajib | Pengiriman cerdas adalah fitur unik EngageLab untuk mengoptimalkan rasio klik notifikasi. Setiap kali pengguna mengakses layanan Anda melalui website atau aplikasi mobile dengan SDK EngageLab, waktu aktif terakhir pengguna akan dilacak. Sistem akan mengirim notifikasi pada waktu optimal sesuai zona waktu pengguna. Untuk pengguna tanpa data aktif, Anda bisa memilih kirim segera (now) atau tentukan waktu pengiriman (format "yyyy-MM-dd HH:mm:ss", 24 jam). |
Membuat Tugas Terjadwal
Endpoint
POST v4/schedules
Batasan
- Jumlah tugas terjadwal aktif (belum expired) dibatasi 1000. Jika melebihi, pembuatan gagal.
- Tidak ada batasan rentang maksimal, namun disarankan tidak lebih dari 1 tahun.
- Nama tugas maksimal 255 karakter, hanya angka, huruf, garis bawah, dan karakter Tionghoa.
Contoh Permintaan
Header Permintaan
POST /v4/schedules
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Body Permintaan
Contoh tugas terjadwal single
{
"name":"Contoh Push Terjadwal_single",
"enabled":true,
"trigger":{
"single":{
"time":"2022-11-23 19:20:00",
"zone_type":1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"Tugas terjadwal dari API",
"android":{
"title":"Tugas terjadwal dari API",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
Contoh tugas terjadwal periodical
{
"name":"Contoh Push Terjadwal_periodical",
"enabled":true,
"trigger":{
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"tugas periodik berulang",
"android":{
"title":"tugas periodik berulang",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"67890",
"custom_args":{
"Engagelab": "push to you"
}
}
}
Contoh pengiriman cerdas
{
"name":"Pengiriman Cerdas",
"enabled":true,
"trigger":{
"intelligent": {
"backup_time":"2024-01-01 00:00:00"
}
} ,
"push":{
"from":"push",
"to":{
"registration_id":[
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body":{
"platform":"android",
"notification":{
"alert":"Tugas terjadwal dari API",
"android":{
"title":"Tugas terjadwal dari API",
"extras":{
"key1":"value1"
}
}
},
"options":{
"time_to_live":60
}
},
"request_id":"12345",
"custom_args":{
"Engagelab": "push to you"
}
}
}
Penjelasan Data Permintaan
zone_typewajib diisi (1 atau 2); jika tidak, push mengikuti zona waktu server.- Saat membuat tugas pertama kali,
enabledharus true. Jika false, pembuatan gagal. pushharus aksi push yang valid; jika tidak, pembuatan gagal.
Contoh Respons
Respons Berhasil
HTTP/1.1 200 OK
Content-Type: application/json
{
"schedule_id": "a9b85590-6cec-4f91-b277-2d82b0e20ef6",
"name": "Nama Tugas Terjadwal"
}
Respons Gagal
HTTP/1.1 400 BAD REQUEST
Content-Type: application/json; charset=utf-8
{
"error": {
"code": 28400,
"message": "pesan error"
}
}
Mendapatkan Daftar Tugas Terjadwal yang Berlaku
- Mendapatkan daftar schedule yang masih aktif (belum expired).
Endpoint
GET v4/schedules?page=
Contoh Permintaan
Header Permintaan
GET /v4/schedules?page=
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
- Daftar tugas terjadwal untuk halaman yang diminta akan dikembalikan. Jika tidak ada halaman, default ke halaman 1.
- Urutan berdasarkan waktu pembuatan.
- Jika nomor halaman melebihi total halaman,
pagetetap nilai diminta,scheduleskosong. - Maksimal 50 tugas per halaman.
Contoh Respons
Respons Berhasil
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
{
"total_count": 1000,
"total_pages": 5,
"page": 4,
"schedules": [
{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "",
"enabled": true
},
{} // Daftar detail informasi.
]
}
- Menunjukkan total 1000 tugas terjadwal, 5 halaman, halaman saat ini 4, berisi 50 tugas.
schedulesadalah daftar detail tugas terjadwal.
Mendapatkan Detail Tugas Terjadwal
- Mendapatkan detail tugas terjadwal berdasarkan id
{schedule_id}.
Endpoint
GET v4/schedules/{schedule_id}
Contoh Permintaan
Header Permintaan
GET /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Contoh Respons
Respons Berhasil
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Data Respons
[{
"schedule_id": "0eac1b80-c2ac-4b69-948b-c65b34b96512",
"name": "Contoh Push Terjadwal",
"enabled": true,
"trigger": {...},
"push": {...}
}]
Mendapatkan Semua ID Pesan dari Tugas Terjadwal
- Mengambil daftar semua ID pesan untuk tugas terjadwal
{schedule_id}.
Endpoint
GET v4/schedules/{schedule_id}/msg-ids
Contoh Permintaan
Header Permintaan
GET /v4/schedules/{schedule_id}/msg-ids
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Contoh Respons
Respons Berhasil
HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
Data Respons
- Format data balikan setelah fitur periodical online (22 Februari 2024), gunakan MsgIds.
- Field ts adalah timestamp eksekusi, akurat milidetik.
{
"count": 1,
"MsgIds": [
"{\"msg_id\":\"1088009\",\"error\":{\"code\":0,\"message\":\"\"},\"needRetry\":false,\"ts\":1707278411611}",
"{\"msg_id\":\"0\",\"error\":{\"code\":1011,\"message\":\"Tidak dapat menemukan target pengiriman\"},\"needRetry\":false,\"ts\":1707278411611}"
]
}
Memperbarui Tugas Terjadwal
- Update tugas terjadwal berdasarkan id.
Endpoint
PUT v4/schedules/{schedule_id}
Contoh Permintaan
Header Permintaan
PUT /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/x-www-form-urlencoded
Accept: application/json
Body Permintaan
{
"name": "tugas",
"enabled": true,
"trigger": {...},
"push": {...}
}
Catatan:
- Tugas terjadwal yang sudah expired tidak bisa diupdate.
- Tugas dengan zona waktu pengguna tidak bisa diubah ke zona waktu server dan sebaliknya.
- Update harus menyertakan semua subfield terkait di bawah
push. Update parsial tidak didukung.
Contoh Update Salah
// SALAH: Hanya update platform ke iOS:
{
"push": {
"body": {
"platform": "ios"
}
}
}
// SALAH: Hanya update tanggal akhir:
{
"trigger": {
"periodical": {
"end": "2024-03-10 00:00:00"
}
}
}
Contoh Update Benar
// BENAR: Update platform ke iOS:
{
"name": "Contoh Push Terjadwal",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform":"ios",
"notification":{
"alert":"Tugas Terjadwal Terminal API",
"ios":{
"alert": {
"title": "halo",
"body": "selamat datang"
},
"extras":{
"key1":"value1"
}
}
},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
// BENAR: Perpanjang tanggal akhir trigger periodical satu bulan:
{
"name": "Contoh Push Terjadwal",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-03-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "android",
"notification": {
"alert": "Tugas terjadwal terminal API",
"android": {
"title": "Tugas terjadwal terminal API",
"extras": {
"key1": "value1"
}
}
},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Pastikan push tetap valid dan efektif; jika tidak, update akan gagal. Selalu kirimkan struktur lengkap saat update untuk menghindari kegagalan akibat update parsial.
Contoh Respons
Respons Berhasil
HTTP/1.0 200 CREATED
Content-Type: application/json
{
"name": "Contoh Push Periodik",
"enabled": true,
"trigger": {
"periodical": {
"start": "2024-01-01 00:00:00",
"end": "2024-02-10 00:00:00",
"time": "12:00:00",
"time_unit": "day",
"point": [],
"zone_type": 1
}
},
"push": {
"from": "push",
"to": {
"registration_id": [
"1a0018970ab49abda3e",
"100d85590955c1d2793"
]
},
"body": {
"platform": "ios",
"notification": {
"alert": "Tugas terjadwal terminal API",
"ios": {
"alert": {
"title": "halo",
"body": "selamat datang"
},
"extras": {
"key1": "value1"
}
}
},
"options": {
"time_to_live": 60
}
},
"request_id": "12345",
"custom_args": {
"Engagelab": "push to you"
}
}
}
Data Respons
{
"name": "Contoh Push Terjadwal",
"enabled": true,
"trigger": {...},
"push": {...}
}
Respons Gagal
- Jika
schedule_idtidak valid atau bukan id yang sah:
HTTP/1.0 404 Not Found
Content-Type: application/json
- Jika operasi update tidak valid:
HTTP/1.0 400 BAD REQUEST
Content-Type: application/json
Menghapus Tugas Terjadwal
Endpoint
DELETE v4/schedules/{schedule_id}
schedule_idadalah id tugas terjadwal yang ada. Jika tidak valid, hasilnya error 404.
Contoh Permintaan
DELETE /v4/schedules/{schedule_id}
Authorization: Basic (base64 auth string)
Content-Type: application/json
Accept: application/json
Contoh Respons
Respons Berhasil
HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 0
Respons Gagal
HTTP/1.0 404 Not Found
Content-Type: application/json
Content-Length: 0
{
"error": {
"code": 28404,
"message": "pesan error"
}
}
Kode Error
| Kode | HTTP | Deskripsi | Pesan Error | Penjelasan Detail |
|---|---|---|---|---|
| 28000 | 200 | Return Benar | - | Kode status sukses |
| 28100 | 400 | Parameter Tidak Valid | Tugas terjadwal tidak valid: bagian tidak valid; sudah berakhir; kadaluarsa; data permintaan bukan JSON; update target task; hapus target task; permintaan schedule tidak ada | |
| 28101 | 401 | Autentikasi Gagal | Autentikasi Basic gagal. | appkey dan masterscrect tidak cocok. |
| 28102 | 400 | Parameter Push Tidak Valid | push param kosong atau tidak valid | Parameter push tidak valid, informasi error spesifik dikembalikan. |
| 28103 | 400 | Parameter Waktu Push Tidak Valid | single time atau format waktu trigger salah | Parameter waktu push tidak valid, informasi error spesifik dikembalikan. |
| 28104 | 404 | Tugas Terjadwal yang Diminta Tidak Ada | Operasi schedule yang diminta tidak ada | Tugas terkait sudah dikirim, atau schedule ID salah. |
| 28105 | 404 | Tidak Ada Target Push untuk Waktu yang Ditetapkan | Tugas push tidak valid. Tidak ada target push untuk waktu yang dijadwalkan | Parameter waktu push salah. |
| 28200 | 500 | Kesalahan Internal Server | Kesalahan internal server. | Terjadi error tak terduga. |
| 28203 | 503 | Kesalahan Internal Server, Silakan Coba Lagi Nanti | Timeout eksekusi aksi, silakan coba lagi nanti | Error komunikasi dengan schedule-server. |










