Buat Template
Endpoint
POST https://otp.api.engagelab.cc/v1/template-configs
Autentikasi
Lihat Autentikasi untuk memahami cara melakukan autentikasi API.
Request
Parameter request
Objek request dinyatakan dalam format JSON, sehingga header request perlu menyertakan Content-Type: application/json.
| Parameter | Tipe | Opsi | Keterangan |
|---|---|---|---|
| template_id | String | Wajib | ID template kustom, bersifat unik, dibatasi hingga 128 karakter |
| description | String | Opsional | Deskripsi template, dibatasi hingga 255 karakter |
| send_channel_strategy | String | Wajib | Strategi template, nilai untuk channel tunggal adalah whatsapp/sms/email/voice, beberapa channel dipisahkan dengan | dan dikirim ulang sesuai urutan; email tidak dapat digabungkan dengan channel lain dalam satu strategi |
| brand_name | String | Opsional | Identitas merek, akan menggantikan variabel signature merek pada beberapa gaya template yang memiliki signature merek, panjang dibatasi antara 2-10 karakter |
| verify_code_config | Object | Wajib bersyarat | Konfigurasi kode verifikasi, wajib ketika template menyertakan tipe kode verifikasi |
| verify_code_config.verify_code_type | Integer | Wajib | Tipe kode verifikasi, rentang nilai [1,7], 1 angka/2 huruf kecil/4 huruf besar, dapat dikombinasikan (misalnya 3 berarti angka+huruf kecil) |
| verify_code_config.verify_code_len | Integer | Wajib | Panjang kode verifikasi, rentang nilai [4,10] |
| verify_code_config.verify_code_ttl | Integer | Wajib | Masa berlaku kode verifikasi, dalam menit, nilai [1,10], jika strategi menyertakan whatsapp hanya boleh 1, 5, atau 10 |
| whatsapp_config | Object | Wajib bersyarat | Konfigurasi strategi whatsapp, wajib ketika strategi pengiriman menyertakan whatsapp |
| whatsapp_config.template_type | Integer | Wajib | Tipe template whatsapp, saat ini hanya mendukung template default, selalu 1 |
| whatsapp_config.template_default_config | Object | Wajib bersyarat | Konfigurasi template default whatsapp, wajib ketika tipe template whatsapp adalah template default |
| sms_config | Object | Wajib bersyarat | Konfigurasi strategi sms, wajib ketika strategi pengiriman menyertakan sms |
| sms_config.template_type | Integer | Wajib | Tipe template sms, 1-template default/2-template kustom |
| sms_config.template_default_config | Object | Wajib bersyarat | Konfigurasi template default sms, wajib ketika tipe template sms adalah template default |
| sms_config.template_custom_config | Object | Wajib bersyarat | Konfigurasi template kustom sms, wajib ketika tipe template sms adalah template kustom |
| sms_config.template_custom_config.custom_sub_type | String | Wajib | Tipe template kustom, authentication-kode verifikasi/marketing-marketing/utility-notifikasi |
| sms_config.template_custom_config.custom_content | String | Wajib | Konten template kustom, harus menyertakan variabel {{code}} untuk tipe authentication |
| sms_config.template_custom_config.custom_country_codes | String | Opsional | Kode negara/wilayah tujuan, dipisahkan dengan koma, digunakan sebagai referensi saat peninjauan template |
| voice_config | Object | Wajib bersyarat | Konfigurasi strategi voice, wajib ketika strategi pengiriman menyertakan voice |
| voice_config.template_type | Integer | Wajib | Tipe template voice, saat ini hanya mendukung template default, selalu 1 |
| voice_config.template_default_config | Object | Wajib bersyarat | Konfigurasi template default voice, wajib ketika tipe template voice adalah template default |
| email_config | Object | Wajib bersyarat | Konfigurasi strategi email, wajib ketika strategi pengiriman menyertakan email |
| email_config.template_name | String | Wajib | Nama template email |
| email_config.template_custom_configs | Array | Wajib bersyarat | Konfigurasi template kustom email, wajib ketika tipe template email adalah template kustom, mendukung konfigurasi multibahasa |
| email_config.template_custom_configs.language | String | Wajib | Bahasa, default adalah bahasa default, saat pengiriman pesan dapat mencocokkan konten template berbeda berdasarkan parameter language |
| email_config.template_custom_configs.pre_from_name | String | Opsional | Nama pengirim yang telah ditentukan |
| email_config.template_custom_configs.pre_from_mail | String | Wajib | Email pengirim yang telah ditentukan |
| email_config.template_custom_configs.pre_subject | String | Wajib | Subjek email yang telah ditentukan |
| email_config.template_custom_configs.template_content | String | Wajib | Konten email, mendukung html, variabel harus diapit dengan {{}} |
| email_config.template_custom_configs.pre_param_map | Object | Opsional | Nilai default untuk variabel konten email, dideklarasikan sebagai pasangan key-value, value harus berupa string |
| pwa_config | Object | Opsional | Konfigurasi terkait pwa, untuk saat ini boleh tidak digunakan |
| pwa_config.pwa_platform | String | Opsional | Platform pwa yang digunakan, untuk nilai spesifik silakan hubungi dukungan teknis |
| pwa_config.pwa_code | String | Opsional | Kode pada platform pwa yang digunakan |
Contoh request
Header request
POST /v1/template-configs HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0
Body request
{
"template_id": "test-template-1", // ID template kustom, unik dalam aplikasi
"description": "Template uji 1", // deskripsi penjelasan template ini
"send_channel_strategy": "whatsapp|sms", // strategi pengiriman template, mendukung empat jenis whatsapp/sms/voice/email, untuk strategi kombinasi gunakan karakter | untuk menandakan pengiriman ulang saat gagal
"brand_name": "Nama merek", // nama merek, digunakan pada signature konten template di beberapa negara/wilayah (misalnya beberapa negara/wilayah pada channel SMS mewajibkan registrasi signature)
"verify_code_config": { // konfigurasi kode verifikasi, untuk mengonfigurasi kode verifikasi yang dibuat otomatis, wajib ketika template menyertakan tipe kode verifikasi
"verify_code_type": 1, // tipe kode verifikasi, rentang nilai [1,7]
"verify_code_len": 6, // panjang kode verifikasi, rentang nilai [4,10]
"verify_code_ttl": 1 // masa berlaku kode verifikasi, rentang nilai [1,10], perhatikan ketika strategi menyertakan whatsapp nilainya hanya boleh 1, 5, 10
},
"whatsapp_config": { // konfigurasi strategi whatsapp, berlaku ketika strategi pengiriman menyertakan whatsapp
"template_type": 1, // tipe template whatsapp, saat ini hanya mendukung template default, yaitu selalu 1
"template_default_config": { // konfigurasi template default whatsapp, berlaku untuk tipe template default
"contain_security": false, // apakah menambahkan pengingat keamanan
"contain_expire": false // apakah menambahkan konten waktu kedaluwarsa
}
},
"sms_config": { // konfigurasi strategi sms, berlaku ketika strategi pengiriman menyertakan sms
"template_type": 2, // tipe template sms, nilai: 1-template default/2-template kustom
"template_default_config": { // konfigurasi template default sms, berlaku untuk tipe template default
"contain_security": false, // apakah menambahkan pengingat keamanan
"contain_expire": false // apakah menambahkan konten waktu kedaluwarsa
},
"template_custom_config": { // konfigurasi template kustom sms, berlaku ketika tipe template sms adalah template kustom
"custom_sub_type": "authentication", // tipe template kustom, nilai: authentication-kode verifikasi/marketing-marketing/utility-notifikasi
"custom_content": "xxx", // konten template kustom, perhatikan jika sub-tipe adalah authentication (kode verifikasi) maka harus menyertakan variabel {{code}}
"custom_country_codes": "HK,PH" // negara/wilayah tujuan template kustom, digunakan sebagai referensi saat peninjauan template, harap isi sesuai kenyataan, jika tidak dapat memengaruhi pengiriman sebenarnya
}
},
"voice_config": { // konfigurasi strategi voice, berlaku ketika strategi pengiriman menyertakan voice
"template_type": 1, // tipe template voice, saat ini hanya mendukung template default, yaitu selalu 1
"template_default_config": { // konfigurasi template default voice, berlaku untuk tipe template default
"contain_security": false, // apakah menambahkan pengingat keamanan
"contain_expire": false // apakah menambahkan konten waktu kedaluwarsa
}
},
"email_config": { // konfigurasi strategi email, berlaku ketika strategi pengiriman menyertakan email
"template_name": "nama template email", // nama template email
"template_custom_configs": [{ // konfigurasi template kustom email, perhatikan ini adalah array objek, terutama untuk mengonfigurasi beberapa entri yang dibedakan melalui language
"language": "default", // bahasa, default adalah bahasa default, saat pengiriman pesan dapat mencocokkan konten template berbeda berdasarkan parameter language
"pre_from_name": "test", // nama pengirim yang telah ditentukan
"pre_from_mail": "test@test.com", // email pengirim yang telah ditentukan
"pre_subject": "test", // subjek email yang telah ditentukan
"template_content": "Konten template email yang telah ditentukan, wajib, variabel kustom seperti {{self}}, kode verifikasinya adalah {{code}}", // konten email, mendukung html, variabel harus diapit dengan dua kurung kurawal {{}}
"pre_param_map": { // nilai default variabel dalam konten email, yaitu jika nilai variabel tidak ditentukan saat pengiriman, maka nilai default berikut digunakan untuk menggantikan variabel, dideklarasikan sebagai pasangan key-value, value harus berupa string
"self": "Ini nilai default variabel self"
}
}]
},
"pwa_config": { // konfigurasi terkait pwa, untuk saat ini boleh tidak digunakan
"pwa_platform": "xx", // platform pwa yang digunakan, untuk nilai spesifik silakan hubungi dukungan teknis
"pwa_code": "xx" // kode pada platform pwa yang digunakan
}
}
Respons
Parameter respons
| Field | Tipe | Opsi | Deskripsi |
|---|---|---|---|
| code | Integer | Wajib | Kode error, 0 berarti sukses, lainnya berarti gagal |
| message | String | Wajib | Informasi respons |
Contoh respons
Respons sukses
{
"code": 0,
"message": "success"
}
Respons gagal
{
"code": 3003,
"message": "not contains any channel config"
}
Penggunaan lanjutan variabel template Email
Ketika Anda mengaktifkan channel Email dalam strategi pengiriman, Anda dapat menyesuaikan subjek dan konten isi email secara mendalam. Melalui placeholder variabel {{nama_variabel}}, konten seperti kode verifikasi dan informasi merek dapat diisi otomatis, sehingga menghadirkan pengalaman email personal yang fleksibel.
Tipe dan penggunaan variabel
Isi template Email (template_content) dan subjek (pre_subject) sama-sama dapat menyematkan variabel, dengan format {{nama_variabel}}.
Nilainya diteruskan secara dinamis melalui field template.params pada API pengiriman, atau diatur sebagai nilai default pada tahap pembuatan template.
Variabel yang didukung
Variabel berikut hanya berlaku untuk channel Email.
| Nama variabel | Tipe | Keterangan | Cara pengisian |
|---|---|---|---|
{{logo_url}} |
Variabel kustom | Alamat gambar Logo merek | Diteruskan saat pengiriman melalui template.params |
{{title}} |
Variabel kustom | Teks judul isi email | Diteruskan saat pengiriman melalui template.params |
{{support_email}} |
Variabel kustom | Alamat email layanan/dukungan | Diteruskan saat pengiriman melalui template.params |
{{subject}} |
Variabel kustom | Menimpa subjek email secara dinamis | Diteruskan saat pengiriman melalui template.params |
{{from_name}} |
Variabel kustom | Menimpa nama pengirim secara dinamis | Diteruskan saat pengiriman melalui template.params |
{{from_mail}} |
Variabel kustom | Menimpa email pengirim secara dinamis | Diteruskan saat pengiriman melalui template.params |
Catatan: Variabel khusus
{{subject}},{{from_name}},{{from_mail}}tidak disisipkan ke dalam HTML isi email, melainkan langsung menimpa field metadata email.
Contoh subjek email
{{brand_name}} Kode Verifikasi
Contoh isi email
<img src="{{logo_url}}" />
<strong>{{title}}</strong>
<p>Kode verifikasi Anda adalah <strong>{{code}}</strong>, harap selesaikan verifikasi dalam {{ttl}} menit.</p>
<p>Jika ada pertanyaan, silakan hubungi <a href="mailto:{{support_email}}">{{support_email}}</a></p>
Pengaturan nilai default template
Saat membuat template, Anda dapat mengatur nilai default variabel kustom pada field pre_param_map. Jika variabel tidak diteruskan saat mengirim email, nilai default akan digunakan secara otomatis.
"pre_param_map": {
"logo_url": "https://example.com/logo.png",
"title": "Kode verifikasi Anda",
"support_email": "support@example.com"
}
Penjelasan parameter pengiriman
| Field | Tipe | Wajib | Keterangan |
|---|---|---|---|
to |
string | Ya | Alamat email tujuan |
template.id |
string | Ya | ID template email |
template.language |
string | Tidak | Kode bahasa, default default |
template.params |
object | Tidak | Pengisian nilai variabel template (tanpa {{}}) |
Contoh request:
{
"to": "user@example.com",
"template": {
"id": "my_email_template",
"language": "default",
"params": {
"logo_url": "https://example.com/logo.png",
"title": "Kode verifikasi Anda",
"support_email": "support@example.com"
}
}
}
Prioritas pengisian variabel
- Mengutamakan nilai variabel yang diteruskan melalui
template.paramspada endpoint pengiriman; - Jika tidak diteruskan, gunakan nilai default pada
pre_param_maptemplate; - Jika keduanya tidak diatur, placeholder akan ditampilkan apa adanya dalam konten email.
Pertanyaan yang sering diajukan
Q: Mengapa variabel tidak tergantikan?
A: Pastikan penulisan dan format nama variabel benar (harus {{nama_variabel}}), dan pastikan nilainya telah disediakan melalui template.params, atau template telah mengatur nilai default.
Q: Bagaimana cara mengatur subjek email dan pengirim secara dinamis?
A: Teruskan subject, from_name, from_mail dalam parameter request template.params, untuk menimpa secara dinamis subjek dan informasi pengirim yang telah ditentukan pada template.
Kode error
| Kode error | http code | Keterangan |
|---|---|---|
| 1000 | 500 | Error internal |
| 2001 | 401 | Autentikasi gagal, tidak menyertakan token yang benar |
| 2002 | 401 | Autentikasi gagal, token telah kedaluwarsa atau dinonaktifkan |
| 2004 | 403 | Tidak memiliki izin untuk memanggil API ini |
| 3001 | 400 | Format parameter request tidak valid, harap periksa apakah konten JSON sesuai dengan format parameter |
| 3002 | 400 | Parameter request salah, harap periksa apakah parameter request memenuhi persyaratan |
| 3003 | 400 | Error parameter pada tingkat bisnis, harap periksa keterangan pada field message yang dikembalikan |










