API Dorongan Tunggal Batch

Batch Single Push API

Deskripsi Fungsi

Digunakan untuk mengirim pesan batch single push, memungkinkan beberapa pengguna target menerima push dalam satu kali panggilan. Mendukung pengiriman melalui registration_id atau alias:

Push via registration_id: POST /v4/batch/push/regid
Push via alias: POST /v4/batch/push/alias
Batasan Kapabilitas:
- Maksimal 500 target push per permintaan
- Mendukung pemrosesan paralel untuk efisiensi
- Mengembalikan hasil sebagian sukses jika terjadi rate limiting
- API ini dan Push API menggunakan kuota QPS yang sama. Batch push ke 1 regid/alias = konsumsi 1 kuota QPS Push API.

Autentikasi

Tambahkan field autentikasi pada HTTP Header:

Authorization: Basic ${base64_auth_string}

              
              Authorization: Basic ${base64_auth_string}

Tampilkan blok kode ini di jendela mengambang

Cara pembuatan: base64(username:password)
- username = AppKey aplikasi
- password = Master Secret
Akses path: Konsol → Pengaturan Aplikasi → Info Aplikasi

Endpoint

Batch push via registration_id

POST /v4/batch/push/regid

              
              POST /v4/batch/push/regid

Tampilkan blok kode ini di jendela mengambang

Batch push via alias

POST /v4/batch/push/alias

              
              POST /v4/batch/push/alias

Tampilkan blok kode ini di jendela mengambang

Contoh Permintaan

