Dokumentasi API

Satu API key, tiga kanal pengiriman. Semua endpoint di bawah pakai base URL https://gateway.wasilahhub.id.

Autentikasi

Setiap request ke endpoint di bawah (selain webhook) wajib menyertakan header X-Api-Key. Ambil API key dari dashboard setelah membuat project — nilainya cuma tampil sekali saat dibuat.

X-Api-Key: WH_xxxxxxxxxxxxxxxx

API key punya scope tertentu (wa.send, wa.read, tg.send, tg.read, ai.chat, shipping.read, notify.send, serta email.identity khusus akun Dedicated); maksimal 10 key aktif per project. Request ke endpoint yang scope-nya tidak dimiliki key akan ditolak dengan API_KEY_SCOPE_DENIED.

Paket & Hak Akses (Shared vs Dedicated)

Setiap akun customer masuk ke salah satu dari dua tier berikut (batas maksimal 2 project per akun customer):

AspekCustomer SharedCustomer Dedicated
Jalur WA & TGPool bersama WasilahHub (rotasi round-robin otomatis)Nomor WA sendiri (scan QR mandiri, min saldo 10 kredit) & Bot Telegram sendiri (@BotFather), maks 1 WA & 1 TG
Tarif Kirim WA1 kredit0.5 kredit
Tarif Kirim TG0.5 kredit0.25 kredit
Webhook InteraktifTidak tersedia (satu arah)Tersedia dua arah (balasan otomatis WA 0.5 kredit / TG 0.25 kredit)
Identitas EmailIdentitas default WasilahHubBisa atur pengirim kustom via PUT /api/v1/email/identity (scope email.identity)

Rate limit

Default 60 request/menit per API key (mengikuti pengaturan admin). Kelebihan batas akan dapat response 429 dengan kode RATE_LIMIT_EXCEEDED. Di luar itu, ada juga batas kasar per alamat IP di level jaringan sebagai lapisan proteksi tambahan.

POST/api/v1/ai/chat

Chat dengan AI Gateway — dicoba berurutan sesuai prioritas provider, berhenti di yang pertama berhasil.

curl -X POST https://gateway.wasilahhub.id/api/v1/ai/chat \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"message":"Halo, apa kabar?"}'

Opsional: system_prompt (maks 4000 karakter) dan history (maks 20 giliran, tiap isi maks 4000 karakter, role user/assistant). message maks 4000 karakter. Balasan: { reply, provider, tokens_used, latency_ms }.

POST/api/v1/wa/send

Kirim pesan WhatsApp lewat pool bersama (round-robin) atau nomor dedicated project Anda.

curl -X POST https://gateway.wasilahhub.id/api/v1/wa/send \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"phone":"62812xxxxxxx","message":"Halo dari WasilahHub"}'

Opsional: "session":"nama-sesi" untuk memaksa nomor tertentu. phone hanya angka format internasional (9-15 digit), message maks 4000 karakter. Kredit dipotong hanya bila status terkirim; bila saldo tidak cukup, request ditolak sebelum pengiriman (402 CREDIT_INSUFFICIENT). Pengiriman yang gagal dibalas HTTP 502 dengan status failed.

Nomor pengirim. Akun Customer Shared mengirim lewat pool bersama secara otomatis (round-robin). Akun Customer Dedicated mengelola nomor WA dan bot Telegram khusus langsung dari menu Dedicated WA & TG di dashboard: secara default project dikunci ke nomor dedicated (bila terputus, pesan tidak dikirim dan tidak dikenai kredit; Anda menerima WA_DEDICATED_UNAVAILABLE, HTTP 503). Aturan ini sama untuk /api/v1/wa/send dan /api/v1/notify; balasan otomatis (dua arah) selalu keluar dari nomor/bot yang menerima pesan. Pada kebijakan dedicated saja, parameter session hanya boleh berisi nomor dedicated project itu (selain itu WA_SESSION_NOT_ALLOWED, HTTP 403).

Format teks. Pesan WhatsApp mendukung pemformatan bawaan aplikasi: *tebal*, _miring_, ~coret~, dan ```monospasi```. Gateway mengirim teks apa adanya, jadi tanda ini langsung dirender oleh WhatsApp penerima.

POST/api/v1/tg/send

curl -X POST https://gateway.wasilahhub.id/api/v1/tg/send \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"chat_id":"123456789","message":"Halo dari WasilahHub"}'

Opsional: "bot":"nama-bot" untuk memaksa bot tertentu.

GET/api/v1/wa/sessions

Daftar nomor WhatsApp yang boleh dipakai project Anda (pool bersama + nomor dedicated milik project Anda), termasuk status koneksinya. Butuh scope wa.read.

curl https://gateway.wasilahhub.id/api/v1/wa/sessions \
  -H "X-Api-Key: WH_xxxxxxxx"

Balasan: { items: [{ id, session_name, phone_number, status, bridge_type, project_id, last_used_at }] }.

GET/api/v1/tg/bots

