WAPRO
description Dokumentasi Lengkap

Dokumentasi API WhatsApp Gateway

Panduan lengkap integrasi WhatsApp API dengan contoh kode PHP, JavaScript, Python. Kirim pesan, media, dan kelola kontak dengan mudah.

info 1. Pengenalan Sistem

WAPRO adalah platform WhatsApp Gateway yang memungkinkan Anda mengirim dan menerima pesan WhatsApp secara terprogram melalui REST API. Sistem ini dirancang untuk:

  • Notifikasi Otomatis: Kirim notifikasi pesanan, pengingat, dan alert ke pelanggan
  • Customer Service: Kelola komunikasi pelanggan secara terpusat
  • Marketing: Broadcast promosi dan informasi ke banyak kontak
  • Integrasi Sistem: Hubungkan dengan website, aplikasi, atau CRM Anda

Fitur Utama

chatKirim Pesan Teks

Kirim pesan teks ke nomor WhatsApp apapun dengan format internasional

imageKirim Media

Dukungan image, video, document, dan audio dengan caption

campaignBroadcast Massal

Kirim pesan ke ribuan kontak sekaligus dengan delay antar pesan

contactsManajemen Kontak

Kelola kontak dengan grup, label, dan pencarian

webhookWebhook Events

Terima notifikasi real-time untuk pesan masuk dan status

auto_modeAuto Reply

Balas pesan otomatis berdasarkan keyword

rocket_launch 2. Quick Start Guide

1

Buat Akun

Daftar gratis di halaman registrasi. Verifikasi email Anda untuk mengaktifkan akun.

2

Tambahkan Device

Masuk ke dashboard, klik "Tambah Device", beri nama, lalu scan QR Code dengan WhatsApp Anda.

3

Generate API Key

Buka menu API Keys, klik "Generate Key". Simpan key tersebut dengan aman.

4

Kirim Pesan Pertama

Gunakan contoh kode di bawah untuk mengirim pesan tes:

curl -X POST https://wapro.dev/api/v1/messages/send \
  -H "X-API-KEY: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"6281234567890","message":"Hello World!"}'

qr_code_scanner 3. Setup Device WhatsApp

Device adalah koneksi WhatsApp yang menghubungkan nomor WhatsApp Anda dengan sistem. Setiap akun dapat memiliki multiple device sesuai paket yang dipilih.

Cara Menambahkan Device

  1. Login ke dashboard WAPRO
  2. Klik menu "Devices" di sidebar
  3. Klik tombol "Tambah Device"
  4. Masukkan nama untuk device (contoh: "HP Marketing")
  5. QR Code akan muncul di layar
  6. Buka WhatsApp di HP Anda → Menu → Linked Devices
  7. Klik "Link a Device" dan scan QR Code
  8. Tunggu status berubah menjadi "Connected"

⚠️ Penting: WhatsApp di HP harus tetap aktif dan terhubung internet. Jika HP mati atau offline, device akan terputus.

Status Device

Connected

Device aktif dan siap kirim pesan

QR Needed

Perlu scan QR untuk menghubungkan

Disconnected

Terputus, perlu reconnect

Connecting

Sedang proses koneksi

code 4. Referensi API

Base URL

https://wapro.dev/api/v1

Daftar Endpoint

MethodEndpointDeskripsi
POST/api/v1/messages/sendKirim pesan teks
POST/api/v1/messages/send-mediaKirim media (image/video/doc/audio)
POST/api/v1/messages/send-bulkKirim pesan massal via API Key (max 1000)
GET/api/v1/messagesRiwayat pesan (paginated)
GET/api/v1/messages/{id}Detail pesan
GET/api/v1/devicesDaftar device
GET/api/v1/devices/{id}/statusStatus detail device
GET/api/v1/contactsDaftar kontak
POST/api/v1/contactsTambah kontak baru
GET/api/v1/contacts/{id}Detail kontak
PUT/api/v1/contacts/{id}Update kontak
DELETE/api/v1/contacts/{id}Hapus kontak
GET/api/v1/quotaCek kuota harian
GET/api/v1/profileInfo akun lengkap

key 5. Autentikasi

Semua request API memerlukan autentikasi menggunakan API Key. API Key harus disertakan dalam header setiap request.

Header Autentikasi

