Langsung ke konten
WbizTool

API Pesan

API Kirim Pesan

Kirim teks, gambar, atau dokumen WhatsApp ke satu nomor telepon dari nomor WhatsApp Anda yang terhubung. Gunakan untuk konfirmasi pesanan, pengingat pembayaran, notifikasi, dan balasan layanan pelanggan.

POSThttps://wbiztool.com/api/v1/send_msg/

Body: JSON, field formulir, atau multipart/form-data saat mengunggah file

Pesan masuk antrean dan dikirim dari nomor WhatsApp Anda dalam hitungan detik. Respons memberi Anda msg_id yang dapat digunakan untuk memeriksa statusnya.

Contoh singkat#

curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Ganti YOUR_API_KEY dan 678 dengan kunci dan ID nomor Anda sendiri. Lihat Autentikasi untuk mengetahui di mana menemukannya. Kunci dikirim di header Authorization: Bearer (disarankan); client_id dan api_key di body, sebagai JSON atau field formulir, juga berfungsi – contoh-contoh selanjutnya menggunakannya.

Parameter request#

Autentikasi

AuthorizationheaderDisarankan

Bearer YOUR_API_KEY: kunci API Anda dari Pengaturan → Kunci API. Dengan header ini, client_id dan api_key boleh tidak dikirim di body; jika keduanya dikirim, kunci valid di header yang dipakai. Lihat Mengirim kunci di header.

client_idintegerTanpa header Authorization

API Client ID Anda dari Pengaturan → Kunci API. Opsional jika memakai header; jika Anda mengirimnya, nilainya harus Client ID workspace kunci tersebut.

api_keystringTanpa header Authorization

Kunci API Anda dari halaman yang sama, jika Anda tidak mengirimnya di header.

whatsapp_clientintegerWajib jika Anda memiliki lebih dari satu nomor

ID nomor WhatsApp atau akun Telegram yang digunakan untuk mengirim, dari WhatsApp settings (pengaturan WhatsApp). Jika tidak dikirim, satu-satunya nomor yang terhubung yang digunakan, dengan WhatsApp didahulukan: satu nomor WhatsApp yang terhubung tetap digunakan meskipun ada akun Telegram yang juga terhubung, dan akun Telegram hanya digunakan jika tidak ada nomor WhatsApp yang terhubung. @username menggunakan satu-satunya akun Telegram yang terhubung. Jika tidak ada nomor WhatsApp yang terhubung, satu-satunya nomor ekstensi Chrome yang browser-nya tertutup yang digunakan, sehingga pesan menunggu alih-alih gagal.

Penerima dan pesan

phonestringwajib

Nomor WhatsApp penerima. Spasi, +, -, ., tanda kurung, dan awalan 00 otomatis dihapus, jadi +91 98765-43210 bisa dipakai. Nilai spreadsheet seperti 919876543210.0 dan 9.19876543210E+11 dibaca sebagai digitnya, tetapi nilai yang dibulatkan seperti 9.19877E+11 ditolak, karena ada digit yang hilang. Kirim nomor dengan kode negaranya (919876543210) atau tanpa kode negara (9876543210) bersama country_code. Nomor lokal yang ditulis dengan awalan 0 juga bisa: 09876543210 dengan country_code 91 dikirim ke 919876543210, dan 0612345678 dengan 39 (Italia, tempat 0 merupakan bagian dari nomor) dikirim ke 390612345678. Nomor yang ditulis dengan + atau 00 sudah membawa kode negaranya: country_code tidak ditambahkan ke nomor itu, dan (0) dalam tanda kurung setelah kode negara dibuang, jadi +44 (0)20 7946 0018 dikirim ke 442079460018. Dari akun Telegram, phone juga dapat berupa @username, tautan t.me/username, atau tg:<id>.

country_codestringopsional

Kode panggilan negara tanpa +, misalnya 91 untuk India atau 1 untuk Amerika Serikat. Kode ini ditambahkan di depan phone kecuali nomornya sudah diawali kode tersebut atau ditulis dengan + atau 00. Pengecualian: dengan 91, nomor 10 digit selalu mendapat awalan. Dengan kode lain, nomor lokal yang diawali angka yang sama tidak diberi awalan, jadi kirim nomor tersebut lengkap dengan kode negaranya.

