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.
https://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."
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
headers={"Authorization": "Bearer YOUR_API_KEY"},
json={
"whatsapp_client": 678,
"msg_type": 0,
"country_code": "91",
"phone": "9876543210",
"msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
},
timeout=60,
)
result = response.json() # read the body even when the HTTP code is 400
if result.get("status") == 1:
print("Queued with msg_id", result["msg_id"])
else:
print("Failed:", result.get("message"))// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Authorization": "Bearer YOUR_API_KEY", "Content-Type": "application/json" },
body: JSON.stringify({
whatsapp_client: 678,
msg_type: 0,
country_code: "91",
phone: "9876543210",
msg: "Hi Aman, your order #4821 has shipped and will arrive on Thursday.",
}),
});
const result = await response.json(); // read the body even when the HTTP code is 400
if (result.status === 1) {
console.log("Queued with msg_id", result.msg_id);
} else {
console.error("Failed:", result.message);
}<?php
$payload = [
'whatsapp_client' => 678,
'msg_type' => 0,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Hi Aman, your order #4821 has shipped and will arrive on Thursday.',
];
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Authorization: Bearer YOUR_API_KEY', 'Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode($payload),
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 60,
]);
$result = json_decode(curl_exec($ch), true);
curl_close($ch);
if (($result['status'] ?? 0) === 1) {
echo 'Queued with msg_id ' . $result['msg_id'];
} else {
echo 'Failed: ' . ($result['message'] ?? 'no response');
}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
AuthorizationheaderDisarankanBearer YOUR_API_KEY: kunci API Anda dari Pengaturan → Kunci API. Dengan header ini,client_iddanapi_keyboleh tidak dikirim di body; jika keduanya dikirim, kunci valid di header yang dipakai. Lihat Mengirim kunci di header.client_idintegerTanpa header AuthorizationAPI Client ID Anda dari Pengaturan → Kunci API. Opsional jika memakai header; jika Anda mengirimnya, nilainya harus Client ID workspace kunci tersebut.
api_keystringTanpa header AuthorizationKunci API Anda dari halaman yang sama, jika Anda tidak mengirimnya di header.
whatsapp_clientintegerWajib jika Anda memiliki lebih dari satu nomorID 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.
@usernamemenggunakan 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
phonestringwajibNomor WhatsApp penerima. Spasi,
+,-,., tanda kurung, dan awalan00otomatis dihapus, jadi+91 98765-43210bisa dipakai. Nilai spreadsheet seperti919876543210.0dan9.19876543210E+11dibaca sebagai digitnya, tetapi nilai yang dibulatkan seperti9.19877E+11ditolak, karena ada digit yang hilang. Kirim nomor dengan kode negaranya (919876543210) atau tanpa kode negara (9876543210) bersamacountry_code. Nomor lokal yang ditulis dengan awalan0juga bisa:09876543210dengancountry_code91dikirim ke919876543210, dan0612345678dengan39(Italia, tempat0merupakan bagian dari nomor) dikirim ke390612345678. Nomor yang ditulis dengan+atau00sudah membawa kode negaranya:country_codetidak ditambahkan ke nomor itu, dan(0)dalam tanda kurung setelah kode negara dibuang, jadi+44 (0)20 7946 0018dikirim ke442079460018. Dari akun Telegram,phonejuga dapat berupa@username, tautant.me/username, atautg:<id>.country_codestringopsionalKode panggilan negara tanpa
+, misalnya91untuk India atau1untuk Amerika Serikat. Kode ini ditambahkan di depanphonekecuali nomornya sudah diawali kode tersebut atau ditulis dengan+atau00. Pengecualian: dengan91, 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_typeintegeropsional0teks (default),1gambar,2file atau dokumen.msgstringWajib jika msg_type bernilai 0Teks pesan, hingga 3.000 karakter. Untuk gambar dan file, ini adalah keterangan (caption) dan boleh kosong. Format WhatsApp berfungsi:
*bold*,_italic_,~strikethrough~.messagediterima sebagai alias.
Gambar dan file
img_urlstringWajib jika msg_type bernilai 1 dan tidak ada file yang diunggahURL
httpatauhttpspublik dari gambar.file_urlstringWajib jika msg_type bernilai 2 dan tidak ada file yang diunggahURL
httpatauhttpspublik tempat file dapat diunduh secara langsung.filefileopsionalUnggah gambar atau file sebagai ganti URL. Kirim request sebagai
multipart/form-datadengan field bernamafile.file_namestringopsionalNama 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_secondsintegeropsionalTandai pesan sebagai kedaluwarsa (status
4) jika belum terkirim dalam jumlah detik ini, misalnya3600untuk 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.webhookstringopsionalURL yang menerima
POSTketika pesan terkirim, gagal, dibatalkan, atau kedaluwarsa. Lihat Webhook.idempotency_keystringopsionalOpsional, 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 terjadi | Respons |
|---|---|
| Request pertama dengan nilai ini | Respons biasa. |
| Mencoba lagi setelah berhasil | Respons 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 berjalan | HTTP 409, code idempotency_in_progress, dengan Retry-After: 1. |
| Nilai yang sama dengan request yang berbeda | HTTP 409, code idempotency_key_reused. |
| Nilai lebih dari 255 karakter, atau berisi baris baru | HTTP 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:
httpatauhttps, 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:
| Kategori | Ekstensi |
|---|---|
| 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:
| Masalah | error di Status pesan |
|---|---|
Gambar (msg_type 1) lebih dari 16 MB | File 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 MB | File 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).
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 🎉"
}'import requests
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
json={
"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 🎉",
},
timeout=60,
)
print(response.json())// Node.js 18+ (built-in fetch). Save as .mjs to use top-level await.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
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 🎉",
}),
});
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
CURLOPT_HTTPHEADER => ['Content-Type: application/json'],
CURLOPT_POSTFIELDS => json_encode([
'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 🎉',
]),
CURLOPT_RETURNTRANSFER => true,
]);
echo curl_exec($ch);
curl_close($ch);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.pdfimport requests
with open("invoice-4821.pdf", "rb") as f:
response = requests.post(
"https://wbiztool.com/api/v1/send_msg/",
data={
"client_id": 12345,
"api_key": "YOUR_API_KEY",
"whatsapp_client": 678,
"msg_type": 2,
"country_code": "91",
"phone": "9876543210",
"msg": "Your invoice for order #4821 is attached.",
"file_name": "invoice-4821.pdf",
},
files={"file": f},
timeout=120,
)
print(response.json())// Node.js 20+ (built-in fetch, FormData and fs.openAsBlob). Save as .mjs to use top-level await.
import { openAsBlob } from "node:fs";
const form = new FormData();
form.append("client_id", "12345");
form.append("api_key", "YOUR_API_KEY");
form.append("whatsapp_client", "678");
form.append("msg_type", "2");
form.append("country_code", "91");
form.append("phone", "9876543210");
form.append("msg", "Your invoice for order #4821 is attached.");
form.append("file_name", "invoice-4821.pdf");
form.append("file", await openAsBlob("./invoice-4821.pdf"), "invoice-4821.pdf");
// Don't set Content-Type yourself; fetch adds the multipart boundary.
const response = await fetch("https://wbiztool.com/api/v1/send_msg/", { method: "POST", body: form });
console.log(await response.json());<?php
$ch = curl_init('https://wbiztool.com/api/v1/send_msg/');
curl_setopt_array($ch, [
CURLOPT_POST => true,
// An array body (not json_encode) makes cURL send multipart/form-data.
CURLOPT_POSTFIELDS => [
'client_id' => 12345,
'api_key' => 'YOUR_API_KEY',
'whatsapp_client' => 678,
'msg_type' => 2,
'country_code' => '91',
'phone' => '9876543210',
'msg' => 'Your invoice for order #4821 is attached.',
'file_name' => 'invoice-4821.pdf',
'file' => new CURLFile('/path/to/invoice-4821.pdf', 'application/pdf', 'invoice-4821.pdf'),
],
CURLOPT_RETURNTRANSFER => true,
CURLOPT_TIMEOUT => 120,
]);
echo curl_exec($ch);
curl_close($ch);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"].
const { WbizToolClient } = require("wbiztool-client");
const client = new WbizToolClient({
clientId: 12345,
apiKey: "YOUR_API_KEY",
whatsappClient: 678,
});
(async () => {
// Errors throw, with the API's response in the error message.
const result = await client.sendMessage({
phone: "9876543210",
countryCode: "91",
message: "Hi Aman, your order #4821 has shipped.",
});
console.log(result);
})().catch(console.error);Respons#
Request yang berhasil mengembalikan HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| Field | Tipe | Deskripsi |
|---|---|---|
status | integer | 1 jika pesan masuk antrean, 0 jika request gagal. |
message | string | Created jika berhasil, selain itu berisi error. |
msg_id | integer | ID 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" }
| Pesan | Cara memperbaikinya |
|---|---|
Auth Error - Please send correct API key and Client id | Kirim api_key yang tidak kosong. |
Invalid client id. | Kirim client_id sebagai angka. |
Auth Error: invalid api key | Pastikan kunci tersebut ada, belum dihapus, dan milik client_id ini. |
Either phone or group_name parameter is required | Tambahkan phone. |
Please provide either phone OR group_name, not both | Hapus salah satunya. |
Invalid phone number | phone 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 null | Pesan teks (msg_type 0) memerlukan msg. |
Message length is too long | Batasi msg hingga 3.000 karakter atau kurang. |
Image Url Can't be null | Untuk msg_type 1, kirim img_url atau unggah file. |
File Url Can't be null | Untuk msg_type 2, kirim file_url atau unggah file. |
Invalid file url, Can't download / Invalid file url | URL tidak publik, waktu habis (timeout), atau file lebih dari 100 MB. |
Invalid whatsapp client | ID 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 credits | Workspace 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 apis | Gunakan akun biasa. |
Account Disabled | Akun 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
| Field | Nilai |
|---|---|
msg_id | msg_id yang dikembalikan saat Anda mengirim pesan. |
status | SENT, 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_codeuntuk menghindari ambiguitas. - Baris baru di JSON: tulis sebagai
\ndi dalammsg. 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).