X-API-KEY: wag_live_xxxxxxxxxxxxxxxxxxxxx
# atau
Authorization: Bearer wag_live_xxxxxxxxxxxxxxxxxxxxx

Cara Mendapatkan API Key

  1. Login ke dashboard WAPRO
  2. Klik menu "API Keys" di sidebar
  3. Klik tombol "Generate API Key"
  4. Berikan nama untuk API Key (contoh: "Production Server")
  5. Copy dan simpan API Key yang muncul (hanya ditampilkan sekali!)

⚠️ Penting: API Key hanya ditampilkan satu kali saat dibuat. Jika hilang, Anda harus membuat key baru. Jangan pernah membagikan API Key ke publik atau commit ke repository.

chat 6. Mengirim Pesan

POST/messages/send

Mengirim pesan teks ke nomor WhatsApp tujuan.

Request Body

{
  "to": "6281234567890",
  "message": "Halo, ini pesan tes!",
  "device_id": "uuid-device-opsional"
}

Parameters

ParameterTypeRequiredDescription
tostringYesNomor tujuan (format internasional tanpa +)
messagestringYesIsi pesan (max 4096 karakter)
device_iduuidNoDevice ID, jika tidak diisi akan pakai device pertama yang connected

Response Sukses (200)

{
  "success": true,
  "message": "Pesan berhasil dikirim.",
  "data": {
    "message_id": "uuid-xxx",
    "to": "6281234567890",
    "status": "sent",
    "sent_at": "2026-03-25T16:00:00+07:00"
  }
}
GET/messages

Mendapatkan riwayat pesan dengan pagination.

Query Parameters

ParameterTypeDefaultDescription
device_iduuid-Filter by device
directionstring-inbound/outbound
statusstring-sent/delivered/failed
fromdate-Filter tanggal mulai (YYYY-MM-DD)
to_datedate-Filter tanggal akhir (YYYY-MM-DD)
per_pageinteger20Items per page (max 100)

image 7. Mengirim Media

POST/messages/send-media

Mengirim media (gambar, video, dokumen, audio) dengan caption opsional. Gunakan multipart/form-data untuk upload file.

Request Body (multipart/form-data)

to=6281234567890
type=image
file=[file upload]
caption=Lihat gambar ini!
device_id=uuid-device-opsional

Parameters

ParameterTypeRequiredDescription
tostringYesNomor tujuan
typestringYesimage/video/document/audio
filefile*Upload file (max 100MB). Wajib jika tidak menggunakan media_url.
media_urlurl*URL media publik. Wajib jika tidak menggunakan file upload.
captionstringNoKeterangan media (max 4096 chars)
device_iduuidNoDevice ID

Tipe Media yang Didukung

image

image

JPG, PNG, GIF

videocam

video

MP4, MOV

description

document

PDF, DOC, XLS

mic

audio

MP3, OGG, OPUS

campaign 8. Broadcast Pesan

⚠️ Perhatian: Broadcast hanya tersedia melalui Dashboard Web (login dengan akun). Fitur broadcast tidak tersedia di API publik v1. Gunakan endpoint /messages/send-bulk untuk mengirim pesan massal via API Key.

Fitur Broadcast memungkinkan Anda mengirim pesan ke banyak kontak sekaligus melalui dashboard. Proses pengiriman berjalan di background (queue) dengan delay antar pesan yang dapat dikonfigurasi.

Cara Menggunakan Broadcast

  1. Login ke dashboard WAPRO
  2. Klik menu "Broadcast" di sidebar
  3. Klik "Broadcast Baru"
  4. Pilih device, tulis pesan (gunakan {nama}, {nomor}, {email} untuk personalisasi)
  5. Pilih penerima: grup kontak atau kontak manual
  6. Atur delay antar pesan (detik)
  7. Klik "Kirim Broadcast"

Status Broadcast

scheduled

Menunggu diproses queue

running

Sedang mengirim pesan

completed

Selesai mengirim

failed

Gagal (device offline/dll)

draft

Draft belum dikirim

cancelled

Dibatalkan

💡 Tips: Gunakan delay yang cukup (5–10 detik) untuk menghindari pembatasan rate limit dari WhatsApp. Untuk pengiriman via API, gunakan endpoint POST /api/v1/messages/send-bulk.

contacts 9. Manajemen Kontak

GET/contacts

Mendapatkan daftar kontak dengan pagination dan filter.

