Dokumentasi API

Panduan lengkap integrasi pengiriman pesan WhatsApp SyncWA ke dalam sistem Anda.

Ringkasan & Mulai Cepat

Register & Login

Buat akun dan login ke dashboard.

Hubungkan Device

Tambah device → scan QR WhatsApp.

Buat API Key

Buka device Anda → tab API Keys → buat key.

Kirim Pesan

POST ke /messages/send dengan API Key Anda.

Base URL

url

https://api.syncwa-staging.my.id/api/v1

Autentikasi API Key

Header: x-api-key

Setiap permintaan ke API harus menyertakan header x-api-key yang valid. Anda dapat mendapatkan kunci ini di halaman Pengaturan Device.

Pastikan perangkat Anda dalam status CONNECTED agar pesan dapat dikirimkan ke jaringan WhatsApp secara instan.

Kebijakan Rate Limit

Untuk menjaga stabilitas akun WhatsApp Anda dan sistem kami, kami menerapkan batasan kecepatan pengiriman pesan (Rate Limit) yang bervariasi sesuai dengan paket layanan Anda.

Paket Layanan	Batas Kecepatan
Free Plan	10 Pesan / Menit
Basic Plan	20 Pesan / Menit
Pro Plan	30 Pesan / Menit
Pro Plus Plan	45 Pesan / Menit
Enterprise Plan	60 Pesan / Menit

* Jika Anda melampaui batas ini, permintaan API Anda akan menerima respons error 429 Too Many Requests.

Kirim Pesan Teks

Endpoint ini memerlukan API Key per-device via header x-api-key. Pengiriman ke Grup didukung dengan menggunakan Group JID (ID unik grup) pada parameter to.

POST /messages/send

curl -X POST https://api.syncwa-staging.my.id/api/v1/messages/send \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "to": "628123456789",
    "text": "Halo! Pesan pertama dari SyncWA 🚀"
  }'

Kirim Media

Anda dapat mengirim media dengan mencantumkan URL publik yang dapat diakses langsung oleh server kami.

🖼 Kirim Gambar / Image

type: image

curl -X POST https://api.syncwa-staging.my.id/api/v1/messages/send-media \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "to": "628123456789",
    "type": "image",
    "url": "https://example.com/banner.jpg",
    "caption": "Promo hari ini! 🎉",
    "mimetype": "image/jpeg"
  }'

📄 Kirim Dokumen / PDF

type: document

curl -X POST https://api.syncwa-staging.my.id/api/v1/messages/send-media \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "to": "628123456789",
    "type": "document",
    "url": "https://example.com/invoice.pdf",
    "caption": "Invoice bulan ini",
    "mimetype": "application/pdf",
    "fileName": "invoice-jan-2024.pdf"
  }'

Webhook — Terima Pesan Masuk

Daftarkan URL server Anda agar SyncWA mengirimkan notifikasi real-time setiap ada event. Berikut adalah event utama yang tersedia:

message.incoming

Pesan baru diterima oleh device

message.sent

Pesan API berhasil dikirim oleh Baileys

message.failed

Pesan gagal dikirim (Nomor tidak valid/DC)

session.disconnected

Koneksi WhatsApp terputus

session.connected

Koneksi WhatsApp berhasil (Scan QR)

Retry Failed Webhook

Jika server Anda gagal merespons (non-200), SyncWA akan mencoba mengirimkan ulang (retry) muatan tersebut beberapa kali setiap 5 menit (sesuai paket Anda). Ini memastikan data tetap sampai meskipun server Anda mengalami gangguan sementara.

Dukungan Kustom Header

Anda dapat menambahkan header HTTP kustom (seperti Authorization atau X-Custom-Token) pada setiap permintaan webhook. Fitur ini memungkinkan integrasi yang lebih aman dengan infrastruktur server Anda.

Daftarkan URL server Anda melalui Dashboard > Device Settings > Webhooks. Gunakan fitur Kustom Header untuk autentikasi yang lebih aman antara SyncWA dan server Anda.

Payload yang dikirim SyncWA ke server Anda

json

{
  "event": "message.incoming",
  "payload": {
    "from": "08123456789",
    "text": "Halo, apa kabar?",
    "timestamp": 1735689600,
    "device_id": "8b5f3a0a-..."
  },
  "timestamp": 1735689605123
}

Handler Webhook + Auto-Reply — Contoh Lengkap

Webhook Handler

# Webhook diterima di server Anda — SyncWA mengirim payload ini:
# POST https://your-server.com/webhook

{
  "event": "message.incoming",
  "payload": {
    "from": "08123456789",
    "text": "Halo, saya tertarik dengan produk Anda",
    "timestamp": 1735689600,
    "device_id": "8b5f3a0a-..."
  },
  "timestamp": 1735689605000
}

Error Codes & Troubleshooting

HTTP Code	Keterangan	Solusi
400	Bad Request	Cek payload JSON dan parameter wajib (to, text, type).
401	Unauthorized	API Key salah atau tidak dikirim dalam header x-api-key.
403	Forbidden	Paket Anda tidak mendukung fitur ini (misal: Media API di paket Free).
404	Not Found	Nomor device salah atau endpoint tidak ditemukan.
429	Too Many Requests	Rate limit tercapai. Kurangi frekuensi pengiriman atau upgrade paket.
500	Internal Server Error	Terjadi masalah pada server. Hubungi dukungan teknis.

Struktur Respons Error

json

{
  "success": false,
  "message": "Rate limit per minute exceeded. Please slow down.",
  "errors": []
}