Panduan API WhatsApp
Program WhatsApp Anda bisa berjalan di WiTalk dengan kode yang sama. Permintaan, jawaban, kode error, dan webhook-nya sama. Anda hanya mengganti isi pengaturan:
| Di WhatsApp | Di WiTalk | |
|---|---|---|
| Alamat | https://graph.facebook.com/v26.0 | https://<server>/api/v1 |
| Phone number ID | dari Meta | 15 angka, dari admin WiTalk |
| WABA ID | dari Meta | 15 angka, dari admin WiTalk |
| Access token | EAA... | wtb_..., dari admin WiTalk |
| App secret | dari Meta | dari admin WiTalk, untuk memeriksa webhook |
| Nomor penerima | nomor WhatsApp | nomor kantor karyawan, nama pengguna, NIK, atau email |
Angka versi boleh ikut, boleh tidak. https://<server>/api/v1/v26.0 juga jalan, jadi base URL yang sudah menyimpan versi tetap cocok.
Coba dalam 2 Menit
Siapkan empat nilai ini dulu:
export BASE="https://chat.perusahaan.co.id/api/v1"
export TOKEN="wtb_isi-token-dari-admin"
export PHONE_ID="961617848123380"
export WABA_ID="310406180682429"
1. Pastikan token berjalan.
curl "$BASE/$PHONE_ID" -H "Authorization: Bearer $TOKEN"
Bila berhasil, jawabannya berisi verified_name dan id.
2. Kirim pesan pertama. Ganti budi dengan nama pengguna WiTalk Anda sendiri.
curl "$BASE/$PHONE_ID/messages" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"messaging_product":"whatsapp","to":"budi","type":"text","text":{"body":"Halo dari program"}}'
Buka aplikasi WiTalk. Pesannya sudah masuk.
Jawabannya sama dengan WhatsApp:
{
"messaging_product": "whatsapp",
"contacts": [{ "input": "budi", "wa_id": "6281234567890" }],
"messages": [{ "id": "wamid.HBgLNjI4MTIzNDU2Nzg5MBUCABIYFDNB", "message_status": "accepted" }]
}
Simpan id pesan bila perlu. Nilai itu dipakai untuk balasan, reaksi, tandai dibaca, dan muncul lagi di webhook status.
3. Sambungkan webhook untuk menerima balasan. Kode verifikasi yang sudah Anda tulis untuk WhatsApp bisa dipakai apa adanya. Daftarkan alamatnya:
curl "$BASE/$WABA_ID/subscribed_apps" \
-H "Authorization: Bearer $TOKEN" \
-H "Content-Type: application/json" \
-d '{"override_callback_uri":"https://bot.perusahaan.co.id/webhook","verify_token":"rahasia_anda"}'
Server langsung memeriksa alamat itu seperti Meta. Admin juga bisa mengisinya di console. Sekarang balas pesan tadi dari aplikasi, dan balasannya sampai di webhook Anda.
Selesai. Bagian berikutnya berisi semua jenis pesan.
Penerima
Karena penerimanya karyawan, kolom to boleh berisi:
- nomor kantor karyawan dalam bentuk apa pun:
6281234567890,081234567890,+62 812-3456-7890; - nama pengguna WiTalk, dengan atau tanpa
@; - NIK karyawan;
- email kantor karyawan.
Di jawaban dan di webhook, wa_id seorang karyawan adalah nomor kantornya dalam format internasional (628...) bila hanya dia yang memakai nomor itu, dan nama penggunanya bila tidak. Keduanya bisa dipakai lagi sebagai to. Nomor yang tidak terdaftar dijawab kode 133010; nomor yang dipakai lebih dari satu akun dijawab 131026 dengan saran memakai nama pengguna.
Jenis Pesan
Semua dikirim ke POST /{phone-number-id}/messages dengan messaging_product: "whatsapp".
Teks
{
"messaging_product": "whatsapp",
"recipient_type": "individual",
"to": "6281234567890",
"type": "text",
"text": { "preview_url": true, "body": "Halo Budi, slip gaji Oktober sudah terbit: https://hris.contoh.co.id/slip" }
}
Teks paling panjang 4.000 karakter. Dengan preview_url: true, tautan pertama ditampilkan dengan pratinjaunya.
Gambar, Dokumen, Audio, Video, Stiker
Media disebut dengan id hasil unggahan (lihat Media) atau dengan link https yang diambil server. Tautan yang sama dalam satu jam diambil sekali saja, jadi siaran ke banyak orang tidak mengunduh berulang.
{
"messaging_product": "whatsapp",
"to": "budi.santoso",
"type": "document",
"document": { "link": "https://contoh.co.id/pengumuman.pdf", "caption": "Pengumuman libur", "filename": "pengumuman.pdf" }
}
| Jenis | Tampil di WiTalk sebagai |
|---|---|
image (JPEG, PNG, WebP) | foto, dengan caption |
document | dokumen dengan nama berkasnya, dengan caption |
audio Ogg/Opus | pesan suara |
audio lainnya, video | dokumen yang bisa diunduh dan diputar, dengan caption |
sticker | foto |
Lokasi
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "location",
"location": { "latitude": -6.2088, "longitude": 106.8456, "name": "Kantor Pusat", "address": "Jl. Sudirman No. 1, Jakarta" }
}
Kontak
Satu kontak yang nomornya (wa_id atau phone) terdaftar di server tampil sebagai kartu kontak WiTalk yang bisa langsung diajak chat. Kontak lain tampil sebagai teks berisi nama, nomor, dan email.
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "contacts",
"contacts": [{ "name": { "formatted_name": "Citra (IT Support)" }, "phones": [{ "phone": "+62 811 2222 3333", "wa_id": "6281122223333" }] }]
}
Membalas Pesan Tertentu
Tambahkan context.message_id berisi wamid pesan di chat yang sama. Pesan dari chat lain dijawab kode 131009.
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"context": { "message_id": "wamid.HBgLNjI4MTIzNDU2Nzg5MBUCABIYFDNB" },
"type": "text",
"text": { "body": "Baik, kami proses hari ini." }
}
Reaksi
emoji kosong ("") menghapus reaksi.
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "reaction",
"reaction": { "message_id": "wamid.HBgLNjI4MTIzNDU2Nzg5MBUCABIYFDNB", "emoji": "👍" }
}
Tombol Balasan
Satu sampai tiga tombol. Judul tombol paling panjang 20 karakter, isi paling panjang 1.024 karakter. Header boleh teks, gambar, video, atau dokumen.
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "interactive",
"interactive": {
"type": "button",
"header": { "type": "text", "text": "Konfirmasi kehadiran" },
"body": { "text": "Apakah Anda hadir di rapat besok pukul 09.00?" },
"footer": { "text": "Tim HRD" },
"action": {
"buttons": [
{ "type": "reply", "reply": { "id": "hadir", "title": "Hadir" } },
{ "type": "reply", "reply": { "id": "izin", "title": "Izin" } }
]
}
}
}
Saat karyawan menekan tombol, webhook menerima pesan type: "interactive" berisi button_reply (lihat Webhook).
Daftar Pilihan
Sampai 10 bagian dan 10 baris; judul baris paling panjang 24 karakter, keterangan 72.
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "interactive",
"interactive": {
"type": "list",
"header": { "type": "text", "text": "Pengajuan cuti" },
"body": { "text": "Pilih jenis cuti yang ingin diajukan." },
"action": {
"button": "Pilih cuti",
"sections": [
{ "title": "Cuti", "rows": [
{ "id": "tahunan", "title": "Cuti tahunan", "description": "Sisa 8 hari" },
{ "id": "sakit", "title": "Cuti sakit" }
] }
]
}
}
}
Tombol Tautan
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "interactive",
"interactive": {
"type": "cta_url",
"body": { "text": "Slip gaji Oktober sudah tersedia." },
"action": { "name": "cta_url", "parameters": { "display_text": "Buka slip", "url": "https://hris.contoh.co.id/slip/2610" } }
}
}
Aplikasi WiTalk versi lama yang belum mengenal tombol tetap menampilkan seluruh isi pesan sebagai teks, termasuk pilihan dan tautannya.
Template
{
"messaging_product": "whatsapp",
"to": "6281234567890",
"type": "template",
"template": {
"name": "pengingat_absen",
"language": { "code": "id" },
"components": [
{ "type": "header", "parameters": [{ "type": "text", "text": "Budi" }] },
{ "type": "body", "parameters": [{ "type": "text", "text": "23 Oktober" }, { "type": "text", "text": "absen pulang" }] },
{ "type": "button", "sub_type": "quick_reply", "index": "0", "parameters": [{ "type": "payload", "payload": "SUDAH_ABSEN" }] },
{ "type": "button", "sub_type": "url", "index": "1", "parameters": [{ "type": "text", "text": "2310" }] }
]
}
}
Parameter text, currency (dipakai fallback_value), dan date_time (dipakai fallback_value) diterima, juga parameter bernama (parameter_name) untuk template dengan parameter_format: "NAMED". Header gambar, video, atau dokumen diisi parameter image, video, atau document berisi id atau link. Tombol balas cepat menjadi tombol di pesan; tombol URL dan nomor telepon menjadi tautan. Jumlah parameter yang tidak cocok dijawab kode 132000, template yang tidak ada dijawab 132001.
Di WiTalk tidak ada jendela layanan 24 jam: pesan biasa dan template sama-sama boleh dikirim kapan saja.
Tandai Dibaca dan Indikator Mengetik
{
"messaging_product": "whatsapp",
"status": "read",
"message_id": "wamid.HBgLNjI4MTIzNDU2Nzg5MBUCABIYFDNB",
"typing_indicator": { "type": "text" }
}
Dijawab { "success": true }. Karyawan melihat centang biru pada pesannya, dan dengan typing_indicator melihat akun resmi sedang mengetik.
Melacak Pesan
Isi biz_opaque_callback_data saat mengirim, paling panjang 512 karakter. Nilainya muncul lagi di semua webhook status pesan itu, sehingga Anda tahu pesan itu milik pesanan atau proses yang mana.
Media
| Permintaan | Fungsi |
|---|---|
POST /{phone-number-id}/media | unggah berkas (multipart: file, type, messaging_product), dijawab { "id": "..." } |
GET /{media-id} | url, mime_type, sha256, file_size, id |
GET {url} | isi berkas, dengan header Authorization yang sama |
DELETE /{media-id} | hapus unggahan yang belum dikirim, dijawab { "success": true } |
curl -X POST "$BASE/$PHONE_ID/media" \
-H "Authorization: Bearer $TOKEN" \
-F messaging_product=whatsapp -F type=image/jpeg -F file=@denah.jpg
Satu media id boleh dikirim ke banyak orang. Unggahan yang tidak pernah dikirim dihapus sesudah 24 jam. Media yang dikirim karyawan ke akun resmi (di webhook) diambil dengan cara yang sama: GET /{media-id}, lalu unduh url-nya. Batas ukuran: foto 16 MB, berkas lain 95 MB.
Template Pesan
| Permintaan | Fungsi |
|---|---|
POST /{waba-id}/message_templates | buat template: name, language, category, components, parameter_format |
GET /{waba-id}/message_templates | daftar, dengan filter name, language, category, limit, after |
GET /{template-id} | satu template |
POST /{template-id} | ubah components atau category |
DELETE /{waba-id}/message_templates?name=... | hapus semua bahasa template itu, atau satu saja dengan hsm_id |
Komponen HEADER (TEXT, IMAGE, VIDEO, DOCUMENT), BODY, FOOTER, dan BUTTONS (QUICK_REPLY, URL, PHONE_NUMBER, COPY_CODE) mengikuti aturan WhatsApp, termasuk {{1}}, {{2}}, atau {{nama}}. WiTalk tidak meninjau template: status template baru langsung APPROVED.
{
"name": "pengingat_absen",
"language": "id",
"category": "UTILITY",
"components": [
{ "type": "HEADER", "format": "TEXT", "text": "Halo {{1}}" },
{ "type": "BODY", "text": "Absen Anda tanggal {{1}} belum lengkap ({{2}})." },
{ "type": "FOOTER", "text": "Tim HRD" },
{ "type": "BUTTONS", "buttons": [
{ "type": "QUICK_REPLY", "text": "Sudah" },
{ "type": "URL", "text": "Buka HRIS", "url": "https://hris.contoh.co.id/absen/{{1}}" }
] }
]
}
Dijawab { "id": "...", "status": "APPROVED", "category": "UTILITY" }.
Template kode OTP (kategori AUTHENTICATION) memakai bentuk WhatsApp: cukup isi add_security_recommendation, code_expiration_minutes, dan tombol OTP. Server menulis kalimatnya, dan kode dikirim sebagai satu parameter body. Setiap template baru juga mengirim webhook message_template_status_update dengan event: "APPROVED".
Webhook
Verifikasi Alamat
Saat admin menyimpan alamat webhook, server memanggilnya sekali seperti Meta:
GET https://alamat-anda/webhook?hub.mode=subscribe&hub.verify_token=<verify token>&hub.challenge=1158201444
Alamat itu harus menjawab HTTP 200 dengan isi persis nilai hub.challenge. Kode verifikasi yang sudah Anda tulis untuk WhatsApp bisa dipakai apa adanya:
app.get('/webhook', (req, res) => {
if (req.query['hub.mode'] === 'subscribe' && req.query['hub.verify_token'] === process.env.VERIFY_TOKEN) {
return res.status(200).send(req.query['hub.challenge']);
}
res.sendStatus(403);
});
Tanda Tangan
Setiap kiriman webhook berupa POST JSON dengan header X-Hub-Signature-256: sha256=<HMAC-SHA256 isi mentah dengan app secret>, sama seperti di Meta:
const crypto = require('crypto');
function signatureOk(rawBody, header) {
const expected = 'sha256=' + crypto.createHmac('sha256', process.env.APP_SECRET).update(rawBody).digest('hex');
return header && crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected));
}
Jawab dengan HTTP 2xx secepatnya. Kiriman yang gagal (bukan 2xx, atau tidak dijawab dalam 10 detik) dicoba lagi dengan jeda yang makin panjang, dari 15 detik sampai paling lama 1 jam, selama 24 jam.
Server juga mengirim header lama X-Hub-Signature (SHA-1), seperti Meta.
Pesan Masuk
Bentuknya sama dengan WhatsApp: object, entry[].id (WABA ID), dan changes[].value dengan field: "messages".
{
"object": "whatsapp_business_account",
"entry": [{
"id": "310406180682429",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "021 5550 100", "phone_number_id": "961617848123380" },
"contacts": [{ "profile": { "name": "Budi Santoso" }, "wa_id": "6281234567890" }],
"messages": [{
"from": "6281234567890",
"id": "wamid.spQqtgq_RX2uGlwhpanO5gAAAAw",
"timestamp": "1792892875",
"type": "text",
"text": { "body": "Saya ada pertanyaan soal lembur." }
}]
}
}]
}]
}
type | Isi |
|---|---|
text | text.body |
image, video, document | id, mime_type, sha256, caption, dan filename untuk dokumen |
audio | pesan suara: id, mime_type, voice: true |
location | latitude, longitude, name, address |
contacts | kartu kontak karyawan, dengan wa_id |
interactive | jawaban tombol (button_reply: id, title) atau daftar (list_reply: id, title, description) |
button | jawaban tombol balas cepat template: payload, text |
reaction | message_id dan emoji (tanpa emoji bila reaksi dihapus) |
unsupported | jenis pesan WiTalk yang tidak ada di WhatsApp, misalnya polling |
Pesan yang membalas pesan lain membawa context.id (wamid pesan yang dibalas) dan context.from; pesan yang diteruskan membawa context.forwarded: true.
Status Pesan
{
"object": "whatsapp_business_account",
"entry": [{
"id": "310406180682429",
"changes": [{
"field": "messages",
"value": {
"messaging_product": "whatsapp",
"metadata": { "display_phone_number": "021 5550 100", "phone_number_id": "961617848123380" },
"statuses": [{
"id": "wamid.spQqtgq_RX2uGlwhpanO5gAAAAs",
"status": "read",
"timestamp": "1792892880",
"recipient_id": "6281234567890",
"conversation": { "id": "b2942ab60abf457dae1a5c21a5a9cee6", "origin": { "type": "service" } },
"pricing": { "billable": false, "pricing_model": "PMP", "category": "service", "type": "free_customer_service" }
}]
}
}]
}]
}
sent dikirim begitu pesan tersimpan, delivered saat pesan sampai di ponsel karyawan, dan read saat dibaca (membalas juga dihitung membaca). Di WiTalk tidak ada biaya: billable selalu false.
Profil, Nomor, dan Blokir
| Permintaan | Fungsi |
|---|---|
GET /{phone-number-id} | verified_name, display_phone_number, quality_rating, id |
GET /{waba-id}/phone_numbers | nomor akun resmi |
GET /{phone-number-id}/whatsapp_business_profile | profil bisnis |
POST /{phone-number-id}/whatsapp_business_profile | ubah profil bisnis |
POST /{phone-number-id}/register, deregister | selalu { "success": true }, agar skrip penyiapan WhatsApp tetap berjalan |
Nama dan foto akun resmi diatur admin di aplikasi.
whatsapp_business_profile juga menyimpan address, email, vertical, dan websites.
| Permintaan | Fungsi |
|---|---|
GET /me | akun yang memegang token ini |
GET /debug_token | memastikan token masih berlaku |
POST /{phone-number-id}/request_code, verify_code | selalu { "success": true }, agar skrip penyiapan tetap berjalan |
POST /{waba-id}/subscribed_apps | tanpa isi: { "success": true }. Dengan override_callback_uri dan verify_token: memasang webhook |
DELETE /{waba-id}/subscribed_apps | melepas webhook |
GET, POST, DELETE /{phone-number-id}/block_users | daftar, blokir, dan buka blokir karyawan |
Yang Berbeda dari WhatsApp
Bagian ini penting dibaca sebelum pindah.
- Penerima hanya karyawan yang terdaftar di server WiTalk perusahaan Anda; tidak ada nomor di luar itu.
- Tidak ada Business Manager, verifikasi bisnis, peninjauan template, tingkat kualitas, jendela 24 jam, atau tagihan.
- Pesan
product,product_list,catalog_message,flow,location_request_message,address_message, dan panggilan belum tersedia (kode131051). - Video dan audio selain Ogg/Opus dikirim sebagai dokumen yang bisa diputar.
- Grup tidak bisa dikirimi lewat API WhatsApp. Pakai API Telegram untuk bot di grup.
- Dokumen memakai
filenamehanya bila berkasnya belum pernah dikirim. - Template carousel dan penawaran terbatas belum tersedia.
- Unggah bertahap (
/{app-id}/uploads) dan pengaturan webhook lewat Meta App belum tersedia; pakaisubscribed_appsatau console.
Kalau Ada Masalah
Bentuk error sama dengan WhatsApp, jadi penanganan error Anda tetap berjalan.
Bentuk error sama dengan WhatsApp:
{
"error": {
"message": "(#131009) Parameter value is not valid",
"type": "OAuthException",
"code": 131009,
"error_data": { "messaging_product": "whatsapp", "details": "context.message_id is not a message of this chat" },
"fbtrace_id": "AbCdEfGh123"
}
}
| Kode | HTTP | Arti |
|---|---|---|
3 | 403 | API bisnis belum dinyalakan di server ini |
190 | 401 | token salah, dicabut, atau tidak ada |
100 | 400 | parameter tidak sah; dengan error_subcode: 33 ID di alamat bukan milik token ini |
131008 | 400 | parameter wajib tidak ada |
131009 | 400 | nilai parameter tidak sah |
131026 | 400 | pesan tidak bisa dikirim (karyawan memblokir akun resmi atau akunnya sudah dihapus) |
131031 | 403 | akun resmi dinonaktifkan admin |
131051 | 400 | jenis pesan tidak tersedia di WiTalk |
131052 | 400 | media di link tidak bisa diambil |
131053 | 400 | media tidak bisa dipakai (salah id, kedaluwarsa, terlalu besar, atau jenisnya tidak didukung) |
130429 | 429 | batas kecepatan akun tercapai |
131056 | 429 | terlalu banyak pesan ke satu penerima |
132000 | 400 | jumlah parameter template tidak cocok |
132001 | 404 | template tidak ada untuk nama dan bahasa itu |
133010 | 400 | penerima tidak terdaftar di server ini |
131000 | 500 | kesalahan lain di server |
2 | 503 | layanan sedang tidak tersedia, coba lagi |
Jawaban 429 membawa header Retry-After.
Kode 2200 berarti alamat webhook gagal diperiksa: pastikan alamatnya menjawab hub.challenge dengan benar.
Batas
| Batas | Nilai |
|---|---|
| Pesan per akun resmi | 600 per menit |
| Pesan ke satu penerima | 10 per menit |
| Unggah media per akun resmi | 120 per 10 menit |
| Semua permintaan per akun resmi | 600 per menit |
| Token salah per alamat IP | 30 per menit |
Batas ini menjaga karyawan dari pesan berlebihan. Siaran ke seluruh karyawan tetap bisa, dengan kecepatan 10 pesan per detik.