Query Parameters

ParameterDescription
searchCari berdasarkan nama atau nomor telepon
group_idFilter berdasarkan grup kontak
per_pageJumlah per halaman (max 100)
POST/contacts

Request Body

{
  "name": "Budi Santoso",
  "phone_number": "6281234567890",
  "email": "budi@example.com",
  "notes": "Pelanggan VIP",
  "tags": ["vip", "jakarta"],
  "group_id": "uuid-group-opsional"
}

Parameters

ParameterTypeRequired
namestringYes
phone_numberstringYes
emailstringNo
notesstringNo
tagsarrayNo
group_iduuidNo
PUT/contacts/{id}

Update data kontak. Semua field opsional, hanya field yang dikirim yang akan diupdate.

DELETE/contacts/{id}

Hapus kontak dari sistem. Aksi ini tidak dapat dibatalkan.

webhook 10. Webhook

Webhook memungkinkan sistem Anda menerima notifikasi real-time saat terjadi event tertentu seperti pesan masuk, pesan terkirim, atau perubahan status device.

Events yang Tersedia

message.received

Pesan masuk diterima

message.sent

Pesan berhasil terkirim

device.connected

Device berhasil terhubung

device.disconnected

Device terputus

Payload Webhook

{
  "event": "message.received",
  "device_id": "uuid-device",
  "device_name": "HP Marketing",
  "timestamp": "2026-03-25T16:00:00+07:00",
  "data": {
    "message_id": "uuid-msg",
    "from": "6281234567890",
    "to": "6289876543210",
    "content": "Halo, ada yang bisa dibantu?",
    "type": "text",
    "timestamp": "2026-03-25T16:00:00+07:00"
  }
}

Headers

X-Webhook-Signature: sha256=xxxxxxxxxx
X-Webhook-Event: message.received
Content-Type: application/json

Verifikasi Signature

Untuk memastikan webhook berasal dari sistem kami, verifikasi signature menggunakan HMAC-SHA256:

// PHP
$payload = file_get_contents('php://input');
$signature = hash_hmac('sha256', $payload, $webhook_secret);
$expected = $_SERVER['HTTP_X_WEBHOOK_SIGNATURE'];

if (!hash_equals('sha256=' . $signature, $expected)) {
    http_response_code(401);
    exit('Invalid signature');
}

Setup Webhook

  1. Login ke dashboard
  2. Klik menu "Webhook" di sidebar
  3. Klik "Tambah Webhook"
  4. Masukkan URL endpoint Anda (harus HTTPS)
  5. Pilih event yang ingin didengarkan
  6. Simpan dan copy Secret Key untuk verifikasi

⚠️ Penting: Endpoint webhook harus merespon dengan HTTP 200 dalam waktu 10 detik. Jika gagal, sistem akan mencoba retry maksimal 3 kali.

auto_mode 11. Auto Reply

Fitur Auto Reply memungkinkan Anda membuat balasan otomatis berdasarkan keyword yang diterima. Cocok untuk customer service otomatis atau FAQ.

Cara Kerja

  1. Pesan masuk diterima oleh device
  2. Sistem memeriksa keyword yang cocok dengan rules yang aktif
  3. Jika cocok, balasan otomatis dikirim
  4. Keyword diproses secara case-insensitive

Tipe Matching

Contains

Cocok jika pesan mengandung keyword

Contoh: "harga" cocok dengan "info harga dong"

Exact

Cocok jika pesan persis sama dengan keyword

Contoh: "harga" hanya cocok dengan "harga"

Starts With

Cocok jika pesan diawali keyword

Contoh: "order" cocok dengan "order 123"

Setup Auto Reply

  1. Login ke dashboard
  2. Klik menu "Auto Reply" di sidebar
  3. Klik "Tambah Auto Reply"
  4. Pilih device yang akan menggunakan auto reply
  5. Masukkan keyword yang ingin dicocokkan
  6. Pilih tipe matching (contains/exact/starts with)
  7. Tulis pesan balasan
  8. Aktifkan dan simpan

💡 Tips: Gunakan keyword yang spesifik untuk menghindari balasan yang tidak relevan. Prioritas diberikan ke rule yang dibuat terakhir jika ada multiple matches.

error 12. Error Handling

