WhatsApp · Template

Template WhatsApp

Kirim template WhatsApp yang sudah disetujui Meta untuk komunikasi di luar jendela 24 jam.

Template WhatsApp adalah pesan yang sudah disetujui oleh Meta dan dapat dikirim ke pengguna WhatsApp di luar jendela percakapan 24 jam terakhir. Template diperlukan untuk komunikasi bisnis yang dimulai dari pihak perusahaan — misalnya notifikasi order, pengingat pembayaran, atau OTP.

whatsGo menyediakan dua cara utama untuk bekerja dengan template:

  1. List template — ambil daftar template yang tersedia dari saluran WhatsApp kamu.
  2. Kirim template — kirim template ke nomor tujuan dengan parameter yang sesuai.
Prasyarat

Pastikan template sudah disetujui oleh Meta di WhatsApp Manager sebelum dikirim melalui API. Template yang belum disetujui akan mengembalikan error.

List template yang tersedia

Ambil daftar seluruh template WhatsApp yang terdaftar di saluran kamu.

GET /external-api/inbox/template-list

Contoh request

curl -X GET "https://whats.sahabatmobile.com/external-api/inbox/template-list" \
  -H "Authorization: Bearer wg_sk_xxxxx" \
  -H "Content-Type: application/json"

Response list example

{
  "success": true,
  "data": [
    {
      "name": "order_confirmation",
      "language": "id",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": ["HEADER", "BODY", "BUTTONS"]
    },
    {
      "name": "otp_verification",
      "language": "id",
      "category": "AUTHENTICATION",
      "status": "APPROVED",
      "components": ["BODY", "BUTTONS"]
    },
    {
      "name": "shipping_update",
      "language": "en",
      "category": "UTILITY",
      "status": "APPROVED",
      "components": ["HEADER", "BODY"]
    }
  ]
}

Field response

Field Tipe Keterangan
name string Nama unik template (digunakan saat mengirim)
language string Kode bahasa template (mis. id, en)
category string Kategori template: AUTHENTICATION, UTILITY, MARKETING, atau SERVICE
status string Status persetujuan Meta: APPROVED, PENDING, REJECTED
components array Daftar komponen yang dimiliki template (HEADER, BODY, FOOTER, BUTTONS)

Mengirim template

Kirim template WhatsApp ke nomor tujuan. Endpoint ini menggunakan metode POST dan menerima body JSON.

POST /external-api/inbox/send-template-message

Body fields

Field Tipe Wajib Keterangan
to string Ya Nomor tujuan dalam format E.164 (mis. 6281234567890)
template object Ya Objek berisi name (string) dan language (object dengan code)
template.name string Ya Nama template yang sudah disetujui
template.language.code string Ya Kode bahasa template (mis. id, en_US)
template.components array Tidak Array komponen untuk mengisi parameter dinamis
channel_id string Tidak ID saluran WhatsApp yang digunakan (wajib jika punya lebih dari satu saluran)

Kirim lewat endpoint template

Gunakan endpoint berikut untuk mengirim template WhatsApp:

POST /external-api/inbox/send-template-message

Header yang diperlukan:

Authorization: Bearer wg_sk_xxxxx
Content-Type: application/json

Contoh request

curl -X POST "https://whats.sahabatmobile.com/external-api/inbox/send-template-message" \
  -H "Authorization: Bearer wg_sk_xxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "6281234567890",
    "template": {
      "name": "order_confirmation",
      "language": {
        "code": "id"
      }
    }
  }'

Struktur komponen

Field template.components adalah array yang berisi objek komponen. Setiap komponen merepresentasikan bagian dari template — header, body, atau button.

Tipe Komponen Field Keterangan
HEADER type: "header" Bagian atas template. Bisa berisi teks, gambar, video, atau dokumen. Gunakan parameters untuk nilai dinamis.
BODY type: "body" Bagian utama pesan. Berisi placeholder {{1}}, {{2}}, dst. yang diisi melalui parameters.
BUTTONS type: "button" Tombol interaktif. Tipe: quick_reply (balasan cepat) atau url (tautan dinamis). Tentukan index urutan tombol.

Jenis parameter

Setiap parameter dalam komponen memiliki field type yang menentukan jenis nilainya:

Tipe Deskripsi
text Nilai teks biasa. Contoh: nama pelanggan, nomor order.
currency Nilai mata uang dengan format fallback_value, code, dan amount_1000.
date_time Nilai tanggal/waktu. Gunakan fallback_value dengan format string yang mudah dibaca.
image Header gambar. Sertakan link URL gambar atau id media yang sudah diunggah.
video Header video. Sertakan link URL video.
document Header dokumen. Sertakan link URL dokumen.
location Header lokasi. Sertakan latitude, longitude, name, dan address.

Contoh-contoh

Template OTP sederhana

{
  "to": "6281234567890",
  "template": {
    "name": "otp_verification",
    "language": {
      "code": "id"
    }
  }
}
Catatan

Template OTP dari kategori AUTHENTICATION yang tidak memiliki parameter dinamis tidak perlu menyertakan components.

Template dengan header gambar

{
  "to": "6281234567890",
  "template": {
    "name": "promo_sale",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "image",
            "image": {
              "link": "https://example.com/promo-banner.jpg"
            }
          }
        ]
      }
    ]
  }
}

Template dengan named parameter

{
  "to": "6281234567890",
  "template": {
    "name": "order_confirmation",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Budi Santoso"
          },
          {
            "type": "text",
            "text": "ORD-2026-00123"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "Rp 250.000",
              "code": "IDR",
              "amount_1000": 250
            }
          }
        ]
      }
    ]
  }
}

Template dengan tombol Quick Reply