Daftar bot Telegram yang boleh dipakai project Anda (pool bersama + bot dedicated milik project Anda), termasuk status koneksinya. Butuh scope tg.read.

curl https://gateway.wasilahhub.id/api/v1/tg/bots \
  -H "X-Api-Key: WH_xxxxxxxx"

Balasan: { items: [{ id, bot_name, username, status, project_id, last_used_at }] }.

POST/api/v1/notify

Satu endpoint untuk tiga kanal — cukup ganti nilai channel.

curl -X POST https://gateway.wasilahhub.id/api/v1/notify \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"channel":"whatsapp","destination":"62812xxxxxxx","message":"Halo"}'
channeldestinationBiaya (Shared / Dedicated)
whatsappNomor WA format internasional (628...)1 kredit (Shared) / 0.5 kredit (Dedicated)
telegramChat ID numerik atau @channel0.5 kredit (Shared) / 0.25 kredit (Dedicated)
emailSatu alamat email valid (kuota 200 email/hari per project)Gratis

Opsi khusus channel email

Semua opsional. Tanpa field berikut, email dikirim sebagai teks biasa seperti sebelumnya (judul Notifikasi).

FieldKeterangan
subjectJudul email, 1–150 karakter, satu baris.
templatenotification — email HTML berformat (logo, warna brand, ringkasan, tombol) dengan versi teks otomatis. message tetap wajib dan tampil sebagai paragraf utama.
variablesDipakai bersama template: heading (judul di dalam email), summary (daftar {"label","value"}, maks 20 baris), button_text + button_url (wajib berpasangan, URL https), note (catatan kecil), preheader (teks pratinjau di kotak masuk, maks 150 karakter), brand (ubah identitas untuk email ini saja: logo_url, brand_color, footer_text; yang tidak dikirim memakai identitas project). Semua nilai di-escape; HTML mentah tidak diterima. Field tak dikenal di dalam variables ditolak dengan VALIDATION_ERROR; field tak dikenal di tingkat atas /notify diabaikan.
curl -X POST https://gateway.wasilahhub.id/api/v1/notify \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"channel":"email","destination":"pembeli@contoh.com","subject":"Pesanan #1234 diterima","message":"Terima kasih, pesanan Anda sudah kami terima.","template":"notification","variables":{"heading":"Pesanan diterima","summary":[{"label":"No. pesanan","value":"#1234"},{"label":"Total","value":"Rp 150.000"}],"button_text":"Lihat pesanan","button_url":"https://toko.contoh.com/pesanan/1234"}}'

Nama pengirim, alamat pengirim, reply-to, logo, warna brand, dan footer diatur per project lewat /api/v1/email/identity. Alamat pengirim hanya boleh memakai domain yang SPF, DKIM, dan DMARC-nya sudah terverifikasi di WasilahHub.

PUT/api/v1/email/identity

Khusus Customer Dedicated. Atur identitas email project Anda; dipakai semua email /api/v1/notify channel email. Butuh API key dengan scope email.identity (akun Shared otomatis memakai identitas pengirim standar WasilahHub). GET pada alamat yang sama membaca nilai saat ini beserta allowed_sender_domains.

FieldAturan
sender_nameNama pengirim, 2–80 karakter: huruf, angka, spasi, dan . , & ' ( ) -.
sender_emailAlamat pengirim. Domainnya harus ada di allowed_sender_domains (terverifikasi SPF/DKIM/DMARC: wasilahhub.id); selain itu DOMAIN_NOT_VERIFIED. Bagian sebelum @: huruf kecil, angka, . _ -, maks 64; nama resmi seperti admin, support, info, postmaster, billing dicadangkan (SENDER_ADDRESS_RESERVED).
reply_toSatu alamat email valid tempat balasan penerima masuk (domain bebas).
logo_urlURL https, maks 255 karakter. Gambar ditampilkan langsung dari URL Anda (tidak disalin oleh gateway), jadi mengganti file di URL yang sama langsung berlaku di semua email.
brand_colorFormat #RRGGBB.
footer_textTeks polos, maks 500 karakter, selalu di-escape.

Field yang dikirim diperbarui, yang tidak dikirim tidak berubah, dan null atau string kosong mengosongkannya. Field tak dikenal ditolak dengan VALIDATION_ERROR supaya klien bisa mendeteksi dukungan fitur. Maksimal 20 perubahan per jam per project (EMAIL_IDENTITY_RATE_LIMITED); setiap perubahan dicatat di log aktivitas.

curl -X PUT https://gateway.wasilahhub.id/api/v1/email/identity \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"sender_name":"Wasilah Hub Store","sender_email":"noreply@wasilahhub.com","reply_to":"toko@contoh.com","logo_url":"https://toko.contoh.com/logo.png","brand_color":"#137A4D","footer_text":"Wasilah Hub Store – Jl. Contoh No. 1"}'

Email yang dikirim dari domain terverifikasi (seperti wasilahhub.id) ditandatangani DKIM dengan domain tersebut, sehingga lolos DMARC. Bila suatu saat domain dicabut dari daftar terverifikasi, email project otomatis kembali memakai alamat standar WasilahHub tanpa error.