HTTP CodeErrorPenyebabSolusi
401UnauthorizedAPI Key tidak valid, dinonaktifkan, atau hilangPeriksa header X-API-KEY
401API Key sudah kadaluarsaTanggal kadaluarsa API Key sudah terlewatBuat API Key baru di menu API Keys
403ForbiddenFitur tidak tersedia di paketUpgrade paket Anda
403IP tidak diizinkanAPI Key dibatasi ke daftar IP tertentuTambahkan IP server Anda ke IP Whitelist
404Not FoundDevice atau resource tidak ditemukanPeriksa ID device
422Validation ErrorData tidak valid atau device offlinePeriksa format data dan status device
429Too Many RequestsKuota pesan harian habisTunggu reset kuota atau upgrade paket
502Bad GatewayWA Engine tidak meresponCoba lagi dalam beberapa saat

Response Format Error

{
  "success": false,
  "error": "Kuota pesan harian habis.",
  "quota": {
    "limit": 50,
    "used": 50,
    "remaining": 0
  }
}

⚠️ Rate Limiting: Selain kuota harian, API memiliki rate limit 60 request per menit. Jika terlampaui, Anda akan menerima response 429.

⚠️ Perhitungan kuota pada pengiriman massal:/messages/send-bulk dan broadcast memotong kuota harian per penerima, bukan per request. Permintaan dengan jumlah penerima melebihi sisa kuota akan ditolak dengan 429 sebelum satu pesan pun terkirim. Bila kuota habis di tengah proses, broadcast berhenti dan berstatus failed — penerima yang belum terkirim tetap berstatus pending. Cek sisa kuota lewat GET /api/v1/quota sebelum mengirim batch besar.

integration_instructions 13. Contoh SDK

PHP (cURL)

<?php

$apiKey = 'wag_live_xxxxx';
$baseUrl = 'https://wapro.dev/api/v1';

// Kirim pesan teks
$ch = curl_init($baseUrl . '/messages/send');
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
curl_setopt($ch, CURLOPT_POST, true);
curl_setopt($ch, CURLOPT_HTTPHEADER, [
    'X-API-KEY: ' . $apiKey,
    'Content-Type: application/json'
]);
curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([
    'to' => '6281234567890',
    'message' => 'Halo dari PHP!'
]));

$response = curl_exec($ch);
$data = json_decode($response, true);

if ($data['success']) {
    echo "Pesan terkirim! ID: " . $data['data']['message_id'];
} else {
    echo "Error: " . $data['error'];
}

curl_close($ch);

PHP (Laravel HTTP Client)

use Illuminate\Support\Facades\Http;

$response = Http::withHeaders([
    'X-API-KEY' => 'wag_live_xxxxx',
])->post('https://wapro.dev/api/v1/messages/send', [
    'to' => '6281234567890',
    'message' => 'Halo dari Laravel!',
]);

if ($response->json('success')) {
    $messageId = $response->json('data.message_id');
    // Pesan terkirim
}

check_circle 14. Best Practices

security Keamanan

  • Simpan API Key di environment variables, jangan hardcode
  • Jangan commit API Key ke repository (gunakan .gitignore)
  • Gunakan HTTPS untuk webhook endpoint
  • Verifikasi webhook signature untuk memastikan keaslian
  • Rotate API Key secara berkala

speed Performa

  • Gunakan bulk send untuk mengirim ke banyak penerima
  • Implementasikan exponential backoff untuk retry
  • Cache quota info untuk mengurangi API calls
  • Gunakan connection pooling untuk HTTP client
  • Proses webhook secara async jika memungkinkan

format_quote Format Pesan

  • Selalu gunakan format internasional tanpa + (628xxx)
  • Bersihkan nomor dari karakter non-numerik sebelum kirim
  • Hindari pesan yang terlalu panjang (max 4096 karakter)
  • Gunakan URL shortener untuk link panjang
  • Personalisasi pesan dengan nama penerima

schedule Rate Limiting

  • Implementasikan delay antar pesan (min 3 detik)
  • Monitor quota usage untuk menghindari limit
  • Queue pesan untuk pengiriman bertahap
  • Hindari burst traffic yang tinggi
  • Kirim pada jam kerja untuk response yang lebih baik

help 15. Frequently Asked Questions

Siap Mulai?

Daftar gratis dan mulai kirim pesan WhatsApp dalam 5 menit.