{
  "to": "6281234567890",
  "template": {
    "name": "appointment_reminder",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Dr. Andi Wijaya"
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "20 Juli 2026, 10:00 WIB"
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 0,
        "parameters": [
          {
            "type": "payload",
            "payload": "CONFIRM_APPOINTMENT"
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "quick_reply",
        "index": 1,
        "parameters": [
          {
            "type": "payload",
            "payload": "RESCHEDULE_APPOINTMENT"
          }
        ]
      }
    ]
  }
}

Template dengan tombol URL dinamis

{
  "to": "6281234567890",
  "template": {
    "name": "invoice_notification",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Budi Santoso"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "Rp 1.500.000",
              "code": "IDR",
              "amount_1000": 1500
            }
          }
        ]
      },
      {
        "type": "button",
        "sub_type": "url",
        "index": 0,
        "parameters": [
          {
            "type": "text",
            "text": "INV-2026-00456"
          }
        ]
      }
    ]
  }
}

Template dengan header lokasi

{
  "to": "6281234567890",
  "template": {
    "name": "event_invitation",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "header",
        "parameters": [
          {
            "type": "location",
            "location": {
              "latitude": -6.2088,
              "longitude": 106.8456,
              "name": "Gelora Bung Karno",
              "address": "Jl. Pintu X Senayan, Jakarta"
            }
          }
        ]
      },
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Konser Amal 2026"
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "25 Juli 2026, 19:00 WIB"
            }
          }
        ]
      }
    ]
  }
}

Template dengan currency

{
  "to": "6281234567890",
  "template": {
    "name": "payment_reminder",
    "language": {
      "code": "id"
    },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "INV-2026-00789"
          },
          {
            "type": "currency",
            "currency": {
              "fallback_value": "Rp 750.000",
              "code": "IDR",
              "amount_1000": 750
            }
          },
          {
            "type": "date_time",
            "date_time": {
              "fallback_value": "31 Juli 2026"
            }
          }
        ]
      }
    ]
  }
}

Response sukses

{
  "success": true,
  "data": {
    "messaging_product": "whatsapp",
    "contacts": [
      {
        "input": "6281234567890",
        "wa_id": "6281234567890"
      }
    ],
    "messages": [
      {
        "id": "wamid.HBgLMTIxMjM0NTY3ODkwQg==",
        "message_status": "sent"
      }
    ]
  }
}
Field Keterangan
messaging_product Produk messaging yang digunakan (selalu "whatsapp")
contacts[].input Nomor tujuan yang dikirim
contacts[].wa_id Nomor WhatsApp yang valid (setelah validasi)
messages[].id ID unik pesan WhatsApp (bisa digunakan untuk melacak status)
messages[].message_status Status awal pengiriman (sent, queued)

Pesan error template

Berikut adalah daftar error yang sering terjadi saat mengirim template WhatsApp:

Kode Error HTTP Status Pesan Penyebab
132000 400 Template param mismatch Jumlah parameter yang dikirim tidak sesuai dengan jumlah placeholder di template
132001 400 Template missing parameters Parameter yang diwajibkan tidak dikirim (lihat bagian Troubleshooting di bawah)
132005 400 Template text too long Nilai parameter melebihi panjang maksimal yang diizinkan
132006 400 Template paused Template sedang dalam status PAUSED oleh Meta (akibat performa buruk)
132007 400 Template rejected Template ditolak oleh Meta. Periksa status di WhatsApp Manager
132008 400 Template language mismatch Kode bahasa yang dikirim tidak tersedia untuk template tersebut
132012 400 Template does not exist Nama template tidak ditemukan atau belum terdaftar di saluran ini
132015 400 Template category mismatch Kategori template tidak sesuai dengan jenis kampanye yang dikirim

Troubleshooting #132001

Error 132001 (Template missing parameters) adalah salah satu error yang paling sering ditemui. Error ini terjadi ketika kamu mengirim template tanpa menyertakan parameter yang diwajibkan.

Penyebab umum

  1. Parameter body tidak dikirim — Template memiliki placeholder {{1}}, {{2}} tetapi array parameters kosong atau tidak ada.
  2. Jumlah parameter kurang — Template memiliki 3 placeholder tetapi hanya 2 parameter yang dikirim.
  3. Tipe parameter salah — Placeholder untuk gambar dikirim dengan tipe text (seharusnya image).
  4. Komponen header tidak dikirim — Template memiliki header gambar/waktu tetapi komponen header tidak disertakan dalam request.

Solusi

  1. Periksa struktur template — Gunakan endpoint GET /external-api/inbox/template-list untuk melihat komponen apa saja yang dimiliki template.
  2. Pastikan jumlah parameter sesuai — Hitung jumlah placeholder di body dan header, lalu kirim jumlah parameter yang sama.
  3. Periksa tipe parameter — Pastikan tipe parameter (text, image, currency, date_time) sesuai dengan jenis komponen.
  4. Gunakan komponen lengkap — Jika template memiliki header dan tombol, sertakan semua komponen yang diperlukan.

Contoh perbaikan

Salah — body kosong untuk template dengan 2 parameter:

{
  "to": "6281234567890",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "id" },
    "components": [
      {
        "type": "body",
        "parameters": []
      }
    ]
  }
}

Benar — parameter lengkap sesuai jumlah placeholder:

{
  "to": "6281234567890",
  "template": {
    "name": "order_confirmation",
    "language": { "code": "id" },
    "components": [
      {
        "type": "body",
        "parameters": [
          {
            "type": "text",
            "text": "Budi Santoso"
          },
          {
            "type": "text",
            "text": "ORD-2026-00123"
          }
        ]
      }
    ]
  }
}
Tips debugging

Saat mengembangkan, simpan response error lengkap dari API. Field error.details (jika tersedia) memberikan informasi spesifik tentang parameter mana yang bermasalah.