Logo Site EngageLab Mark Colored TransparentDokumen
Cari

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
              
              POST /v1/template-configs  HTTP/1.1
Content-Type: application/json
Authorization: Basic amlndWFuZ2RldjpkZXZfc2VjcmV0

            
Tampilkan blok kode ini di jendela mengambang

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 } }
              
              {
    "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
    }
}

            
Tampilkan blok kode ini di jendela mengambang

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" }
              
              {
    "code": 0,
    "message": "success"
}

            
Tampilkan blok kode ini di jendela mengambang

Respons gagal

{ "code": 3003, "message": "not contains any channel config" }
              
              {
    "code": 3003,
    "message": "not contains any channel config"
}

            
Tampilkan blok kode ini di jendela mengambang

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
              
              {{brand_name}} Kode Verifikasi

            
Tampilkan blok kode ini di jendela mengambang

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>
              
              <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>

            
Tampilkan blok kode ini di jendela mengambang

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" }
              
              "pre_param_map": {
  "logo_url": "https://example.com/logo.png",
  "title": "Kode verifikasi Anda",
  "support_email": "support@example.com"
}

            
Tampilkan blok kode ini di jendela mengambang

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" } } }
              
              {
  "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"
    }
  }
}

            
Tampilkan blok kode ini di jendela mengambang

Prioritas pengisian variabel

  1. Mengutamakan nilai variabel yang diteruskan melalui template.params pada endpoint pengiriman;
  2. Jika tidak diteruskan, gunakan nilai default pada pre_param_map template;
  3. 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
Icon Solid Transparent White Qiyu
Hubungi Sales