Pesan Interaktif WhatsApp

Quick Reply, CTA URL, List, dan Minta Lokasi — pesan dengan tombol/pilihan yang membuat pelanggan merespons tanpa perlu mengetik.

Pesan interaktif memungkinkan pelanggan membalas dengan menekan tombol atau memilih opsi alih-alih mengetik. Tidak butuh approval template — cukup kirim ke kontak yang sudah membalas pesan kamu dalam 24 jam terakhir.

Semua path di halaman ini relatif terhadap base URL https://api.chatera.id/v1.

POST /v1/whatsapp/messages

Scope: whatsapp:send

Tipe yang tersedia

Tipe	`interactive.type`	Kegunaan
Quick Reply	`button`	Maks 3 tombol balas cepat
CTA URL	`cta_url`	1 tombol membuka link
List	`list`	Daftar pilihan dengan kategori (mis. menu pilihan layanan)
Minta Lokasi	`location_request_message`	Tombol Kirim lokasi agar pelanggan membagikan lokasinya

Satu pesan, satu tipe

Setiap pesan interaktif hanya boleh berisi satu tipe. Untuk kombinasi (mis. Quick Reply + CTA URL di percakapan yang sama), kirim dua pesan terpisah.

Quick Reply (tombol balas cepat)

{
  "to": "628123456789",
  "type": "interactive",
  "interactive": {
    "type": "button",
    "header": { "type": "text", "text": "Konfirmasi Pesanan" },
    "body": { "text": "Pesanan #ORD-12345 siap dikirim. Alamat sudah benar?" },
    "footer": { "text": "Balas dalam 24 jam" },
    "action": {
      "buttons": [
        { "type": "reply", "reply": { "id": "confirm_yes", "title": "Ya, Benar" } },
        { "type": "reply", "reply": { "id": "confirm_no",  "title": "Ubah Alamat" } }
      ]
    }
  }
}

Batas

Field	Min	Maks
Jumlah tombol	1	3
`reply.title`	1	20 karakter
`reply.id`	1	256 karakter
`header.text`	—	60 karakter
`body.text`	1	1024 karakter
`footer.text`	—	60 karakter

reply.id adalah ID unik yang akan kamu terima di webhook saat user menekan tombol — pakai untuk routing logic di handler kamu.

CTA URL (tombol membuka link)

{
  "to": "628123456789",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "body": { "text": "Pesanan menunggu pembayaran Rp 250.000. Klik untuk membayar." },
    "footer": { "text": "Link berlaku 24 jam" },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Bayar Sekarang",
        "url": "https://payment.toko-anda.com/pay/ORD-12345"
      }
    }
  }
}

Batas

Field	Min	Maks
`parameters.display_text`	1	20 karakter
`parameters.url`	1	Harus HTTP/HTTPS
`body.text`	1	1024 karakter
`header`	opsional	`type`: `text`, `image`, `video`, atau `document`. `header.text` maks 60 karakter
`footer.text`	opsional	60 karakter

Header CTA URL sekarang bisa berupa media, bukan cuma teks. Formatnya sama seperti pesan media biasa (link HTTPS publik atau id media):

{
  "to": "628123456789",
  "type": "interactive",
  "interactive": {
    "type": "cta_url",
    "header": {
      "type": "image",
      "image": { "link": "https://toko-anda.com/promo/banner.jpg" }
    },
    "body": { "text": "Promo akhir bulan sudah dimulai. Cek katalognya, yuk!" },
    "action": {
      "name": "cta_url",
      "parameters": {
        "display_text": "Lihat Katalog",
        "url": "https://toko-anda.com/katalog"
      }
    }
  }
}

Untuk header document, isi document.link (atau document.id) dan opsional document.filename; untuk video, isi video.link atau video.id.

List (daftar pilihan)

Cocok untuk menu pilihan layanan, kategori produk, jadwal slot, dll.

