Public Integration Reference

WA Gateway HTTP JSON API

Dokumentasi publik untuk integrasi website, SaaS, automasi, dan jalur WhatsApp. Semua endpoint integrasi memakai JSON dan Bearer token.

Base URLhttps://wa.wayahe.my.id

Authentication

Semua endpoint /api/* dan /ext/* memakai header Authorization: Bearer sk-.... API key dibuat dari dashboard atau otomatis saat provisioning tenant.

Authorization: Bearer sk-your-api-key
Content-Type: application/json

API key bisa terikat ke satu device. Jika terikat, semua request otomatis memakai sesi WhatsApp device tersebut.

Machine Readable Index

Ringkasan endpoint untuk AI crawler atau integration assistant.

{
  "auth": "Bearer API key, format Authorization: Bearer sk-...",
  "base_url": "https://wa.wayahe.my.id",
  "channel_send": {
    "method": "POST",
    "path": "/api/channel/send",
    "supports": [
      "text only",
      "image only",
      "image + text"
    ],
    "request": {
      "channel_id": "required string, WhatsApp Channel JID ending with @newsletter",
      "type": "optional string: text or image; inferred from image field when omitted",
      "text": "required for text only; optional alias for caption",
      "caption": "optional for image; accepted as text for text-only payloads",
      "image": "required for image posts; public http(s) URL, data URL base64, or raw base64 image",
      "client_ref": "optional idempotency key"
    },
    "response_identifiers_for_delete": [
      "channel_id",
      "message_id",
      "post_id"
    ]
  },
  "endpoints": [
    "POST /ext/provision",
    "POST /ext/connect",
    "GET /ext/qr",
    "GET /ext/status",
    "POST /ext/disconnect",
    "POST /ext/webhook",
    "POST /api/send",
    "POST /api/send-image",
    "POST /api/send-bulk",
    "GET /api/groups",
    "POST /api/check-number",
    "POST /api/validate",
    "GET /api/channel/list",
    "POST /api/channel/send",
    "POST /api/channel/delete",
    "POST /api/channel/get-post"
  ]
}

Device API

POST/ext/provision

Create device and API key

Membuat device baru dan API key per-device. Cocok untuk SaaS multi-tenant.

curl -X POST https://wa.wayahe.my.id/ext/provision \
  -H "Authorization: Bearer sk-MASTER_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Toko A","webhookUrl":"https://example.com/api/wa-webhook"}'

{
  "success": true,
  "data": {
    "deviceId": "dev_xxxxx",
    "apiKey": "sk-full-key-save-this",
    "keyPreview": "sk-abcd...1234",
    "webhookUrl": "https://example.com/api/wa-webhook"
  }
}

POST/ext/connect

Start WhatsApp session

Memulai sesi Baileys dan membuat QR code untuk device dari API key.

curl -X POST https://wa.wayahe.my.id/ext/connect \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY"

GET/ext/qr

Get QR code

Polling setiap 2-3 detik sampai status menjadi connected.

{
  "success": true,
  "data": {
    "qr": "data:image/png;base64,...",
    "status": "connecting"
  }
}

GET/ext/status

Get device status

{
  "success": true,
  "data": {
    "deviceId": "dev_xxxxx",
    "name": "Toko A",
    "phone": "628123456789",
    "status": "connected",
    "webhookUrl": "https://example.com/api/wa-webhook"
  }
}

Message API

POST/api/send

Send text message

curl -X POST https://wa.wayahe.my.id/api/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"08123456789","message":"Halo, pesanan kamu sudah diproses."}'

{
  "success": true,
  "message": "Pesan masuk antrian",
  "data": {
    "jobId": "123",
    "dbId": 45,
    "to": "628123456789@s.whatsapp.net"
  }
}

POST/api/send-image

Send image to chat or group

{
  "to": "08123456789",
  "imageUrl": "https://example.com/invoice.jpg",
  "caption": "Invoice pesanan kamu"
}

POST/api/send-bulk

Send bulk text messages

Maksimal 50 penerima per request. Pesan tetap masuk queue agar pengiriman bertahap.

{
  "recipients": ["0811111111", "0822222222"],
  "message": "Promo hari ini"
}

POST/api/check-number

Check WhatsApp number and profile name

Validasi nomor WhatsApp dan mengembalikan nama profil/pushname bila gateway sudah bisa mengenalinya dari cache kontak, pesan masuk, atau profil bisnis. Jika name bernilai null, gunakan nama dari form user sebagai fallback saat menyimpan kontak.

curl -X POST https://wa.wayahe.my.id/api/check-number \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"628123456789"}'

{
  "success": true,
  "data": {
    "number": "628123456789",
    "isRegistered": true,
    "jid": "628123456789@s.whatsapp.net",
    "lid": null,
    "name": "Budi Santoso",
    "pushname": "Budi Santoso",
    "source": "message_pushname"
  }
}

POST/api/validate

Check WhatsApp number

Endpoint lama untuk kompatibilitas. Response juga menyertakan field nama bila tersedia.

{
  "to": "08123456789"
}

WhatsApp Channel API

Channel WhatsApp di Baileys disebut newsletter dan memakai JID @newsletter. Jika library tidak memberikan link publik per-post, field post_link bernilai null. Untuk delete, simpanchannel_id, message_id, dan post_id.

GET/api/channel/list

List channels

Return channel yang tersedia untuk akun WhatsApp yang login.

curl https://wa.wayahe.my.id/api/channel/list \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY"

{
  "success": true,
  "data": [
    {
      "id": "120363xxxxxxxx@newsletter",
      "name": "Promo Toko",
      "role": "OWNER",
      "can_post": true,
      "public_invite_link": "https://whatsapp.com/channel/..."
    }
  ]
}

POST/api/channel/send

Send text, image, or image + text to channel

Mengirim satu post ke channel. Mode yang didukung: text only,image only, dan image + caption/text. Field client_ref opsional dan idempotent, jadi request ulang dengan referensi yang sama tidak membuat double post.

Field type boleh text atau image. Jika type dikosongkan, gateway otomatis memilih imagesaat field image ada, selain itu memilih text. Untuk gambar, field image menerima URL publik, data URL base64 seperti data:image/jpeg;base64,..., atau raw base64.

Text only

curl -X POST https://wa.wayahe.my.id/api/channel/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "120363xxxxxxxx@newsletter",
    "type": "text",
    "text": "Info stok hari ini sudah ready.",
    "client_ref": "info-stok-2026-04-26"
  }'

Image only

curl -X POST https://wa.wayahe.my.id/api/channel/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "120363xxxxxxxx@newsletter",
    "type": "image",
    "image": "https://example.com/banner.jpg",
    "client_ref": "banner-2026-04-26"
  }'

Image + text

curl -X POST https://wa.wayahe.my.id/api/channel/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "120363xxxxxxxx@newsletter",
    "type": "image",
    "caption": "Promo hari ini",
    "image": "https://example.com/banner.jpg",
    "client_ref": "promo-2026-04-26"
  }'

{
  "success": true,
  "data": {
    "type": "image",
    "channel_id": "120363xxxxxxxx@newsletter",
    "channel_name": "Promo Toko",
    "message_id": "ABCDEF123456",
    "server_id": null,
    "post_id": "ch_stable_unique_id",
    "timestamp": 1712345678,
    "text": "Promo hari ini",
    "caption": "Promo hari ini",
    "image_url": "https://example.com/banner.jpg",
    "post_link": null,
    "can_delete": true
  }
}

POST/api/channel/delete

Delete channel post

Menghapus post channel berdasarkan identifier yang dikembalikan dari endpoint send.

curl -X POST https://wa.wayahe.my.id/api/channel/delete \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "channel_id": "120363xxxxxxxx@newsletter",
    "message_id": "ABCDEF123456",
    "post_id": "ch_stable_unique_id"
  }'

{
  "success": true,
  "message": "Post deleted"
}

POST/api/channel/get-post

Get channel post metadata

Mengambil metadata post dari gateway dan mencoba validasi remote jika library mendukung.

{
  "channel_id": "120363xxxxxxxx@newsletter",
  "message_id": "ABCDEF123456"
}

Channel validation rules

Request ditolak jika WhatsApp belum login.
Request ditolak jika channel_id bukan JID channel/newsletter.
Request ditolak jika role channel terbaca dan akun bukan admin/owner.
Request text ditolak jika text atau caption kosong.
Request image ditolak jika image bukan URL publik atau base64 image valid.

Incoming Webhook

Jika device punya webhook URL, gateway akan POST setiap pesan masuk ke URL tersebut. Jika device tidak punya webhook, gateway memakai webhook global dari settings.

{
  "event": "message.incoming",
  "data": {
    "deviceId": "dev_xxxxx",
    "jid": "628123456789@s.whatsapp.net",
    "sender": "628123456789",
    "name": "Customer",
    "text": "halo",
    "rawText": "Halo",
    "messageId": "ABCDEF123"
  }
}

Errors and Status Codes

400: payload tidak valid.
401: API key tidak ada atau tidak valid.
403: akun tidak punya izin post ke channel.
404: post/channel tidak ditemukan.
409: client_ref sedang diproses atau pernah gagal.
501: versi library belum mendukung operasi tertentu, misalnya list channel.
503: WhatsApp belum login atau device tidak terhubung.

{
  "success": false,
  "message": "WhatsApp tidak terhubung"
}

Curl Quickstart

# 1. Cek status device
curl https://wa.wayahe.my.id/ext/status \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY"

# 2. Kirim pesan teks
curl -X POST https://wa.wayahe.my.id/api/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"to":"08123456789","message":"Halo dari WA Gateway"}'

# 3. Kirim post channel text only
curl -X POST https://wa.wayahe.my.id/api/channel/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"120363xxxxxxxx@newsletter","type":"text","text":"Halo dari channel","client_ref":"channel-text-001"}'

# 4. Kirim post channel image + text idempotent
curl -X POST https://wa.wayahe.my.id/api/channel/send \
  -H "Authorization: Bearer sk-PER_DEVICE_KEY" \
  -H "Content-Type: application/json" \
  -d '{"channel_id":"120363xxxxxxxx@newsletter","type":"image","caption":"Promo","image":"https://example.com/banner.jpg","client_ref":"promo-001"}'