msg_typeintegeropsional

0 teks (default), 1 gambar, 2 file atau dokumen.

msgstringWajib jika msg_type bernilai 0

Teks pesan, hingga 3.000 karakter. Untuk gambar dan file, ini adalah keterangan (caption) dan boleh kosong. Format WhatsApp berfungsi: *bold*, _italic_, ~strikethrough~. message diterima sebagai alias.

Gambar dan file

img_urlstringWajib jika msg_type bernilai 1 dan tidak ada file yang diunggah

URL http atau https publik dari gambar.

file_urlstringWajib jika msg_type bernilai 2 dan tidak ada file yang diunggah

URL http atau https publik tempat file dapat diunduh secara langsung.

filefileopsional

Unggah gambar atau file sebagai ganti URL. Kirim request sebagai multipart/form-data dengan field bernama file.

file_namestringopsional

Nama file yang dilihat penerima, misalnya invoice-4821.pdf. Ekstensinya menentukan cara file dikirim, jadi sertakan ekstensi. Nama dikirim dalam huruf kecil, karakter seperti & : ? * $ ; diganti dengan _, dan dipotong menjadi 150 karakter. Jika tidak dikirim, nama diambil dari URL atau file yang diunggah.

Opsi pengiriman

expire_after_secondsintegeropsional

Tandai pesan sebagai kedaluwarsa (status 4) jika belum terkirim dalam jumlah detik ini, misalnya 3600 untuk satu jam. Berguna untuk pesan yang bergantung pada waktu, seperti perkiraan waktu pengantaran. Proses latar belakang melakukannya paling cepat 30 detik setelah batas waktu, jadi jangan mengandalkannya untuk batas waktu yang lebih pendek dari satu menit.

webhookstringopsional

URL yang menerima POST ketika pesan terkirim, gagal, dibatalkan, atau kedaluwarsa. Lihat Webhook.

idempotency_keystringopsional

Opsional, maksimal 255 karakter. Selama 24 jam, jika Anda mencoba lagi dengan nilai yang sama, Anda menerima respons pertama, bukan pesan kedua. Anda juga dapat mengirimnya sebagai header Idempotency-Key. Lihat Mencoba lagi dengan aman.

Mencoba lagi dengan aman#

Setelah timeout atau koneksi terputus, Anda tidak bisa tahu apakah request Anda sampai, dan mengirimnya lagi bisa membuat pelanggan menerima pesan dua kali. Agar aman saat mencoba lagi, kirim field idempotency_key atau header Idempotency-Key dengan nilai Anda sendiri yang unik untuk pesan ini, seperti ID pesanan atau UUID, lalu gunakan nilai dan request yang sama saat mencoba lagi.

Ini berlaku untuk Kirim pesan, Kirim ke grup, Kirim ke banyak nomor, dan Jadwalkan pesan. Setiap kunci API memiliki nilainya sendiri, yang disimpan selama 24 jam. Tanpa nilai, atau dengan nilai kosong, setiap request mengirim pesan seperti biasa.

Yang terjadiRespons
Request pertama dengan nilai iniRespons biasa.
Mencoba lagi setelah berhasilRespons pertama lagi, dengan header Idempotent-Replayed: true. Tidak ada pesan baru.
Mencoba lagi setelah ditolak (status 0)Dijalankan lagi: penolakan tidak diingat, jadi Anda dapat memperbaiki request dan mencoba lagi dengan nilai yang sama.
Mencoba lagi saat request pertama masih berjalanHTTP 409, code idempotency_in_progress, dengan Retry-After: 1.
Nilai yang sama dengan request yang berbedaHTTP 409, code idempotency_key_reused.
Nilai lebih dari 255 karakter, atau berisi baris baruHTTP 400, code invalid_idempotency_key.

Kunci idempotensi hanya mencegah request yang sama membuat pesan kedua. Kunci ini tidak memberi tahu apakah pesan sampai ke WhatsApp: untuk itu, gunakan webhook atau Status pesan.

Mengirim gambar dan file#

Batas unduhan untuk img_url dan file_url:

  • URL harus publik: http atau https, dapat dijangkau dari internet. Hingga 5 redirect diikuti, dan setiap redirect juga harus mengarah ke alamat publik.
  • File yang ditautkan boleh berukuran hingga 100 MB. Server harus mulai merespons dalam 45 detik dan tidak boleh berhenti lebih lama dari itu.
  • File diambil saat Anda memanggil API, jadi tautan yang rusak langsung gagal dengan Invalid file url.

