Pengiriman OTP

Endpoint ini membuat kode verifikasi melalui platform EngageLab, dan mengirimkannya sesuai strategi channel yang ditentukan dalam template.

Jika Anda ingin membuat kode verifikasi sendiri tanpa melalui platform EngageLab, Anda dapat memanggil endpoint Pengiriman OTP Kustom EngageLab.

Endpoint

POST https://otp.api.engagelab.cc/v1/messages

Autentikasi

Lihat Autentikasi untuk memahami cara melakukan autentikasi API.

Contoh request

Header request

              
              POST /v1/messages  HTTP/1.1  
Content-Type: application/json  
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            

Body request

              
              {
    "to": "+6591234567",
    "template":{
      "id":"test-template-1",
      "language": "default",
        "params": {
        "key1": "value1",
        "key2": "value2"
        }
    }
}

            

Parameter request

Objek request dinyatakan dalam format JSON, sehingga header request perlu menyertakan Content-Type: application/json.

Penjelasan tentang params

1. Untuk field preset template seperti from_id, jika nilai field params tidak diteruskan, maka saat pengiriman pesan akan digunakan from_id preset template;
2. Jika nilai field params diteruskan, seperti params:{"from_id":"12345"}, maka saat pengiriman pesan, from_id template akan diganti menjadi 12345;
3. Selain itu, untuk field variabel kustom dalam konten template saat pembuatan template, nilainya juga diisi melalui params, misalnya konten template Hi {{name}}, your verify code is {{code}}, maka perlu mengisi parameter params:{"name":"Bob"}
4. Variabel khusus channel Email: Untuk channel Email, mendukung penimpaan dinamis subjek email (subject), nama pengirim (from_name), email pengirim (from_mail), dan lainnya melalui params. Untuk penggunaan lanjutan yang lebih detail, lihat Buat Template - Penggunaan lanjutan variabel template Email.

Parameter respons

Respons sukses

              
              {
    "message_id": "1725407449772531712",
    "send_channel": "sms"
}

            

Perhatikan, nilai**send_channel**yang dikembalikan tidak mewakili channel akhir yang sampai ke pengguna, melainkan hanya mewakili channel yang digunakan pada tahap saat ini; jika strategi template mengonfigurasi channel WhatsApp dan pengirimannya gagal lalu otomatis dikirim ulang melalui channel SMS, maka respons endpoint akan mengembalikan nilai whatsapp, dan setelah beberapa waktu ketika kegagalan terdeteksi, sistem akan menggunakan channel SMS untuk mengirim

Respons gagal

Status code HTTP adalah 4xx atau 5xx, body respons berisi field sebagai berikut:

              
              {
    "code": 5001,
    "message": "sms send fail"
}

            

Kode error

Tabel berikut hanya menjelaskan error yang dikembalikan API ini pada tahap autentikasi, validasi sebelum pengiriman, dan pengiriman sinkron. Kegagalan pengiriman asinkron setelah diterima penyedia tidak dikembalikan oleh API ini; dapatkan melalui kueri status pesan atau callback.

Pemanggil harus menggunakan code untuk menentukan jenis error. Gunakan message untuk menampilkan alasan spesifik atau untuk troubleshooting; jangan mengandalkan teks message yang tetap untuk logika bisnis.

Catatan error batasan laju dan volume pengiriman

• 3004 adalah kontrol frekuensi pengiriman OTP template; jendela batas mengikuti konfigurasi template dan mungkin tidak sama dengan masa berlaku kode verifikasi.
• 6001 dan 6002 adalah kontrol frekuensi keamanan pada dimensi nomor atau IP pengguna akhir.
• 6003 dan 6008 menunjukkan permintaan ini memicu batas volume pengiriman; setelah mencapai batas dan memasuki status ditangguhkan, permintaan berikutnya mungkin mengembalikan 6007.
• Saat menerima HTTP 429, jangan segera mencoba ulang secara terus-menerus; coba lagi nanti, dan jika terus muncul, hubungi administrator atau dukungan teknis.
• 5011 hingga 5019 hanya mencakup kegagalan yang dapat dikenali pada tahap pengiriman sinkron. Status seperti nomor kosong, ponsel mati, atau penolakan operator setelah diterima penyedia masih dapat dikembalikan melalui status pesan asinkron atau callback.