1. Batch push via registration_id

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "android", "notification": { "android": { "alert": "Hai, Push!", "title": "Kirim ke Android", "builder_id": 1, "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "ios", "notification": { "ios": { "alert": "Hai, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/regid \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "registration_id_1",  
        "platform": "android",  
        "notification": {  
          "android": {  
            "alert": "Hai, Push!",  
            "title": "Kirim ke Android",  
            "builder_id": 1,  
            "extras": { "newsid": 321 }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        },  
        "custom_args": { "business": "info" }  
      },  
      {  
        "target": "registration_id_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hai, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }'

Tampilkan blok kode ini di jendela mengambang

2. Batch push via alias

curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "AppKey:MasterSecret" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "all", "notification": { "android": { "alert": "Hai, Push!", "title": "Kirim ke Android" }, "ios": { "alert": "Hai, MTPush!", "sound": "default" } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "ios", "notification": { "ios": { "alert": "Hai, MTPush!", "sound": "default", "badge": "+1", "extras": { "newsid": 321 } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://pushapi-sgp.engagelab.com/v4/batch/push/alias \  
  -H "Content-Type: application/json" \  
  -u "AppKey:MasterSecret" \  
  -d '{  
    "requests": [  
      {  
        "target": "user_alias_1",  
        "platform": "all",  
        "notification": {  
          "android": { "alert": "Hai, Push!", "title": "Kirim ke Android" },  
          "ios": { "alert": "Hai, MTPush!", "sound": "default" }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      },  
      {  
        "target": "user_alias_2",  
        "platform": "ios",  
        "notification": {  
          "ios": {  
            "alert": "Hai, MTPush!",  
            "sound": "default",  
            "badge": "+1",  
            "extras": { "newsid": 321 }  
          }  
        },  
        "options": {  
          "time_to_live": 60,  
          "apns_production": false  
        }  
      }  
    ]  
  }'

Tampilkan blok kode ini di jendela mengambang

Parameter Permintaan

Struktur body permintaan:

{ "requests": [ { "target": "string", // Wajib, target push (registration_id atau alias) "platform": "string", // Wajib, platform push (android/ios/all) "notification": "object", // Opsional, konten notifikasi (lihat Push API) "message": "object", // Opsional, pesan kustom (lihat Push API), tidak bisa bersamaan dengan notification "options": "object", // Opsional, opsi push (lihat Push API) "custom_args": "object" // Opsional, parameter yang diteruskan ke klien } ] }

              
              {  
  "requests": [  
    {  
      "target": "string",     // Wajib, target push (registration_id atau alias)  
      "platform": "string",   // Wajib, platform push (android/ios/all)  
      "notification": "object",  // Opsional, konten notifikasi (lihat Push API)  
      "message": "object",     // Opsional, pesan kustom (lihat Push API), tidak bisa bersamaan dengan notification  
      "options": "object",     // Opsional, opsi push (lihat Push API)  
      "custom_args": "object"  // Opsional, parameter yang diteruskan ke klien  
    }  
  ]  
}

Tampilkan blok kode ini di jendela mengambang

Deskripsi parameter:

Field	Wajib	Tipe	Deskripsi
`requests`	Ya	array	Array permintaan batch (maksimal 500 item, `target` harus unik per batch)
`target`	Ya	string	Nilai target: - endpoint `/regid`: `registration_id` - endpoint `/alias`: `alias`
`platform`	Ya	string	Platform push: `android`, `ios`, atau `all`
`notification`	Tidak	object	Konten notifikasi (struktur sama dengan single push API)
`message`	Tidak	object	Pesan kustom (struktur sama dengan single push API)
`options`	Tidak	object	Opsi push (misal: `time_to_live`, `apns_production`)
`custom_args`	Tidak	object	Parameter passthrough kustom

Contoh Respons

Respons berhasil (semua sukses)

{ "results": { "registration_id_1": { "target": "registration_id_1", "success": true, "msg_id": 2460001 }, "registration_id_2": { "target": "registration_id_2", "success": true, "msg_id": 2460002 } } }

              
              {
  "results": {
    "registration_id_1": {
      "target": "registration_id_1",
      "success": true,
      "msg_id": 2460001
    },
    "registration_id_2": {
      "target": "registration_id_2",
      "success": true,
      "msg_id": 2460002
    }
  }
}

Tampilkan blok kode ini di jendela mengambang

Respons berhasil (sebagian rate limiting)

{ "rate_limit_info": { "message": "Beberapa permintaan terkena pembatasan laju selama pemrosesan batch", "rate_limit_occurred": true }, "results": { "170976fa8a0771c2647": { "target": "170976fa8a0771c2647", "success": false, "error": { "code": 23008, "message": "Batas laju API terlampaui" } }, "170976fa8a9277c25d4": { "target": "170976fa8a9277c25d4", "success": false, "error": { "code": 23008, "message": "Batas laju API terlampaui" } } } }

              
              {
    "rate_limit_info": {
        "message": "Beberapa permintaan terkena pembatasan laju selama pemrosesan batch",
        "rate_limit_occurred": true
    },
    "results": {
        "170976fa8a0771c2647": {
            "target": "170976fa8a0771c2647",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Batas laju API terlampaui"
            }
        },
        "170976fa8a9277c25d4": {
            "target": "170976fa8a9277c25d4",
            "success": false,
            "error": {
                "code": 23008,
                "message": "Batas laju API terlampaui"
            }
        }
    }
}

Tampilkan blok kode ini di jendela mengambang

Respons gagal (kesalahan global)

{ "error": { "code": 21004, "message": "autentikasi dasar gagal" } }

              
              {  
  "error": {  
    "code": 21004,  
    "message": "autentikasi dasar gagal"  
  }  
}

Tampilkan blok kode ini di jendela mengambang

Respons gagal (kesalahan parameter)

{ "error": { "code": 21003, "message": "Nilai parameter tidak valid" } }

              
              {  
  "error": {  
    "code": 21003,  
    "message": "Nilai parameter tidak valid"  
  }  
}

Tampilkan blok kode ini di jendela mengambang

Referensi Kode Error

Kode Error	Deskripsi	Solusi	HTTP Status
Kode Error Global
21004	Autentikasi dasar gagal	Periksa AppKey/MasterSecret	401
21008	Panjang AppKey bukan 24 karakter	Verifikasi format AppKey	400
21038	Tidak ada izin push untuk aplikasi	Periksa konfigurasi aplikasi	400
21043	Tidak ada izin push (menunggu pembayaran)	Selesaikan masalah penagihan	400
23009	IP tidak ada di allowlist	Tambahkan IP server ke allowlist	400
21009	Kesalahan sistem internal (jangan retry)	Hubungi dukungan teknis	400
Error Pembatasan Laju
23008	Batas laju API tercapai	Ulangi item yang gagal jika sebagian sukses	400
Error Parameter
21003	Nilai parameter tidak valid	Periksa format body permintaan	400
21015	Parameter permintaan tidak valid	Validasi field yang wajib	400
21016	Validasi parameter gagal	Periksa tipe field dan rentang nilai	400

Daftar kode error lengkap: Create Push API - Response

Catatan

Penanganan Rate Limit: Jika terjadi pembatasan laju, hasil sukses sebagian dikembalikan (msg_id untuk yang berhasil + error untuk yang gagal).
Pengecekan Duplikat: Semua nilai target atau cid harus unik dalam satu batch.
Batas Jumlah: Maksimal 500 target per permintaan.
Penanganan Error: Error global (misal: autentikasi gagal) langsung menghentikan proses tanpa hasil sebagian.