File yang dikirim dengan msg_type 2 mempertahankan ekstensi berikut:

KategoriEkstensi
Gambar.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Dokumen.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Audio.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Video.mp4, .mov, .avi, .webm
Arsip.zip, .rar

Pemeriksaan berikut dijalankan saat pesan dikirim, bukan saat Anda memanggil API, sehingga kegagalannya hanya terlihat di Status pesan dan webhook:

Masalaherror di Status pesan
Gambar (msg_type 1) lebih dari 16 MBFile exceeds WhatsApp size limit (16MB max)
Video (.mp4, .webm) lebih dari 64 MB, termasuk yang dikirim sebagai gambar (msg_type 1)File exceeds WhatsApp size limit (64MB max)
File lain apa pun (msg_type 2) lebih dari 100 MBFile exceeds WhatsApp size limit (100MB max)
File kosong (0 byte)The file is empty
File .wav atau .ogg yang dikirim sebagai gambar (msg_type 1)File type not supported

Audio WAV dan OGG tidak dapat dikirim sebagai gambar (msg_type 1). Jika dikirim sebagai file (msg_type 2), keduanya diterima sebagai dokumen dengan namanya sendiri, seperti recording.wav. File .mp3, .mpga, .m4a, dan .aac diterima sebagai audio yang dapat diputar di chat, dan msg menyusul sebagai pesan teks terpisah (audio tidak memiliki keterangan).

Gambar dari URL
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -H "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 1,
    "country_code": "91",
    "phone": "9876543210",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts today 🎉"
  }'
Unggah file
curl -X POST https://wbiztool.com/api/v1/send_msg/ \
  -F client_id=12345 \
  -F api_key=YOUR_API_KEY \
  -F whatsapp_client=678 \
  -F msg_type=2 \
  -F country_code=91 \
  -F phone=9876543210 \
  -F "msg=Your invoice for order #4821 is attached." \
  -F file_name=invoice-4821.pdf \
  -F file=@./invoice-4821.pdf

Menggunakan klien resmi#

Klien Python dan Node.js memanggil endpoint ini untuk Anda.

from wbiztool_client import WbizToolClient

client = WbizToolClient(api_key="YOUR_API_KEY", client_id="12345")

result = client.send_message(
    phone="9876543210",
    country_code="91",
    msg="Hi Aman, your order #4821 has shipped.",
    whatsapp_client=678,
)
print(result)

Error memunculkan requests.HTTPError. Baca penyebabnya dengan e.response.json()["message"].

Respons#

Request yang berhasil mengembalikan HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
FieldTipeDeskripsi
statusinteger1 jika pesan masuk antrean, 0 jika request gagal.
messagestringCreated jika berhasil, selain itu berisi error.
msg_idintegerID pesan dalam antrean. Simpan untuk memeriksa status nanti. Hanya ada jika berhasil.

"status": 1 berarti pesan sudah masuk antrean, belum tentu sudah sampai ke penerima. Gunakan webhook atau Status pesan untuk memastikan pesan sudah terkirim.

Error#

Error mengembalikan HTTP 400 dengan status bernilai 0 (Account Disabled tidak memiliki field status):

