API Dorongan Tunggal Batch

Batch Single Push API

Deskripsi Fungsi

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

Push melalui registration_id: POST /v4/batch/push/regid
Push melalui alias: POST /v4/batch/push/alias
Batasan Kapabilitas:
- Maksimal 500 target push per permintaan
- Mendukung pemrosesan paralel untuk efisiensi
- Mengembalikan hasil sebagian sukses saat 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: 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://webpushapi-sgp.engagelab.com/v4/batch/push/regid \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "registration_id_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false }, "custom_args": { "business": "info" } }, { "target": "registration_id_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/regid \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "registration_id_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
                "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        },
        "custom_args": {
          "business": "info"
        }
      },
      {
        "target": "registration_id_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
                "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "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://webpushapi-sgp.engagelab.com/v4/batch/push/alias \ -H "Content-Type: application/json" \ -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \ -d '{ "requests": [ { "target": "user_alias_1", "platform": "web", "notification": { "alert": "Hi,Push !", "web": { "alert": "Hi,Push !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } }, { "target": "user_alias_2", "platform": "web", "notification": { "alert": "Hi,MTPush !", "web": { "alert": "Hi,MTPush !", "title": "web_push", "url": "http://www.google.com", "extras": { "web-key1": "web-value1" } } }, "options": { "time_to_live": 60, "apns_production": false } } ] }'

              
              curl --insecure -X POST -v https://webpushapi-sgp.engagelab.com/v4/batch/push/alias \
  -H "Content-Type: application/json" \
  -u "c96f42e0d2e662e45d035ab1:df4d59e84eac2f9d53b36f12" \
  -d '{
    "requests": [
      {
        "target": "user_alias_1",
        "platform": "web",
        "notification": {
            "alert": "Hi,Push !",
            "web": {
              "alert": "Hi,Push !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "options": {
          "time_to_live": 60,
          "apns_production": false
        }
      },
      {
        "target": "user_alias_2",
        "platform": "web",
        "notification": {
            "alert": "Hi,MTPush !",
            "web": {
              "alert": "Hi,MTPush !",
                "title": "web_push",
                "url": "http://www.google.com",
                "extras": {
                    "web-key1": "web-value1"
                }
            }
        },
        "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, pengaturan platform push (lihat Push API) "notification": "object", // Opsional, konten notifikasi (lihat Push API) "message": "object", // Opsional, pesan kustom (lihat Push API), tidak dapat 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, pengaturan platform push (lihat Push API)
      "notification": "object",  // Opsional, konten notifikasi (lihat Push API)  
      "message": "object",     // Opsional, pesan kustom (lihat Push API), tidak dapat 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 (maks 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 Push API)
`message`	Tidak	object	Pesan kustom (struktur sama dengan Push API)
`options`	Tidak	object	Opsi push (misal `time_to_live`, `apns_production`)
`custom_args`	Tidak	object	Parameter kustom yang diteruskan

Contoh Respons

Respons sukses (semua berhasil)

{ "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 sukses (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 basic gagal" } }

              
              {  
  "error": {  
    "code": 21004,  
    "message": "autentikasi basic 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 basic 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 Rate Limit
23008	Batas laju API tercapai	Ulangi item gagal jika sebagian sukses	400
Error Parameter
21003	Nilai parameter tidak valid	Periksa format body permintaan	400
21015	Parameter permintaan tidak valid	Validasi field 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: Mengembalikan hasil sebagian sukses saat terjadi pembatasan laju (msg_id untuk yang berhasil + error untuk yang gagal).
Cek Duplikat: Semua nilai target atau cid harus unik dalam satu batch.
Batas Jumlah: Maksimal 500 target per permintaan.
Penanganan Error: Error global (misal gagal autentikasi) langsung menghentikan proses tanpa hasil sebagian.