Dokumentasi API

Kirim dan terima pesan WhatsApp dari aplikasi Anda memakai nomor Anda sendiri. Layanan ini memakai koneksi tidak resmi, jadi baca juga risiko dan batasannya.

Mulai

• Buat akun dan tambahkan nomor di dashboard, lalu pindai kode QR dari WhatsApp (Perangkat tertaut).
• Buat kunci API di menu Kunci API. Kunci diawali wgk_ dan hanya tampil sekali.
• Semua alamat di bawah relatif terhadap alamat API Anda; contoh memakai https://api.domain-anda.com.

Autentikasi

Kirim kunci di header Authorization: Bearer wgk_.... Kunci punya izin (misalnya hanya kirim pesan), bisa diganti kuncinya, dan bisa dicabut. Jangan menaruh kunci di aplikasi yang dilihat pengguna (browser atau aplikasi HP); panggil API dari server Anda.

Kirim pesan

POST /api/v1/message/send menaruh pesan ke antrean dan langsung menjawab 202. Itu berarti diterima, belum terkirim; pantau statusnya lewat webhook atau endpoint status. Pesan promosi hanya dapat dikirim kepada penerima yang sudah opt-in.

curl -X POST https://api.domain-anda.com/api/v1/message/send \
  -H "Authorization: Bearer wgk_KUNCI_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"device_key":"WAPI-XXXXXXXX","to":"6281234567890","message":"Halo dari API"}'

Balasan yang menanggapi pesan masuk pelanggan dapat memakai reply_to_message_id tanpa perintah START. Jalur ini hanya berlaku untuk chat langsung yang sama, dalam 24 jam sejak pesan masuk, dan tetap menghormati STOP. Pesan proaktif dan campaign tetap memerlukan bukti opt-in; tanpa consent tersimpan, API mengembalikan 409 RECIPIENT_CONSENT_REQUIRED, sedangkan setelah opt-out API mengembalikan 409 RECIPIENT_OPTED_OUT. Broadcast melaporkan penolakan per penerima.

Penerima tidak harus mengirim START bila persetujuan WhatsApp sudah dikumpulkan di alur signup/checkout Anda. Setelah pengguna secara aktif menyetujui pemberitahuan WhatsApp, panggil endpoint berikut dari server Anda (bukan browser) dengan API key berscope content:write. Endpoint ini hanya mencatat bukti izin; pengiriman pesan tetap dilakukan lewat endpoint pesan. Jangan panggil hanya karena Anda memiliki nomor telepon.

curl -X POST https://api.domain-anda.com/api/v1/contacts/signup-consent \
  -H "Authorization: Bearer wgk_KUNCI_ANDA" \
  -H "Content-Type: application/json" \
  -d '{"phone_number":"6281234567890","consent_text":"Saya setuju menerima notifikasi status pesanan Toko Contoh melalui WhatsApp.","evidence_ref":"signup:order-123"}'

Kirim permintaan ini hanya jika pengguna memang mencentang persetujuan tersebut. evidence_ref harus ID catatan signup/consent yang stabil dan tidak berisi rahasia. Pemanggilan ulang dengan ID bukti dan data yang sama aman; ID yang sama dengan data berbeda ditolak. Jika pengguna berhenti, status opt-out tetap berlaku sampai ada persetujuan baru yang benar-benar diberikan.

Status pesan

GET /api/v1/messages/{id} mengembalikan status dan riwayatnya. Urutan normal: queued → sending → sent → delivered → read. Status akhir gagal: failed atau blocked (ditolak aturan keamanan nomor). POST /api/v1/messages/{id}/retry mencoba ulang pesan yang gagal.

Centang biru (read) hanya muncul jika penerima mengaktifkan tanda baca di WhatsApp-nya.

Kontrol pengiriman

Device dapat digunakan setelah tersambung dan online; tidak ada batas berdasarkan umur device untuk memulai chat atau mengirim media. Pesan tetap tunduk pada saldo/kuota, batas harian berdasarkan catatan kualitas pengiriman, batas laju, jam aktif, pemeriksaan isi, dan status device. Sistem dapat menahan atau menolak pesan berdasarkan kontrol tersebut.

Pesan masuk tidak otomatis menjadi consent untuk promosi atau campaign. Balasan manual yang merujuk pesan masuk dan balasan otomatis untuk chat langsung dapat dilakukan dalam jendela 24 jam; instruksi STOP tetap memblokir pengiriman proaktif. Broadcast berisiko membuat WhatsApp membatasi nomor; kirim hanya kepada penerima yang setuju. KONEVA tidak menjamin nomor bebas pembatasan.

Pesan OTP yang dikirim melalui API tenant tetap mengikuti aturan consent, kuota, dan kontrol biasa. Nilai priority: "urgent" maupun otp_code dari pemanggil tidak mengaktifkan jalur istimewa.

Webhook

Webhook adalah panggilan dari kami ke server Anda saat ada kejadian, sehingga Anda tidak perlu menanyakan status terus-menerus. Simpan alamat di dashboard menu Webhook, buat kunci tanda tangan, lalu tekan Kirim tes.

Setiap kiriman membawa header X-Webhook-Event dan X-Webhook-Signature: sha256=<hex>, yaitu HMAC-SHA256 dari body mentah dengan kunci Anda. Hitung ulang dan bandingkan:

import crypto from "node:crypto";
import express from "express";

const app = express();
const SECRET = process.env.WEBHOOK_SECRET; // whsec_...

// Penting: baca body mentah, bukan hasil parse JSON.
app.post("/webhook", express.raw({ type: "application/json" }), (req, res) => {
  const expected = crypto.createHmac("sha256", SECRET).update(req.body).digest("hex");
  const received = (req.get("X-Webhook-Signature") || "").replace("sha256=", "");

  const ok =
    received.length === expected.length &&
    crypto.timingSafeEqual(Buffer.from(received), Buffer.from(expected));
  if (!ok) return res.status(401).send("invalid signature");

  const event = JSON.parse(req.body.toString());
  // Balas 200 dulu, kerjakan yang berat belakangan.
  res.sendStatus(200);

  if (event.event === "message.received") {
    console.log("Pesan masuk dari", event.from, ":", event.content);
  }
});

app.listen(3000);

Kejadian

{
  "event": "message.delivered",
  "device_key": "WAPI-XXXXXXXX",
  "message_id": "9380ccc2-9098-4c1e-8a0e-1f0f0d6f6a11",
  "whatsapp_message_id": "3EB0C767D0A1",
  "to": "6281234567890",
  "status": "delivered",
  "timestamp": "2026-09-26T10:30:00.000Z"
}

Aturan pengiriman

• Balas 2xx dalam 10 detik; selain itu dianggap gagal.
• Dicoba ulang 3 kali (setelah 1, 5, dan 15 detik), lalu dicatat gagal.
• Pengalihan (redirect) tidak diikuti.
• Bisa terkirim dobel dan urutan tidak dijamin: buat proses Anda aman diulang dan pakai timestamp.

Kode kesalahan

KONEVA adalah layanan pihak ketiga, tidak berafiliasi dengan WhatsApp atau Meta.