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 "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."
  }'

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

AuthorizationheaderDisyorkan

Bearer YOUR_API_KEY: kunci API anda dari Tetapan → Kunci API. Dengan pengepala ini, client_id dan api_key boleh ditinggalkan daripada badan; jika kedua-duanya dihantar, kunci sah dalam pengepala yang digunakan. Lihat Hantar kunci dalam pengepala.

client_idintegerTanpa pengepala Authorization

API Client ID anda dari Tetapan → Kunci API. Pilihan dengan pengepala; jika anda menghantarnya, ia mestilah Client ID ruang kerja kunci itu.

api_keystringTanpa pengepala Authorization

Kunci API anda dari halaman yang sama, apabila anda tidak menghantarnya dalam pengepala.

whatsapp_clientintegerWajib jika anda mempunyai lebih daripada satu nombor

ID 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. @username menggunakan 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

phonestringwajib

Nombor WhatsApp penerima. Ruang, +, -, ., kurungan dan 00 di hadapan dibuang secara automatik, jadi +91 98765-43210 boleh digunakan. Nilai hamparan seperti 919876543210.0 dan 9.19876543210E+11 dibaca sebagai digitnya, tetapi nilai yang dibundarkan seperti 9.19877E+11 ditolak, kerana ada digit yang hilang. Hantar nombor sama ada dengan kod negaranya (919876543210) atau tanpa kod negara (9876543210) bersama country_code. Nombor tempatan yang ditulis dengan 0 di hadapan juga boleh digunakan: 09876543210 dengan country_code 91 dihantar ke 919876543210, dan 0612345678 dengan 39 (Itali, di mana 0 ialah sebahagian daripada nombor) dihantar ke 390612345678. Nombor yang ditulis dengan + atau 00 sudah membawa kod negaranya: country_code tidak ditambah kepadanya, dan (0) dalam kurungan selepas kod negara dibuang, jadi +44 (0)20 7946 0018 dihantar ke 442079460018. Daripada akaun Telegram, phone juga boleh berupa @username, pautan t.me/username atau tg:<id>.

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 atau ditulis dengan + atau 00. 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, gagal, dibatalkan atau tamat tempoh. Lihat Webhook.

idempotency_keystringpilihan

Pilihan, 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 berlakuRespons
Permintaan pertama dengan nilai iniRespons biasa.
Cuba semula selepas berjayaRespons 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 berjalanHTTP 409, code idempotency_in_progress, dengan Retry-After: 1.
Nilai yang sama dengan permintaan yang berbezaHTTP 409, code idempotency_key_reused.
Nilai melebihi 255 aksara, atau dengan pemisah barisHTTP 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: 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.

Fail yang dihantar dengan msg_type 2 mengekalkan sambungan berikut:

KategoriSambungan
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:

Masalaherror dalam Status mesej
Imej (msg_type 1) melebihi 16 MBFile 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 MBFile 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).

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 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 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.
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 creditsRuang 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 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, 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
MedanNilai
msg_idmsg_id yang dipulangkan semasa anda menghantar mesej.
statusSENT, 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_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).