POST/api/v1/shipping/cost

curl -X POST https://gateway.wasilahhub.id/api/v1/shipping/cost \
  -H "X-Api-Key: WH_xxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"origin":"31505","destination":"40739","weight":1000}'

origin/destination pakai district ID. Opsional: courier, origin_postal_code, destination_postal_code (agar provider cadangan bisa dipakai), item_value. Balasan: { options: [...], provider, latency_ms }, tiap opsi berisi courier, service, cost, etd.

Balasan otomatis (dua arah — Khusus Dedicated)

Pada akun Customer Shared, satu nomor/bot dipakai bersama semua project (round-robin) untuk pengiriman satu arah. Untuk chat interaktif dua arah pada akun Customer Dedicated, pasangkan nomor WA / bot Telegram Anda di menu Dedicated WA & TG, lalu isi kolom Webhook Interaktif pada tabel Projects di dashboard.

Setiap pesan teks masuk diteruskan ke URL itu, baik dari WhatsApp maupun Telegram:

POST <webhook_url_anda>
X-Webhook-Secret: <secret_anda>
Content-Type: application/json

{"channel":"whatsapp","from":"62812xxxxxxx","message":"produk"}

Contoh dari Telegram:

{"channel":"telegram","from":"123456789","message":"produk"}

Balas dengan {"reply":"teks balasan"} (HTTP 200) dan WasilahHub mengirimkannya ke customer lewat nomor/bot yang sama. Jika reply kosong atau tidak ada, tidak ada balasan yang dikirim.

Isi from. WhatsApp: nomor pengirim. Telegram: chat_id sebagai string. Chat privat berisi id pengguna (angka positif); grup/supergrup berisi id grup (negatif), sehingga semua anggota tampak sebagai satu pengirim. Layani fitur personal seperti login dan status hanya saat from positif. Id pengirim, username, dan tipe chat tidak diteruskan. Di grup, bot hanya menerima pesan sesuai setelan privacy mode di BotFather.

Yang diteruskan. Telegram: hanya pesan teks baru; foto, stiker, pesan yang diedit, dan tombol inline tidak diteruskan. Balasan untuk kedua kanal berupa teks.

Format respons. Respons harus berupa JSON yang valid, cukup {} jika tidak ada balasan. Respons kosong, bukan JSON, atau berstatus 4xx/5xx dicatat sebagai galat dan tidak ada balasan yang dikirim. Redirect (301/302) tidak diikuti, jadi daftarkan URL akhir yang tidak mengalihkan.

Keamanan. Cocokkan header X-Webhook-Secret dengan secret project Anda dan tolak jika berbeda.

Waktu dan pengulangan. WasilahHub menunggu respons Anda paling lama 30 detik. Pesan masuk tidak dideduplikasi, jadi buat handler yang cepat dan idempoten.

Biaya. Setiap balasan otomatis memotong kredit pemilik project (saat ini WA 0.5 kredit / TG 0.25 kredit untuk Dedicated). Jika kredit tidak cukup, pengirim menerima pesan standar WasilahHub sebagai ganti balasan Anda. Pesan masuk hanya diteruskan jika pemilik project aktif.

Kode error umum

KodeArti
API_KEY_REQUIREDHeader X-Api-Key tidak ada
API_KEY_INVALIDKey salah, dicabut, atau kedaluwarsa
API_KEY_SCOPE_DENIEDKey tidak punya scope yang dibutuhkan
RATE_LIMIT_EXCEEDEDTerlalu banyak request dalam 1 menit
CREDIT_INSUFFICIENTSaldo kredit tidak cukup
VALIDATION_ERRORInput tidak valid (HTTP 422)
EMAIL_DAILY_LIMITKuota email harian project habis (HTTP 429)
WA_SESSION_NOT_FOUND / TG_BOT_NOT_FOUNDNomor/bot diminta tidak ada atau bukan milik project Anda
DOMAIN_NOT_VERIFIEDDomain sender_email belum terverifikasi SPF/DKIM/DMARC (HTTP 422); lihat allowed_sender_domains
SENDER_ADDRESS_RESERVEDNama sebelum @ dicadangkan (HTTP 422)
EMAIL_IDENTITY_RATE_LIMITEDLebih dari 20 perubahan identitas email dalam 1 jam (HTTP 429)
WA_DEDICATED_UNAVAILABLEProject dikunci ke nomor dedicated yang sedang terputus atau belum diatur (HTTP 503); pesan tidak dikirim, kredit tidak dipotong
WA_SESSION_NOT_ALLOWEDProject dikunci ke nomor dedicated; sesi lain tidak boleh dipakai (HTTP 403)
WA_POOL_EMPTY / TG_POOL_EMPTYTidak ada nomor/bot aktif di pool
AI_PROVIDER_UNAVAILABLESemua provider AI gagal dicoba

Siap coba? Daftar akun, buat project, dan ambil API key — semuanya lewat dashboard.

Buat akun gratis