{ "status": 0, "message": "Msg cant be null" }
PesanCara memperbaikinya
Auth Error - Please send correct API key and Client idKirim api_key yang tidak kosong.
Invalid client id.Kirim client_id sebagai angka.
Auth Error: invalid api keyPastikan kunci tersebut ada, belum dihapus, dan milik client_id ini.
Either phone or group_name parameter is requiredTambahkan phone.
Please provide either phone OR group_name, not bothHapus salah satunya.
Invalid phone numberphone harus berupa nomor dengan 6–17 digit. Huruf dan simbol lain tidak diperbolehkan, begitu pula nilai spreadsheet yang dibulatkan seperti 9.19877E+11.
Invalid Contact Number "…"Setelah kode negara ditambahkan, nomor harus sepanjang 7–15 digit.
Msg cant be nullPesan teks (msg_type 0) memerlukan msg.
Message length is too longBatasi msg hingga 3.000 karakter atau kurang.
Image Url Can't be nullUntuk msg_type 1, kirim img_url atau unggah file.
File Url Can't be nullUntuk msg_type 2, kirim file_url atau unggah file.
Invalid file url, Can't download / Invalid file urlURL tidak publik, waktu habis (timeout), atau file lebih dari 100 MB.
Invalid whatsapp clientID whatsapp_client tersebut tidak ada di workspace Anda.
Invalid whatsapp client id.Kirim whatsapp_client. Parameter ini wajib jika workspace Anda memiliki lebih dari satu nomor yang terhubung.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_client@username, tautan t.me, atau tg:<id> di phone memerlukan akun Telegram sebagai whatsapp_client.
Not enough creditsWorkspace memakai paket gratis dan pesannya sudah habis: paket berbayar mengirim pesan tanpa batas. Lihat Saat pesan Anda habis.
Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. (HTTP 429, "code": "daily_limit_reached")Nomor ini sudah menerima 1.000 pesan dalam 24 jam terakhir (penggunaan wajar). Respons tetap berisi msg_id pesan yang ditolak, yang tampil sebagai gagal. Kirim sisanya nanti atau dari nomor lain.
Demo Account can not access apisGunakan akun biasa.
Account DisabledAkun Anda dinonaktifkan. Hubungi dukungan.
Invalid JSON format: …Body JSON tidak valid, sering kali karena koma di akhir atau baris baru tanpa escape di msg. Gunakan \n untuk baris baru.

Pesan yang sudah masuk antrean masih bisa gagal saat dikirim, misalnya dengan File exceeds WhatsApp size limit (…). Error tersebut tidak pernah muncul di respons ini. Lihat Mengirim gambar dan file dan periksa Status pesan.

Webhook#

Jika Anda mengirim webhook, WbizTool mengirim POST ke URL tersebut ketika pesan terkirim atau gagal, dan juga ketika pesan dibatalkan atau kedaluwarsa sebelum terkirim. Body-nya dienkode sebagai formulir (application/x-www-form-urlencoded), bukan JSON:

msg_id=9817263&status=SENT
FieldNilai
msg_idmsg_id yang dikembalikan saat Anda mengirim pesan.
statusSENT, FAILED, CANCELLED (dibatalkan sebelum terkirim: dengan Batalkan pesan, dari dashboard, atau karena nomor WhatsApp atau kampanyenya dihapus) atau EXPIRED (tidak terkirim sebelum expire_after_seconds habis, atau masih menunggu di nomor yang terputus 48 jam setelah jadwalnya)

Setiap webhook ditandatangani: header WbizTool-Timestamp dan WbizTool-Signature (v1= dan HMAC-SHA256 dari <timestamp>.<raw body> dengan rahasia penandatanganan workspace Anda) memungkinkan Anda memastikan webhook itu berasal dari WbizTool. Dapatkan rahasianya serta contoh pemeriksaan Python dan Node.js di Tanda tangan webhook; penerima yang mengabaikan header ini tetap berfungsi.

Balas dengan kode 2xx apa pun; pengalihan (redirect) diikuti paling banyak 3 kali. Jika endpoint Anda tidak menjawab dalam 10 detik, tidak dapat dijangkau, atau mengembalikan 429 atau 5xx, WbizTool mencoba lagi setelah 30 detik, 1 menit, dan 2 menit (total 4 kali percobaan). Respons 4xx lainnya tidak dicoba ulang. URL harus berupa alamat internet publik: webhook ke alamat privat atau lokal (seperti 192.168.x.x atau localhost) tidak dikirim.

Tips#

  • Nomor telepon: simpan nomor dalam format internasional dan kirim bersama country_code untuk menghindari ambiguitas.
  • Baris baru di JSON: tulis sebagai \n di dalam msg. Baris baru mentah membuat JSON tidak valid.
  • Jaga nomor Anda tetap terhubung: pesan dikirim dari nomor WhatsApp Anda, jadi nomor tersebut harus tetap terhubung di WhatsApp settings.
  • Banyak penerima: untuk mengirim pesan yang sama ke beberapa nomor dalam satu request, gunakan Kirim ke banyak nomor. Untuk kampanye besar, unggah spreadsheet dari halaman Campaigns (Kampanye).