{
  "to": "628123456789",
  "type": "interactive",
  "interactive": {
    "type": "list",
    "header": { "type": "text", "text": "Menu Layanan" },
    "body": { "text": "Silakan pilih layanan yang Anda butuhkan:" },
    "footer": { "text": "Pilih salah satu opsi" },
    "action": {
      "button": "Pilih Layanan",
      "sections": [
        {
          "title": "Layanan Pelanggan",
          "rows": [
            { "id": "faq", "title": "FAQ", "description": "Pertanyaan yang sering diajukan" },
            { "id": "talk_agent", "title": "Hubungi CS", "description": "Bicara langsung dengan agen kami" }
          ]
        },
        {
          "title": "Order & Pembayaran",
          "rows": [
            { "id": "track_order", "title": "Lacak Pesanan", "description": "Cek status pengiriman" },
            { "id": "payment_help", "title": "Bantuan Pembayaran", "description": "Pertanyaan seputar metode pembayaran" }
          ]
        }
      ]
    }
  }
}

Batas

Field	Min	Maks
`action.button`	1	20 karakter
Jumlah `sections`	1	10
Jumlah `rows` (semua section digabung)	1 per section	10 total
`rows[].title`	1	24 karakter
`rows[].description`	—	72 karakter
`rows[].id`	1	200 karakter
`body.text`	1	4096 karakter

Minta Lokasi (location_request_message)

Tampilkan tombol Kirim lokasi di bawah pesan kamu. Cocok untuk alamat pengantaran, titik jemput, atau verifikasi area layanan.

{
  "to": "628123456789",
  "type": "interactive",
  "interactive": {
    "type": "location_request_message",
    "body": { "text": "Kirim lokasi kamu ya, biar kurir kami bisa langsung jalan." },
    "action": { "name": "send_location" }
  }
}

Field	Wajib	Tipe	Keterangan
`interactive.type`	✅	string	`location_request_message`
`interactive.body.text`	✅	string	Teks pesan, maks 1024 karakter
`interactive.action.name`	✅	string	Selalu `send_location`

Tipe ini tidak memakai header maupun footer.

Batas

Field	Min	Maks
`body.text`	1	1024 karakter
`action.name`	—	harus `send_location`

Saat pelanggan menekan tombol dan membagikan lokasinya, balasannya masuk sebagai pesan lokasi biasa (bukan balasan interaktif) — lihat Menerima jawaban user.

Batas & penolakan

Server menolak request yang melebihi batas — kamu akan menerima error WHATSAPP_INTERACTIVE_LIMIT_EXCEEDED.

Pesan error pesan interaktif

Kode	Penyebab	Solusi
`WHATSAPP_SESSION_CLOSED`	Di luar jendela 24 jam	Pakai template
`WHATSAPP_INTERACTIVE_INVALID_TYPE`	`interactive.type` tidak dikenal	Pakai `button`, `list`, `cta_url`, atau `location_request_message`
`WHATSAPP_INTERACTIVE_MISSING_FIELD`	Field wajib tidak ada	Cek `details.field`
`WHATSAPP_INTERACTIVE_INVALID_FIELD`	Format field tidak valid	Cek `details.errors[]` (mis. URL bukan HTTPS, `action.name` bukan `send_location`, header CTA URL selain `text`/`image`/`video`/`document`)
`WHATSAPP_INTERACTIVE_LIMIT_EXCEEDED`	Melebihi batas tombol/section/karakter	Lihat tabel batas di atas

Menerima jawaban user

Saat user menekan tombol Quick Reply atau memilih row di List, Chatera mengirim webhook event message.inbound ke endpoint webhook kamu.

Payload webhook akan berisi interactive.reply.id (untuk button) atau interactive.list_reply.id (untuk list) — gunakan ID ini untuk routing logic di handler kamu.

Balasan dari Minta Lokasi masuk sebagai message.inbound dengan contentType: "location" dan content.text bernilai "[Location]". Koordinat (latitude, longitude, nama, alamat) tampil di inbox Chatera, tetapi belum disertakan di payload webhook.

Lihat Webhook untuk detail format payload.

Pesan Interaktif WhatsApp

On this page