Kirim Pesan WhatsApp

POST /v1/whatsapp/messages

Scope yang dibutuhkan: whatsapp:send

Endpoint ini dipakai untuk mengirim semua jenis pesan WhatsApp: teks, gambar, dokumen, audio, video, lokasi, template, dan pesan interaktif.

Aturan jendela 24 jam

Pesan teks, media, lokasi, dan interaktif hanya bisa dikirim jika kontak telah mengirim pesan ke kamu dalam 24 jam terakhir. Untuk komunikasi proaktif di luar jendela ini, gunakan template WhatsApp yang sudah disetujui Meta.

Body request — field umum

Semua tipe pesan menggunakan field umum berikut:

Field	Wajib	Tipe	Keterangan
`to`	✅	string	Nomor tujuan (E.164)
`type`	✅	string	`text` \| `image` \| `audio` \| `video` \| `document` \| `location` \| `template` \| `interactive`
`channel_id`	—	string (UUID)	ID saluran WhatsApp pengirim. Wajib hanya jika kamu punya lebih dari satu saluran aktif.

Tipe pesan

Teks

{
  "to": "628123456789",
  "type": "text",
  "text": {
    "body": "Halo, ini pesan dari API Chatera!",
    "preview_url": false
  }
}

Field	Wajib	Keterangan
`text.body`	✅	Isi pesan, maks 4096 karakter
`text.preview_url`	—	`true` untuk preview link otomatis (default `false`)

Gambar

{
  "to": "628123456789",
  "type": "image",
  "image": {
    "link": "https://contoh.com/produk.jpg",
    "caption": "Produk baru tersedia!"
  }
}

Field	Wajib	Keterangan
`image.link`	✅	URL HTTPS publik ke gambar (JPEG/PNG)
`image.caption`	—	Caption di bawah gambar

Audio

{
  "to": "628123456789",
  "type": "audio",
  "audio": {
    "link": "https://contoh.com/voicenote.ogg"
  }
}

Audio tidak mendukung caption.

Video

{
  "to": "628123456789",
  "type": "video",
  "video": {
    "link": "https://contoh.com/promo.mp4",
    "caption": "Lihat video promo terbaru kami!"
  }
}

Dokumen

{
  "to": "628123456789",
  "type": "document",
  "document": {
    "link": "https://contoh.com/invoice.pdf",
    "caption": "Invoice #ORD-12345",
    "filename": "invoice-ord-12345.pdf"
  }
}

Field	Wajib	Keterangan
`document.link`	✅	URL HTTPS publik ke dokumen
`document.filename`	✅	Nama file yang ditampilkan ke penerima
`document.caption`	—	Caption di atas attachment

Lokasi

{
  "to": "628123456789",
  "type": "location",
  "location": {
    "latitude": -6.2,
    "longitude": 106.816666,
    "name": "Kantor Chatera",
    "address": "Jl. Contoh No. 123, Jakarta"
  }
}

name dan address opsional.

Multi-channel: memilih saluran pengirim

Jika organisasi kamu punya lebih dari satu saluran WhatsApp aktif, sertakan channel_id untuk memilih saluran pengirim:

{
  "to": "628123456789",
  "type": "text",
  "channel_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "text": { "body": "Halo dari channel sales!" }
}

Cara mendapatkan channel_id:

Dari payload webhook (data.channelId).
Dari halaman Pengaturan > Saluran di dashboard.

Jika channel_id tidak disertakan dan kamu hanya punya satu saluran, saluran tersebut otomatis dipakai. Jika punya beberapa saluran tanpa channel_id, request akan ditolak dengan error WHATSAPP_CHANNEL_NOT_FOUND.

Response

{
  "success": true,
  "data": {
    "messageId": "9b8c1234-e5f6-4789-90ab-cdef01234567",
    "whatsappMessageId": "wamid.HBgNNjI4MTIzNDU2Nzg5FQIAERgSRDM0NEU3RkY1...",
    "status": "sent",
    "to": "+628123456789",
    "timestamp": "2026-04-27T10:51:33.228Z"
  }
}

Field	Keterangan
`messageId`	ID pesan di Chatera (UUID) — pakai untuk lookup di webhook
`whatsappMessageId`	ID dari Meta (`wamid.xxx`)
`status`	`sent` (artinya diterima oleh server WhatsApp Cloud API; status `delivered` & `read` dikirim via webhook)
`to`	Nomor tujuan dalam E.164 (dengan `+`)
`timestamp`	Waktu kirim (ISO 8601)

Pesan error

Kode	Penyebab	Solusi
`VALIDATION_INVALID_PHONE`	Format `to` salah	Pakai E.164
`VALIDATION_MISSING_FIELD`	`to` atau `type` kosong	Lengkapi field wajib
`WHATSAPP_SESSION_CLOSED`	Di luar jendela 24 jam	Pakai template
`WHATSAPP_CHANNEL_NOT_FOUND`	`channel_id` tidak valid / tidak aktif, atau punya >1 saluran tapi tidak menyebut `channel_id`	Cek saluran di dashboard
`WHATSAPP_MEDIA_UPLOAD_FAILED`	URL media tidak bisa diakses Meta (404, timeout, ukuran terlalu besar)	Pastikan URL HTTPS, publik, ukuran sesuai limit Meta
`WHATSAPP_SEND_FAILED`	Meta menolak request	Lihat `details` untuk detail. Coba lagi setelah beberapa saat.

Limit ukuran media

Meta WhatsApp Cloud API membatasi ukuran media:

Gambar: 5 MB
Audio: 16 MB
Video: 16 MB
Dokumen: 100 MB

URL kamu harus dapat di-fetch oleh server Meta — pastikan tidak di belakang IP whitelist atau autentikasi.

Kirim Pesan WhatsApp

On this page