API mesej
Send Message API
Hantar teks, imej atau dokumen WhatsApp ke satu nombor telefon dari nombor WhatsApp anda yang disambungkan. Gunakannya untuk pengesahan pesanan, peringatan bayaran, makluman dan balasan sokongan.
https://wbiztool.com/api/v1/send_msg/Body: JSON, medan borang, atau multipart/form-data semasa memuat naik fail
Mesej dimasukkan ke dalam baris gilir dan dihantar dari nombor WhatsApp anda dalam beberapa saat. Respons memberikan msg_id yang boleh anda gunakan untuk menyemak statusnya.
Contoh ringkas#
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');
}Gantikan YOUR_API_KEY dan 678 dengan kunci dan ID nombor anda sendiri. Lihat Pengesahan identiti untuk mengetahui di mana nilai ini boleh didapati. Kunci dimasukkan dalam pengepala Authorization: Bearer (disyorkan); client_id dan api_key dalam badan, sebagai JSON atau medan borang, juga berfungsi – contoh-contoh di bawah menggunakannya.
Parameter permintaan#
Pengesahan identiti
AuthorizationheaderDisyorkanBearer YOUR_API_KEY: kunci API anda dari Tetapan → Kunci API. Dengan pengepala ini,client_iddanapi_keyboleh ditinggalkan daripada badan; jika kedua-duanya dihantar, kunci sah dalam pengepala yang digunakan. Lihat Hantar kunci dalam pengepala.client_idintegerTanpa pengepala AuthorizationAPI Client ID anda dari Tetapan → Kunci API. Pilihan dengan pengepala; jika anda menghantarnya, ia mestilah Client ID ruang kerja kunci itu.
api_keystringTanpa pengepala AuthorizationKunci API anda dari halaman yang sama, apabila anda tidak menghantarnya dalam pengepala.
whatsapp_clientintegerWajib jika anda mempunyai lebih daripada satu nomborID nombor WhatsApp atau akaun Telegram yang digunakan untuk menghantar, dari tetapan WhatsApp. Jika anda tidak menyertakannya, satu-satunya nombor yang disambungkan akan digunakan, WhatsApp dahulu: satu nombor WhatsApp yang disambungkan digunakan walaupun akaun Telegram turut disambungkan, dan akaun Telegram hanya digunakan apabila tiada nombor WhatsApp yang disambungkan.
@usernamemenggunakan satu-satunya akaun Telegram yang disambungkan. Apabila tiada nombor WhatsApp yang disambungkan, satu-satunya nombor sambungan Chrome yang pelayarnya ditutup digunakan, jadi mesej itu menunggu dan bukannya gagal.
Penerima dan mesej
phonestringwajibNombor WhatsApp penerima. Ruang,
+,-,., kurungan dan00di hadapan dibuang secara automatik, jadi+91 98765-43210boleh digunakan. Nilai hamparan seperti919876543210.0dan9.19876543210E+11dibaca sebagai digitnya, tetapi nilai yang dibundarkan seperti9.19877E+11ditolak, kerana ada digit yang hilang. Hantar nombor sama ada dengan kod negaranya (919876543210) atau tanpa kod negara (9876543210) bersamacountry_code. Nombor tempatan yang ditulis dengan0di hadapan juga boleh digunakan:09876543210dengancountry_code91dihantar ke919876543210, dan0612345678dengan39(Itali, di mana0ialah sebahagian daripada nombor) dihantar ke390612345678. Nombor yang ditulis dengan+atau00sudah membawa kod negaranya:country_codetidak ditambah kepadanya, dan(0)dalam kurungan selepas kod negara dibuang, jadi+44 (0)20 7946 0018dihantar ke442079460018. Daripada akaun Telegram,phonejuga boleh berupa@username, pautant.me/usernameatautg:<id>.country_codestringpilihanKod panggilan negara tanpa
+, contohnya91untuk India atau1untuk Amerika Syarikat. Kod ini ditambah di hadapanphonekecuali nombor itu sudah bermula dengannya atau ditulis dengan+atau00. Pengecualian: dengan91, nombor 10 digit sentiasa diberi awalan. Dengan kod lain, nombor tempatan yang bermula dengan digit yang sama tidak diberi awalan, jadi hantar nombor itu bersama kod negaranya.msg_typeintegerpilihan0teks (lalai),1imej,2fail atau dokumen.msgstringWajib apabila msg_type ialah 0Teks mesej, sehingga 3,000 aksara. Untuk imej dan fail, ini ialah kapsyen dan boleh dibiarkan kosong. Format WhatsApp boleh digunakan:
*bold*,_italic_,~strikethrough~.messagediterima sebagai alias.
Imej dan fail
img_urlstringWajib apabila msg_type ialah 1 dan tiada fail dimuat naikURL
httpatauhttpsawam bagi imej.file_urlstringWajib apabila msg_type ialah 2 dan tiada fail dimuat naikURL
httpatauhttpsawam tempat fail boleh dimuat turun secara terus.filefilepilihanMuat naik imej atau fail dan bukannya memberikan URL. Hantar permintaan sebagai
multipart/form-datadengan medan bernamafile.file_namestringpilihanNama fail yang dilihat oleh penerima, seperti
invoice-4821.pdf. Sambungannya menentukan cara fail dihantar, jadi sertakan sambungan. Nama dihantar dalam huruf kecil, aksara seperti& : ? * $ ;digantikan dengan_, dan nama dipotong kepada 150 aksara. Jika anda tidak menyertakannya, nama diambil daripada URL atau fail yang dimuat naik.
Pilihan penghantaran
expire_after_secondsintegerpilihanTandakan mesej sebagai tamat tempoh (status
4) jika ia belum dihantar dalam tempoh bilangan saat ini, contohnya3600untuk satu jam. Berguna untuk mesej yang sensitif masa seperti anggaran waktu tiba penghantaran. Tugas latar belakang melakukannya sekurang-kurangnya 30 saat selepas tarikh akhir, jadi jangan bergantung padanya untuk tarikh akhir yang kurang daripada satu minit.webhookstringpilihanURL yang menerima
POSTapabila mesej dihantar, gagal, dibatalkan atau tamat tempoh. Lihat Webhook.idempotency_keystringpilihanPilihan, sehingga 255 aksara. Selama 24 jam, jika anda mencuba semula dengan nilai yang sama, anda menerima respons pertama, bukan mesej kedua. Anda juga boleh menghantarnya sebagai pengepala
Idempotency-Key. Lihat Mencuba semula dengan selamat.
Mencuba semula dengan selamat#
Selepas tamat masa atau sambungan terputus, anda tidak dapat tahu sama ada permintaan anda sampai, dan menghantarnya semula boleh menyebabkan pelanggan menerima mesej dua kali. Untuk mencuba semula dengan selamat, hantar medan idempotency_key atau pengepala Idempotency-Key dengan nilai anda sendiri yang unik bagi mesej ini, seperti ID pesanan atau UUID, dan gunakan nilai dan permintaan yang sama apabila mencuba semula.
Ini berfungsi pada Hantar mesej, Hantar ke kumpulan, Hantar ke beberapa nombor dan Jadualkan mesej. Setiap kunci API mempunyai nilainya sendiri, yang disimpan selama 24 jam. Tanpa nilai, atau dengan nilai kosong, setiap permintaan menghantar mesej seperti biasa.
| Apa yang berlaku | Respons |
|---|---|
| Permintaan pertama dengan nilai ini | Respons biasa. |
| Cuba semula selepas berjaya | Respons pertama sekali lagi, dengan pengepala Idempotent-Replayed: true. Tiada mesej baharu. |
Cuba semula selepas ditolak (status 0) | Dijalankan semula: penolakan tidak diingati, jadi anda boleh membetulkan permintaan dan mencuba semula dengan nilai yang sama. |
| Cuba semula semasa permintaan pertama masih berjalan | HTTP 409, code idempotency_in_progress, dengan Retry-After: 1. |
| Nilai yang sama dengan permintaan yang berbeza | HTTP 409, code idempotency_key_reused. |
| Nilai melebihi 255 aksara, atau dengan pemisah baris | HTTP 400, code invalid_idempotency_key. |
Kunci idempotensi hanya menghalang permintaan yang sama daripada membuat mesej kedua. Ia tidak memberitahu sama ada mesej sampai ke WhatsApp: untuk itu, gunakan webhook atau Status mesej.
Menghantar imej dan fail#
Had muat turun untuk img_url dan file_url:
- URL mesti awam:
httpatauhttps, boleh dicapai dari internet. Sehingga 5 ubah hala diikuti, dan setiap satu juga mesti menuju ke alamat awam. - Fail yang dipautkan boleh bersaiz sehingga 100 MB. Pelayan mesti mula memberi respons dalam masa 45 saat dan tidak terhenti lebih lama daripada itu.
- Fail diambil semasa anda memanggil API, jadi pautan yang rosak gagal serta-merta dengan
Invalid file url.
Fail yang dihantar dengan msg_type 2 mengekalkan sambungan berikut:
| Kategori | Sambungan |
|---|---|
| Imej | .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 |
| Arkib | .zip, .rar |
Semakan ini dijalankan semasa mesej dihantar, bukan semasa anda memanggil API, jadi kegagalannya hanya kelihatan dalam Status mesej dan webhook:
| Masalah | error dalam Status mesej |
|---|---|
Imej (msg_type 1) melebihi 16 MB | File exceeds WhatsApp size limit (16MB max) |
Video (.mp4, .webm) melebihi 64 MB, termasuk yang dihantar sebagai imej (msg_type 1) | File exceeds WhatsApp size limit (64MB max) |
Sebarang fail lain (msg_type 2) melebihi 100 MB | File exceeds WhatsApp size limit (100MB max) |
| Fail kosong (0 bait) | The file is empty |
Fail .wav atau .ogg yang dihantar sebagai imej (msg_type 1) | File type not supported |
Audio WAV dan OGG tidak boleh dihantar sebagai imej (msg_type 1). Apabila dihantar sebagai fail (msg_type 2), ia diterima sebagai dokumen dengan namanya sendiri, seperti recording.wav. Fail .mp3, .mpga, .m4a dan .aac diterima sebagai audio yang dimainkan dalam sembang, dan msg menyusul sebagai mesej teks berasingan (audio tiada kapsyen).
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 rasmi#
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)Ralat menimbulkan requests.HTTPError. Baca sebabnya 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#
Permintaan yang berjaya memulangkan HTTP 200:
{
"status": 1,
"message": "Created",
"msg_id": 9817263
}
| Medan | Jenis | Penerangan |
|---|---|---|
status | integer | 1 jika mesej telah dimasukkan ke dalam baris gilir, 0 jika permintaan gagal. |
message | string | Created jika berjaya, jika tidak, mesej ralat. |
msg_id | integer | ID mesej dalam baris gilir. Simpan untuk menyemak status kemudian. Hanya ada jika berjaya. |
"status": 1 bermaksud mesej telah dimasukkan ke dalam baris gilir, bukan bermaksud ia sudah sampai kepada penerima. Gunakan webhook atau Status mesej untuk mengesahkan bahawa ia telah dihantar.
Ralat#
Ralat memulangkan HTTP 400 dengan status ditetapkan kepada 0 (Account Disabled tiada medan status):
{ "status": 0, "message": "Msg cant be null" }
| Mesej | Cara membetulkannya |
|---|---|
Auth Error - Please send correct API key and Client id | Hantar api_key yang tidak kosong. |
Invalid client id. | Hantar client_id sebagai nombor. |
Auth Error: invalid api key | Pastikan kunci wujud, belum dipadam dan milik client_id ini. |
Either phone or group_name parameter is required | Tambah phone. |
Please provide either phone OR group_name, not both | Buang salah satu daripadanya. |
Invalid phone number | phone mesti nombor dengan 6–17 digit. Huruf dan simbol lain tidak dibenarkan, begitu juga nilai hamparan yang dibundarkan seperti 9.19877E+11. |
Invalid Contact Number "…" | Selepas kod negara ditambah, nombor mesti sepanjang 7–15 digit. |
Msg cant be null | Mesej teks (msg_type 0) memerlukan msg. |
Message length is too long | Hadkan msg kepada 3,000 aksara atau kurang. |
Image Url Can't be null | Untuk msg_type 1, hantar img_url atau muat naik file. |
File Url Can't be null | Untuk msg_type 2, hantar file_url atau muat naik file. |
Invalid file url, Can't download / Invalid file url | URL bukan awam, tamat masa, atau fail melebihi 100 MB. |
Invalid whatsapp client | ID whatsapp_client itu tiada dalam ruang kerja anda. |
Invalid whatsapp client id. | Hantar whatsapp_client. Ia wajib apabila ruang kerja anda mempunyai lebih daripada satu nombor yang disambungkan. |
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_client | @username, pautan t.me atau tg:<id> dalam phone memerlukan akaun Telegram sebagai whatsapp_client. |
Not enough credits | Ruang kerja menggunakan pelan percuma dan tiada baki mesej: pelan berbayar menghantar mesej tanpa had. Lihat Apabila mesej 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") | Nombor ini telah menerima 1,000 mesej dalam 24 jam yang lalu (penggunaan berpatutan). Respons masih mengandungi msg_id mesej yang ditolak, yang dipaparkan sebagai gagal. Hantar bakinya kemudian atau daripada nombor lain. |
Demo Account can not access apis | Gunakan akaun biasa. |
Account Disabled | Akaun anda dinyahdayakan. Hubungi sokongan. |
Invalid JSON format: … | Badan JSON tidak sah, selalunya kerana koma di hujung atau pemisah baris yang tidak di-escape dalam msg. Gunakan \n untuk baris baharu. |
Mesej dalam baris gilir masih boleh gagal semasa dihantar, contohnya dengan File exceeds WhatsApp size limit (…). Ralat sebegini tidak pernah muncul dalam respons ini. Lihat Menghantar imej dan fail dan semak Status mesej.
Webhook#
Jika anda menghantar webhook, WbizTool menghantar POST ke URL itu apabila mesej dihantar atau gagal, dan apabila ia dibatalkan atau tamat tempoh sebelum sempat dihantar. Badannya dikodkan sebagai borang (application/x-www-form-urlencoded), bukan JSON:
msg_id=9817263&status=SENT
| Medan | Nilai |
|---|---|
msg_id | msg_id yang dipulangkan semasa anda menghantar mesej. |
status | SENT, FAILED, CANCELLED (dibatalkan sebelum dihantar: dengan Batal mesej, daripada papan pemuka, atau kerana nombor WhatsApp atau kempennya dibuang) atau EXPIRED (tidak dihantar sebelum expire_after_seconds tamat, atau masih menunggu pada nombor yang terputus sambungan 48 jam selepas masanya tiba) |
Setiap webhook ditandatangani: pengepala WbizTool-Timestamp dan WbizTool-Signature (v1= dan HMAC-SHA256 bagi <timestamp>.<raw body> dengan rahsia tandatangan ruang kerja anda) membolehkan anda memastikan ia datang daripada WbizTool. Dapatkan rahsia itu serta semakan Python dan Node.js dalam Tandatangan webhook; penerima yang mengabaikan pengepala ini terus berfungsi.
Balas dengan mana-mana kod 2xx; pengalihan (redirect) diikuti, paling banyak 3 kali. Jika endpoint anda tidak menjawab dalam masa 10 saat, tidak dapat dicapai, atau memulangkan 429 atau 5xx, WbizTool mencuba semula selepas 30 saat, 1 minit dan 2 minit (4 percubaan keseluruhannya). Respons 4xx yang lain tidak dicuba semula. URL mestilah alamat internet awam: webhook ke alamat peribadi atau setempat (seperti 192.168.x.x atau localhost) tidak dihantar.
Petua#
- Nombor telefon: simpan nombor dalam format antarabangsa dan hantarkannya bersama
country_codeuntuk mengelakkan kekeliruan. - Baris baharu dalam JSON: tulis sebagai
\ndi dalammsg. Pemisah baris mentah menjadikan JSON tidak sah. - Pastikan nombor anda kekal disambungkan: mesej dihantar dari nombor WhatsApp anda, jadi ia mesti kekal disambungkan di tetapan WhatsApp.
- Ramai penerima: untuk menghantar mesej yang sama ke beberapa nombor dalam satu permintaan, gunakan Hantar ke beberapa nombor. Untuk kempen besar, muat naik hamparan dari halaman Campaigns (Kempen).

