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):
| Aspek | Customer Shared | Customer Dedicated |
|---|---|---|
| Jalur WA & TG | Pool 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 WA | 1 kredit | 0.5 kredit |
| Tarif Kirim TG | 0.5 kredit | 0.25 kredit |
| Webhook Interaktif | Tidak tersedia (satu arah) | Tersedia dua arah (balasan otomatis WA 0.5 kredit / TG 0.25 kredit) |
| Identitas Email | Identitas default WasilahHub | Bisa 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"}'
| channel | destination | Biaya (Shared / Dedicated) |
|---|---|---|
whatsapp | Nomor WA format internasional (628...) | 1 kredit (Shared) / 0.5 kredit (Dedicated) |
telegram | Chat ID numerik atau @channel | 0.5 kredit (Shared) / 0.25 kredit (Dedicated) |
email | Satu 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).
| Field | Keterangan |
|---|---|
subject | Judul email, 1–150 karakter, satu baris. |
template | notification — email HTML berformat (logo, warna brand, ringkasan, tombol) dengan versi teks otomatis. message tetap wajib dan tampil sebagai paragraf utama. |
variables | Dipakai 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.
| Field | Aturan |
|---|---|
sender_name | Nama pengirim, 2–80 karakter: huruf, angka, spasi, dan . , & ' ( ) -. |
sender_email | Alamat 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_to | Satu alamat email valid tempat balasan penerima masuk (domain bebas). |
logo_url | URL 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_color | Format #RRGGBB. |
footer_text | Teks 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
| Kode | Arti |
|---|---|
API_KEY_REQUIRED | Header X-Api-Key tidak ada |
API_KEY_INVALID | Key salah, dicabut, atau kedaluwarsa |
API_KEY_SCOPE_DENIED | Key tidak punya scope yang dibutuhkan |
RATE_LIMIT_EXCEEDED | Terlalu banyak request dalam 1 menit |
CREDIT_INSUFFICIENT | Saldo kredit tidak cukup |
VALIDATION_ERROR | Input tidak valid (HTTP 422) |
EMAIL_DAILY_LIMIT | Kuota email harian project habis (HTTP 429) |
WA_SESSION_NOT_FOUND / TG_BOT_NOT_FOUND | Nomor/bot diminta tidak ada atau bukan milik project Anda |
DOMAIN_NOT_VERIFIED | Domain sender_email belum terverifikasi SPF/DKIM/DMARC (HTTP 422); lihat allowed_sender_domains |
SENDER_ADDRESS_RESERVED | Nama sebelum @ dicadangkan (HTTP 422) |
EMAIL_IDENTITY_RATE_LIMITED | Lebih dari 20 perubahan identitas email dalam 1 jam (HTTP 429) |
WA_DEDICATED_UNAVAILABLE | Project dikunci ke nomor dedicated yang sedang terputus atau belum diatur (HTTP 503); pesan tidak dikirim, kredit tidak dipotong |
WA_SESSION_NOT_ALLOWED | Project dikunci ke nomor dedicated; sesi lain tidak boleh dipakai (HTTP 403) |
WA_POOL_EMPTY / TG_POOL_EMPTY | Tidak ada nomor/bot aktif di pool |
AI_PROVIDER_UNAVAILABLE | Semua provider AI gagal dicoba |
Siap coba? Daftar akun, buat project, dan ambil API key — semuanya lewat dashboard.
Buat akun gratis