Dokumentasi Integrasi api-wa

Verifikasi nomor WhatsApp pelanggan lewat WhatsApp resmi. Dua cara: pelanggan chat duluan (murah) atau kita kirim OTP.

KonsepMulai cepatAutentikasi InboundOutboundCek status KuotaWebhookKode error

1. Konsep: Inbound vs Outbound

Tujuannya sama — memastikan sebuah nomor WhatsApp benar-benar milik & dipegang orangnya. Bedanya cuma siapa yang kirim pesan duluan.

2. Mulai cepat

3. Autentikasi

Setiap request menyertakan API key di header Authorization:

Authorization: Bearer API_KEY_KAMU
Content-Type: application/json

Semua endpoint di bawah berada di prefix /v1. Balasan selalu JSON.

📥 INBOUND 4. Verifikasi Inbound

Langkah 1 — buat sesi verifikasi. Kirim type: "inbound".

# POST /v1/verifications
curl -X POST https://api-wa-murah.biz.id/v1/verifications \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{"type":"inbound"}'

Balasan (201):

{
  "data": {
    "id": "01j...ulid",
    "type": "inbound",
    "status": "pending",
    "code": "QL-8F3K",
    "wa_link": "https://wa.me/62812xxxx?text=Verifikasi%20%23QL-8F3K",
    "expires_at": "2026-07-10T12:10:00+00:00",
    "created_at": "2026-07-10T12:00:00+00:00"
  }
}

Langkah 2 — tampilkan wa_link sebagai tombol "Verifikasi WhatsApp" ke pelanggan. Dia menekannya, lalu tekan Kirim di WhatsApp.

Langkah 3 — tunggu hasilnya lewat Webhook (disarankan) atau cek status berkala. Saat selesai, status jadi verified dan muncul verified_number.

📤 OUTBOUND 5. Verifikasi Outbound (OTP)

Langkah 1 — kirim OTP. Sertakan type: "outbound" dan to (nomor tujuan, format internasional tanpa +).

# POST /v1/verifications
curl -X POST https://api-wa-murah.biz.id/v1/verifications \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{"type":"outbound","to":"62812xxxxxxx"}'

Balasan (201) — OTP dikirim via WhatsApp, kodenya tidak pernah diekspos di API:

{
  "data": {
    "id": "01j...ulid",
    "type": "outbound",
    "status": "pending",
    "target_number": "62812xxxxxxx",
    "expires_at": "2026-07-10T12:10:00+00:00",
    "created_at": "2026-07-10T12:00:00+00:00"
  }
}

Langkah 2 — cek kode yang diketik pelanggan di form kamu:

# POST /v1/verifications/{id}/check
curl -X POST https://api-wa-murah.biz.id/v1/verifications/01j...ulid/check \
  -H "Authorization: Bearer API_KEY_KAMU" \
  -H "Content-Type: application/json" \
  -d '{"code":"123456"}'

Kalau benar (200): {"message":"Nomor terverifikasi.","data":{...}}. Kalau salah → 422 invalid_code, kedaluwarsa → 410 expired, terlalu banyak coba → 429 too_many_attempts.

6. Cek status (polling)

# GET /v1/verifications/{id}
curl https://api-wa-murah.biz.id/v1/verifications/01j...ulid \
  -H "Authorization: Bearer API_KEY_KAMU"

status	arti
pending	menunggu pelanggan
verified	berhasil terverifikasi
expired	kedaluwarsa (lewat 10 menit)

7. Cek kuota pemakaian

# GET /v1/usage
curl https://api-wa-murah.biz.id/v1/usage -H "Authorization: Bearer API_KEY_KAMU"

{
  "data": {
    "period_start": "2026-07-01",
    "period_end": "2026-07-31",
    "plan": "Starter",
    "quota": 250,
    "used": 12,
    "remaining": 238
  }
}

Kalau kuota habis, request verifikasi baru ditolak dengan 402.

8. Webhook (disarankan)

Daftarkan URL milikmu. Saat verifikasi selesai, kami kirim POST ke URL itu — jadi kamu tak perlu polling.

# Yang kami kirim ke URL kamu:
POST https://situsmu.com/webhook-apiwa
X-ApiWa-Event: verification.completed
X-ApiWa-Signature: sha256=<hmac>

{
  "event": "verification.completed",
  "data": {
    "id": "01j...ulid",
    "type": "inbound",
    "status": "verified",
    "verified_number": "62812xxxxxxx",
    "target_number": null,
    "verified_at": "2026-07-10T12:03:00+00:00"
  }
}

Verifikasi keaslian (agar tak dipalsukan): hitung HMAC SHA-256 dari raw body pakai secret webhook-mu, bandingkan dengan header X-ApiWa-Signature.

// contoh PHP
$raw = file_get_contents('php://input');
$expected = 'sha256=' . hash_hmac('sha256', $raw, $SECRET_WEBHOOK_KAMU);
if (! hash_equals($expected, $_SERVER['HTTP_X_APIWA_SIGNATURE'] ?? '')) {
    http_response_code(401); exit;
}

9. Ringkasan kode status

Kode	Arti
201	Sesi verifikasi dibuat
200	OK / terverifikasi
401	API key salah/hilang
402	Kuota habis
403	API key tak punya scope layanan itu
404	Verifikasi tak ditemukan (atau bukan milikmu)
410	Sesi kedaluwarsa
422	Input tak valid / kode OTP salah
429	Terlalu banyak percobaan / rate limit

© api-wa · Butuh bantuan? Hubungi admin.