Dokumentasi API

Gambaran Umum

Base URL untuk seluruh endpoint di bawah ini:

https://pesan-client1.suryacloud.my.id

Setiap request dan response menggunakan JSON (content-type: application/json), kecuali endpoint upload media yang menerima multipart/form-data.

Mulai Cepat

1. Login dengan akun Google — akun dibuat otomatis saat pertama kali login.
2. Di halaman Nomor Saya, klik + Tambah Nomor dan beri nama.
3. Salin API key yang ditampilkan — hanya muncul sekali saat itu juga.
4. Buka dashboard nomor tersebut, scan QR dari WhatsApp di HP (Perangkat Tertaut → Tautkan Perangkat).
5. Panggil endpoint di bawah menggunakan API key nomor tersebut.

Autentikasi

Endpoint pengiriman pesan (/api/send/*, /api/groups, /media/*) diautentikasi dengan API key per-nomor, dikirim lewat header x-api-key (atau parameter query ?key= jika header tidak memungkinkan, mis. embed <img>).

x-api-key: API_KEY_NOMOR_ANDA

Login dashboard (halaman web) menggunakan akun Google, terpisah sepenuhnya dari API key — API key tidak pernah digunakan untuk login ke dashboard, dan sebaliknya.

Mengirim pesan teks ke nomor personal atau grup.

curl -X POST https://pesan-client1.suryacloud.my.id/api/send/text \
  -H "x-api-key: API_KEY_ANDA" \
  -H "content-type: application/json" \
  -d '{"to":"628123456789","message":"Halo dari WA Client 1"}'

const res = await fetch('https://pesan-client1.suryacloud.my.id/api/send/text', {
  method: 'POST',
  headers: { 'x-api-key': 'API_KEY_ANDA', 'content-type': 'application/json' },
  body: JSON.stringify({ to: '628123456789', message: 'Halo dari WA Client 1' }),
});

import requests

requests.post(
    'https://pesan-client1.suryacloud.my.id/api/send/text',
    headers={'x-api-key': 'API_KEY_ANDA'},
    json={'to': '628123456789', 'message': 'Halo dari WA Client 1'},
)

Response 200

{ "success": true, "messageId": "3EB0..." }

Mengirim gambar, video, dokumen, atau audio. Terima file langsung (multipart/form-data) atau URL media yang sudah publik.

curl -X POST https://pesan-client1.suryacloud.my.id/api/send/media \
  -H "x-api-key: API_KEY_ANDA" \
  -F "to=628123456789" \
  -F "file=@/path/ke/gambar.jpg" \
  -F "caption=Contoh gambar"

const form = new FormData();
form.append('to', '628123456789');
form.append('mediaUrl', 'https://contoh.com/gambar.jpg');
form.append('type', 'image');
await fetch('https://pesan-client1.suryacloud.my.id/api/send/media', {
  method: 'POST', headers: { 'x-api-key': 'API_KEY_ANDA' }, body: form,
});

Daftar grup WhatsApp yang diikuti nomor ini.

{ "groups": [ { "id": "1234-5678@g.us", "subject": "Tim Support", "participants": 12 } ] }

Webhook

Dikelola dari halaman Webhook di dashboard nomor Anda (bukan lewat API key). Satu nomor bisa punya lebih dari satu tujuan webhook sekaligus — misalnya satu ke Google Apps Script untuk otomasi, satu lagi ke server OTP login — setiap event dikirim ke semua endpoint yang aktif secara paralel dan independen. Tiap endpoint punya URL dan secret HMAC-nya sendiri, jadi merotasi atau menghapus satu integrasi tidak memengaruhi yang lain.

Event yang Dikirim

Setiap payload otomatis disisipi numberId dan phoneNumber milik nomor WA Client1 Anda sendiri (bukan lawan bicara) — jadi satu URL webhook bisa dipakai untuk beberapa nomor sekaligus dan tetap bisa dibedakan asalnya. Untuk identitas pengirim/lawan bicara, selalu pakai chatId/from, bukan phoneNumber di level atas ini.

{
  "event": "message.incoming",
  "chatId": "628123456789@s.whatsapp.net",
  "from": "628123456789@s.whatsapp.net",
  "isGroup": false,
  "isFromMe": false,
  "type": "text",
  "text": "Halo, ada info?",
  "numberId": "b3f1...",
  "phoneNumber": "6281234567890"
}

Contoh payload message.status — perhatikan nama field-nya chatId, bukan to:

{
  "event": "message.status",
  "messageId": "3EB0...",
  "chatId": "628123456789@s.whatsapp.net",
  "status": "delivered",
  "timestamp": 1786450000,
  "numberId": "b3f1...",
  "phoneNumber": "6281234567890"
}

Contoh payload identity.merged:

{
  "event": "identity.merged",
  "oldChatId": "44294803030187@lid",
  "newChatId": "628123456789@s.whatsapp.net",
  "numberId": "b3f1...",
  "phoneNumber": "6281234567890"
}

Verifikasi Signature

Setiap request webhook menyertakan header x-webhook-signature berisi HMAC-SHA256 dari body mentah, ditandatangani dengan secret milik endpoint tujuan itu sendiri (beda dari API key, dan beda per endpoint kalau Anda punya lebih dari satu — lihat halaman Webhook di dashboard).

const crypto = require('crypto');

function isValid(rawBody, header, secret) {
  const expected = 'sha256=' + crypto.createHmac('sha256', secret).update(rawBody).digest('hex');
  return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(header));
}

import hmac, hashlib

def is_valid(raw_body: bytes, header: str, secret: str) -> bool:
    expected = 'sha256=' + hmac.new(secret.encode(), raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, header)

Rate Limit

Endpoint /api/send/* dibatasi 20 pesan per menit per nomor (bisa berbeda per deployment) untuk mengurangi risiko deteksi otomatisasi oleh WhatsApp. Response melebihi batas mengembalikan status 429 dengan header retry-after.

Kode Error

{ "error": "pesan penjelasan singkat" }