Integrasi WhatsApp

Layanan WhatsApp Notification Gateway ini menyediakan antarmuka REST API yang memungkinkan aplikasi internal maupun pihak ketiga untuk mengirimkan pesan notifikasi secara otomatis ke pengguna melalui platform WhatsApp.

Integrasi ini dirancang sebagai middleware yang menjembatani sistem Anda dengan protokol WhatsApp Web Multi-device, memungkinkan pengiriman informasi yang cepat, personal, dan real-time.

Fitur Utama

Layanan ini mendukung beberapa kapabilitas pengiriman pesan, antara lain:

• Text Messaging: Pengiriman pesan teks standar dengan dukungan pemformatan (tebal, miring, monospace).
• Media Messaging: Pengiriman file gambar (JPG/PNG) yang disertai dengan caption.
• Secure Access: Dilindungi menggunakan standar Basic Authentication.

Kapan Menggunakan Layanan Ini?

API ini ideal digunakan untuk skenario komunikasi satu arah (server-to-user), seperti:

• Pengiriman kode OTP (One Time Password).
• Notifikasi status transaksi atau layanan publik.
• Peringatan sistem (System Alerting) untuk tim teknis.
• Pengiriman bukti laporan atau tiket antrian dalam bentuk gambar.

Disclaimer Teknis

Layanan ini berjalan di atas protokol WhatsApp Web Multi-device (Unofficial Wrapper).

• Anti-Spam: Gunakan layanan ini dengan bijak. Pengiriman pesan massal (bulk) yang agresif ke nomor yang tidak menyimpan kontak sender berisiko menyebabkan pemblokiran nomor oleh pihak WhatsApp.

Base URL

Pastikan Anda menggunakan Base URL yang sesuai dengan environment (Staging/Production).

• Base URL: https://dev.denpasarkota.go.id/whatsapp

Alur Integrasi (Sequence Diagram)

Berikut adalah alur pengiriman pesan dari aplikasi klien ke WhatsApp Gateway:

Autentikasi

API ini menggunakan mekanisme Basic Authentication. Setiap permintaan (request) ke API harus menyertakan header Authorization yang valid.

Kredensial terdiri dari username dan password yang digabungkan dengan format username:password.

Credentials

Pastikan Anda tidak menyimpan kredensial (Username & Password) langsung di dalam source code frontend (client-side). Selalu lakukan request dari sisi server (backend) untuk menjaga keamanan.

Format Header

Authorization: Basic <base64_encoded_credentials>

1. Mengirim Pesan Teks

Endpoint ini digunakan untuk mengirim pesan teks biasa ke nomor tujuan. Mendukung formatting teks dasar WhatsApp (Bold, Italic, Strikethrough, ```Monospace```).

POST /send/message

Request Body

Format body menggunakan JSON.

Parameter	Tipe	Wajib	Deskripsi
phone	string	Ya	Nomor telepon tujuan dengan kode negara (tanpa + atau 0). Contoh: 6281234567890.
message	string	Ya	Isi pesan teks yang akan dikirimkan.

Contoh Request

cURL

# Gunakan flag -u untuk Basic Auth (curl otomatis melakukan encode)
curl -X POST https://dev.denpasarkota.go.id/whatsapp/send/message \
-u "username:password" \
-H "Content-Type: application/json" \
-d '{
    "phone": "6281234567890",
    "message": "Halo, ini pesan dengan autentikasi."
}'

Node.js (Axios)

const axios = require('axios');

axios.post('https://dev.denpasarkota.go.id/whatsapp/send/message', 
  {
    phone: '6281234567890',
    message: 'Halo, ini pesan dengan autentikasi.'
  },
  {
    auth: {
      username: 'username_anda',
      password: 'password_anda'
    }
  }
).then(response => console.log(response.data))
 .catch(error => console.error(error));

Response Sukses (200 OK)

{
  "status": true,
  "data": {
    "id": "3EB0...",
    "status": "PENDING",
    "message": "Message sent successfully"
  }
}

---

2. Mengirim Pesan Gambar

Endpoint ini digunakan untuk mengirimkan file gambar (berupa upload file lokal atau melalui URL) disertai dengan caption dan pengaturan spesifik lainnya.

POST /send/image

Request Body

Format request menggunakan multipart/form-data.

Parameter	Tipe	Wajib	Deskripsi
phone	string	Ya	Nomor telepon tujuan dengan kode negara. Contoh: 6281234567890@s.whatsapp.net atau 6281234567890.
image	binary	Opsional*	File gambar yang akan diunggah. (Wajib jika tidak menggunakan image_url)
image_url	string	Opsional*	Tautan URL gambar. Contoh: https://example.com/image.jpg. (Wajib jika tidak menggunakan image)
caption	string	Tidak	Teks deskripsi atau caption yang menyertai gambar.
view_once	boolean	Tidak	Atur ke true agar gambar hanya dapat dilihat satu kali oleh penerima. Default: false.
compress	boolean	Tidak	Atur ke true untuk melakukan kompresi ukuran gambar sebelum dikirim. Default: false.
duration	integer	Tidak	Durasi (dalam detik) sebelum pesan menghilang (disappearing message). Contoh: 3600 (1 jam).
is_forwarded	boolean	Tidak	Menandai pesan seolah-olah diteruskan dari percakapan lain. Default: false.

Praktik Terbaik Pengiriman Gambar

Gunakan parameter compress: true jika Anda mengirim gambar beresolusi tinggi untuk menghindari timeout atau kegagalan pengiriman pada jaringan lambat.

Contoh Request

cURL

