Langkau ke kandungan
Wbiztool

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.

POSThttps://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 "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

Gantikan 12345, YOUR_API_KEY dan 678 dengan nilai anda sendiri. Lihat Pengesahan identiti untuk mengetahui di mana nilai ini boleh didapati.

Parameter permintaan#

Pengesahan identiti

client_idintegerwajib

API Client ID anda dari Settings → API keys (Tetapan → Kunci API).

api_keystringwajib

Kunci API anda dari halaman yang sama.

whatsapp_clientintegerWajib jika anda mempunyai lebih daripada satu nombor

ID nombor WhatsApp yang digunakan untuk menghantar, dari tetapan WhatsApp. Jika anda tidak menyertakannya dan ruang kerja anda mempunyai tepat satu nombor yang disambungkan, nombor itu akan digunakan.

Penerima dan mesej

phonestringwajib

Nombor WhatsApp penerima, digit sahaja. Ruang, +, -, . dan kurungan dibuang secara automatik. Hantar nombor sama ada dengan kod negaranya (919876543210) atau tanpa kod negara (9876543210) bersama country_code. Dengan medan borang, jangan sertakan 0 trunk di hadapan (09876543210): ia tidak dibuang sebelum country_code ditambah, jadi mesej akan dihantar ke nombor yang salah. Permintaan JSON membuangnya untuk anda.

country_codestringpilihan

Kod panggilan negara tanpa +, contohnya 91 untuk India atau 1 untuk Amerika Syarikat. Kod ini ditambah di hadapan phone kecuali nombor itu sudah bermula dengannya. Pengecualian: dengan 91, 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_typeintegerpilihan

0 teks (lalai), 1 imej, 2 fail atau dokumen.

msgstringWajib apabila msg_type ialah 0

Teks mesej, sehingga 3,000 aksara. Untuk imej dan fail, ini ialah kapsyen dan boleh dibiarkan kosong. Format WhatsApp boleh digunakan: *bold*, _italic_, ~strikethrough~. message diterima sebagai alias.

Imej dan fail

img_urlstringWajib apabila msg_type ialah 1 dan tiada fail dimuat naik

URL http atau https awam bagi imej.

file_urlstringWajib apabila msg_type ialah 2 dan tiada fail dimuat naik

URL http atau https awam tempat fail boleh dimuat turun secara terus.

filefilepilihan

Muat naik imej atau fail dan bukannya memberikan URL. Hantar permintaan sebagai multipart/form-data dengan medan bernama file.

file_namestringpilihan

Nama 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_secondsintegerpilihan

Tandakan mesej sebagai tamat tempoh (status 4) jika ia belum dihantar dalam tempoh bilangan saat ini, contohnya 3600 untuk 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.

webhookstringpilihan

URL yang menerima POST apabila mesej dihantar atau gagal. Lihat Webhook.

Menghantar imej dan fail#

Had muat turun untuk img_url dan file_url:

  • URL mesti awam: http atau https, 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.

Sambungan yang disokong: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

Semakan ini dijalankan semasa mesej dihantar, bukan semasa anda memanggil API, jadi kegagalannya hanya kelihatan dalam Status mesej dan webhook:

Masalaherror dalam Status mesej
Imej (msg_type 1) melebihi 16 MBFile exceeds WhatsApp size limit (16MB max)
Video (.mp4, .webm) melebihi 64 MB, atau fail kosongFile exceeds WhatsApp size limit (…)
Fail .ogg, atau fail .wav yang dihantar sebagai imej (msg_type 1)File type not supported

Audio WAV dan OGG tidak disokong. Fail .wav yang dihantar sebagai fail (msg_type 2) tidak ditolak tetapi diterima sebagai recording.wav.pdf. Tukar audio kepada .mp3 atau .m4a dahulu.

Imej 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 🎉"
  }'
Muat naik fail
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 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"].

Respons#

Permintaan yang berjaya memulangkan HTTP 200:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
MedanJenisPenerangan
statusinteger1 jika mesej telah dimasukkan ke dalam baris gilir, 0 jika permintaan gagal.
messagestringCreated jika berjaya, jika tidak, mesej ralat.
msg_idintegerID 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" }
MesejCara membetulkannya
Auth Error - Please send correct API key and Client idHantar api_key yang tidak kosong.
Invalid client id.Hantar client_id sebagai nombor.
Auth Error: invalid api keyPastikan kunci wujud, belum dipadam dan milik client_id ini.
Either phone or group_name parameter is requiredTambah phone.
Please provide either phone OR group_name, not bothBuang salah satu daripadanya.
Invalid phone numberphone mesti mengandungi digit sahaja (6–17 digit), boleh bermula dengan +.
Invalid Contact Number "…"Selepas kod negara ditambah, nombor mesti sepanjang 6–15 digit.
Msg cant be nullMesej teks (msg_type 0) memerlukan msg.
Message length is too longHadkan msg kepada 3,000 aksara atau kurang.
Image Url Can't be nullUntuk msg_type 1, hantar img_url atau muat naik file.
File Url Can't be nullUntuk msg_type 2, hantar file_url atau muat naik file.
Invalid file url, Can't download / Invalid file urlURL bukan awam, tamat masa, atau fail melebihi 100 MB.
Invalid whatsapp clientID 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.
Not enough creditsPelan anda tiada baki mesej.
Demo Account can not access apisGunakan akaun biasa.
Account DisabledAkaun 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. Badannya dikodkan sebagai borang (application/x-www-form-urlencoded), bukan JSON:

msg_id=9817263&status=SENT
MedanNilai
msg_idmsg_id yang dipulangkan semasa anda menghantar mesej.
statusSENT atau FAILED

Balas dengan mana-mana kod 2xx. Jika endpoint anda tamat masa (selepas 3 saat) atau memulangkan 5xx, panggilan dicuba semula sehingga 3 kali secara keseluruhan. Respons 4xx tidak dicuba semula. Tiada webhook dihantar apabila mesej dibatalkan atau tamat tempoh; gunakan Status mesej untuk kes tersebut.

Petua#

  • Nombor telefon: simpan nombor dalam format antarabangsa dan hantarkannya bersama country_code untuk mengelakkan kekeliruan.
  • Baris baharu dalam JSON: tulis sebagai \n di dalam msg. 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).