# Mengirim file gambar lokal beserta caption dan fitur view once
curl -X POST https://dev.denpasarkota.go.id/whatsapp/send/image \
-u "username:password" \
-H "Content-Type: multipart/form-data" \
-F "phone=6281234567890" \
-F "caption=Ini bukti laporan Anda" \
-F "view_once=true" \
-F "compress=true" \
-F "image=@/path/to/gambar.jpg"

Node.js (Axios)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('phone', '6281234567890');
form.append('caption', 'Ini bukti laporan Anda');
form.append('view_once', 'true');
form.append('compress', 'true');
// Membaca file dari sistem lokal
form.append('image', fs.createReadStream('/path/to/gambar.jpg'));

axios.post('https://dev.denpasarkota.go.id/whatsapp/send/image', form, {
  auth: {
    username: 'username_anda',
    password: 'password_anda'
  },
  headers: {
    ...form.getHeaders()
  }
}).then(response => console.log(response.data))
  .catch(error => console.error(error));

Contoh Responses

Sukses (200 OK)

{
  "status": true,
  "data": {
    "id": "3EB0...",
    "status": "PENDING",
    "message": "Image sent successfully"
  }
}

Gagal - Bad Request (400)

{
  "status": false,
  "message": "Bad Request: Parameter phone dan image/image_url wajib diisi."
}

Kompresi Gambar

Disarankan untuk melakukan kompresi gambar sebelum dikirim ke API untuk menghindari timeout atau kegagalan pengiriman pada jaringan yang lambat.

---

3. Mengirim Pesan File

Peringatan (Troubleshooting Content-Type)

PENTING: Saat melakukan pengujian di client seperti Postman atau modifikasi header manual, jangan pernah mengunci atau mengisi secara hardcode header Content-Type: multipart/form-data tanpa boundary yang valid.

• Di cURL, menggunakan flag -F atau --form secara otomatis menyusun tipe multipart beserta boundary-nya yang tepat.
• Di Node.js (Axios), pastikan menggunakan penanda ...form.getHeaders() untuk menyertakan boundary dynamic.

Kelalaian dalam pengaturan ini akan memicu error 500 Internal Server Error dengan pesan "request Content-Type has bad boundary or is not multipart/form-data".

---

Request Body (multipart/form-data)

Anda dapat mengirimkan file menggunakan salah satu dari dua metode alternatif berikut: Menggunakan File URL atau Mengunggah File Fisik secara langsung.

Parameter:

Parameter	Tipe Data	Wajib	Contoh / Pilihan	Deskripsi
phone	Text (String)	Ya	6281238921xxx	Nomor WhatsApp tujuan lengkap dengan kode negara tanpa tanda +.
caption	Text (String)	Tidak	kirim file ni pak	Teks pesan pendamping/caption file.
file_url	Text (String)	Alternatif	https://raw.githubusercontent.com/.../logo.png	URL valid langsung ke file yang ingin diunduh dan dikirim oleh sistem.
file	File (Binary)	Alternatif	pemandangan.jpg	File fisik yang diunggah langsung dari penyimpanan lokal komputer/server Anda.
reply_message_id	Text (String)	Tidak	3EB089B....	ID pesan jika ingin membalas (reply) pesan spesifik tertentu.
is_forwarded	Boolean	Tidak	false	Menandai apakah pesan ini diteruskan atau tidak.
duration	Integer	Tidak	0	Durasi disappearing message dalam detik (0 = non-aktif).

---

Contoh Respons API

Respons Sukses (200 OK)

{
  "code": "SUCCESS",
  "message": "Document sent to 6281238921xxx@s.whatsapp.net (server timestamp: 2026-07-13 05:52:09 +0000 UTC)",
  "results": {
    "message_id": "3EB030C....",
    "status": "Document sent to 6281238921xxx@s.whatsapp.net (server timestamp: 2026-07-13 05:52:09 +0000 UTC)"
  }
}

---

Contoh Implementasi

cURL

# Opsi A: Mengirim file menggunakan remote URL direktori internet
curl -X POST https://dev.denpasarkota.go.id/whatsapp/send/file
-u "username_anda:password_anda"
-F "phone=6281238921xxx"
-F "caption=kirim file ni pak"
-F "file_url=https://raw.githubusercontent.com/xxx/logo.png"

# Opsi B: Mengirim file fisik langsung dari storage lokal Anda
curl -X POST https://dev.denpasarkota.go.id/whatsapp/send/file
-u "username_anda:password_anda"
-F "phone=6281238921xxx"
-F "caption=kirim file fisik ni pak"
-F "file=@/path/to/pemandangan.jpg"

Node.js (Axios)

const axios = require('axios');
const FormData = require('form-data');
const fs = require('fs');

const form = new FormData();
form.append('phone', '6281238921xxx');
form.append('caption', 'kirim file ni pak');

// PILIHAN A: Menggunakan file_url (Pilih salah satu dengan Pilihan B)
form.append('file_url', 'https://raw.githubusercontent.com/xxx/main/logo.png');

// PILIHAN B: Menggunakan file fisik lokal (Aktifkan baris di bawah jika ingin upload file lokal)
// form.append('file', fs.createReadStream('/path/to/pemandangan.jpg'));

axios.post('https://dev.denpasarkota.go.id/whatsapp/send/file', form, {
  auth: {
    username: 'username_anda',
    password: 'password_anda'
  },
  headers: {
    ...form.getHeaders() // Otomatis menyusun Content-Type multipart/form-data beserta boundary yang valid
  }
}).then(response => console.log(response.data))
  .catch(error => console.error(error));