Langkau ke kandungan
WbizTool

API mesej

API Hantar ke Beberapa Nombor

Hantar mesej WhatsApp yang sama ke beberapa nombor telefon dan kumpulan dalam satu permintaan. Gunakannya untuk siaran kecil seperti surat berita, tawaran dan pengumuman.

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

Body: JSON atau medan borang

WbizTool mencipta satu mesej bagi setiap penerima dan memulangkan msg_id untuk setiap satu, supaya anda boleh menyemak statusnya secara berasingan.

Contoh ringkas#

curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
  -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,9812345670,Sales Team Mumbai",
    "msg": "Our Diwali sale starts tomorrow. Get 20% off on all orders!"
  }'

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

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

ID nombor WhatsApp atau akaun Telegram yang digunakan untuk menghantar, dari tetapan WhatsApp. Tidak seperti Hantar mesej, endpoint ini tidak pernah memilih nombor untuk anda.

Penerima dan mesej

phonestringwajib

Nombor telefon dan nama kumpulan dalam satu rentetan yang dipisahkan dengan koma, contohnya 9876543210,9812345670,Sales Team Mumbai. Jangan hantar tatasusunan JSON. Lihat Cara penerima dibaca.

country_codestringpilihan

Kod panggilan negara tanpa +, contohnya 91. Kod ini ditambah di hadapan setiap nombor telefon kecuali nombor itu sudah bermula dengannya atau ditulis dengan + atau 00. Dalam JSON, rentetan ("91") dan nombor (91) kedua-duanya boleh digunakan.

msg_typeintegerpilihan

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

msgstringWajib apabila msg_type ialah 0

Teks mesej. 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

URL http atau https awam bagi imej.

file_urlstringWajib apabila msg_type ialah 2

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

file_namestringpilihan

Nama fail yang dilihat oleh penerima, seperti price-list.pdf. Nama dihantar dalam huruf kecil, aksara seperti & : ? * $ ; digantikan dengan _, dan nama dipotong kepada 150 aksara. Jika anda tidak menyertakannya, nama diambil daripada URL.

Pilihan penghantaran

webhookstringpilihan

URL yang menerima POST bagi setiap mesej apabila ia dihantar, gagal, dibatalkan atau tamat tempoh. Muatannya sama seperti untuk Hantar mesej.

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.

Imej dari URLcURL
curl -X POST https://wbiztool.com/api/v1/send_msg/multi/ \
  -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,9812345670",
    "img_url": "https://example.com/offers/diwali-sale.jpg",
    "msg": "Our Diwali sale starts tomorrow."
  }'

Cara penerima dibaca#

WbizTool memisahkan phone mengikut koma, membuang ruang di sekeliling setiap item, kemudian menentukan jenis setiap item:

  • Nombor telefon boleh ditulis seperti yang anda ada: +91 98765 43210, 98765-43210, (987) 654-3210, 0091 98765 43210 dan +44 (0)20 7946 0018 semuanya boleh digunakan, begitu juga nilai hamparan seperti 919876543210.0 dan 9.19876543210E+11.
  • country_code ditambah kecuali nombor itu sudah bermula dengannya atau ditulis dengan + atau 00: +44 20 7946 0018 dengan country_code 91 kekal sebagai 442079460018. Jadi senarai boleh mencampurkan beberapa negara: tulis nombor negara lain dengan +.
  • 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.
  • Selepas kod negara ditambah, nombor mesti sepanjang 7 hingga 15 digit.
  • Teks dengan huruf atau simbol lain, seperti Sales Team Mumbai atau Family 2024, dianggap sebagai nama kumpulan WhatsApp, dicari dengan cara yang sama seperti dalam Hantar ke kumpulan.
  • Nama kumpulan tanpa huruf, seperti 2024-2025, dibaca sebagai nombor telefon, melainkan ia mempunyai kurang daripada 10 digit dan ruang kerja anda sudah pernah menghantar mesej kepada kumpulan dengan nama yang tepat sama (ia disenaraikan di bawah Kumpulan dalam Kenalan). Nama pendek dengan kurang daripada 7 digit dan sengkang, titik atau kurungan, seperti 2024-25 atau (2024), sentiasa dianggap nama kumpulan. Nama kumpulan yang mengandungi koma tidak boleh dihantar dari endpoint ini. Gunakan Hantar ke kumpulan untuk kumpulan sebegini.
  • Daripada akaun Telegram, @username, pautan t.me/username atau tg:<id> ialah seseorang, bukan nama kumpulan, dan nombor telefon dihantar kepada orang itu di Telegram. Daripada nombor WhatsApp, nama pengguna, pautan t.me dan tg:<id> dilangkau.

Perkara lain yang perlu diketahui:

  • Nombor yang terlalu pendek atau terlalu panjang selepas kod negara ditambah, nilai hamparan yang dibundarkan dan item yang hanya sifar (0, 00) akan dilangkau tanpa pemberitahuan. Nombor ini tidak muncul dalam respons dan tidak mendapat msg_id.
  • Pendua tidak dibuang. Nombor yang disenaraikan dua kali akan menerima dua mesej.
  • Jika nombor tempatan kebetulan bermula dengan digit yang sama seperti country_code (contohnya 9123456780 dengan country_code 91), kod tidak ditambah. Hantar nombor sebegini dengan kod negara sudah disertakan (919123456780).
  • URL imej dan fail tidak disemak semasa anda memanggil API. URL dimuat turun semasa setiap mesej dihantar, jadi pautan yang rosak menyebabkan mesej gagal kemudian, bukan permintaan. Peraturan semasa penghantaran yang sama seperti Hantar mesej terpakai: imej melebihi 16 MB dan video melebihi 64 MB akan gagal, audio WAV dan OGG tidak boleh dihantar sebagai imej (msg_type 1), dan fail (msg_type 2) tanpa sambungan atau dengan sambungan yang tidak disokong akan ditambah .pdf. Lihat Menghantar imej dan fail.

Had mesej#

Keseluruhan kelompok disemak sebelum apa-apa dicipta, jadi senarai tidak pernah dihantar separuh. Setiap item yang tidak kosong dalam phone dikira, termasuk item yang kemudiannya dilangkau, dan mesej yang berada dalam baris gilir tetapi belum dihantar juga dikira.

  • Setiap pelan: kelompok mesti muat dalam had harian penggunaan berpatutan nombor penghantar – 1,000 mesej dalam mana-mana tempoh 24 jam. Jika tidak, tiada mesej dicipta dan anda akan menerima:
{
  "message": "Daily limit reached: a number can send 1,000 messages in 24 hours (fair use). Send the rest tomorrow. 1200 messages requested, 640 more can go out from this number in the next 24 hours.",
  "code": "daily_limit_reached",
  "status": 0
}
  • Pelan percuma: kelompok juga mesti muat dalam baki mesej percuma ruang kerja (50 dalam mana-mana tempoh 30 hari). Jika tidak, anda akan menerima:
{
  "message": "Not enough credits: 120 messages requested, 35 credits remaining",
  "status": 0
}

Bahagikan senarai besar kepada beberapa nombor atau hari. Untuk kempen besar, muat naik hamparan dari halaman Campaigns (Kempen).

Respons#

Permintaan yang berjaya memulangkan HTTP 200:

{
  "msg_ids": [9817263, 9817264, 9817265],
  "messages": [
    { "msg_id": 9817263, "contact": "919876543210", "is_group": false },
    { "msg_id": 9817264, "contact": "919812345670", "is_group": false },
    { "msg_id": 9817265, "contact": "Sales Team Mumbai", "is_group": true }
  ],
  "message": "Successfully created 3 messages",
  "status": 1
}
MedanJenisPenerangan
statusinteger1 jika sekurang-kurangnya satu mesej dimasukkan ke dalam baris gilir, jika tidak 0.
messagestringSuccessfully created N messages jika berjaya, jika tidak, mesej ralat.
msg_idstatasusunan integerID mesej dalam baris gilir, mengikut susunan phone. Hanya ada jika berjaya.
messagestatasusunanSatu objek bagi setiap mesej dalam baris gilir. Hanya ada jika berjaya.
messages[].msg_idintegerID mesej.
messages[].contactstringNombor telefon dengan kod negara yang telah ditambah, atau nama kumpulan.
messages[].is_groupbooleantrue jika item itu dianggap sebagai nama kumpulan.

Bandingkan messages dengan senarai yang anda hantar untuk mencari nombor yang dilangkau, dan pastikan is_group ialah false bagi setiap item yang anda maksudkan sebagai nombor telefon.

Ralat#

Kebanyakan ralat memulangkan HTTP 200 dengan status ditetapkan kepada 0, jadi sentiasa semak status dalam badan respons. Kecuali ralat HTTP 400 dan 403, respons (termasuk yang berjaya) ialah JSON yang dihantar dengan Content-Type: text/html, jadi huraikan badan respons sendiri dan jangan bergantung pada pengesanan JSON automatik (contohnya dalam alat tanpa kod):

{ "message": "Invalid whatsapp client", "status": 0 }
MesejCara membetulkannya
Auth ErrorHantar kedua-dua client_id dan api_key.
Invalid Client IdHantar client_id sebagai nombor. Dipulangkan dengan HTTP 403.
Auth Error: invalid api keyPastikan kunci wujud, belum dipadam dan milik client_id ini. Dipulangkan dengan HTTP 400.
Msg cant be nullMesej teks (msg_type 0) memerlukan msg.
Image Url Can't be nullUntuk msg_type 1, hantar img_url.
File Url Can't be nullUntuk msg_type 2, hantar file_url.
Not enough credits: … messages requested, … credits remainingMesej pelan percuma tidak mencukupi untuk senarai ini. Hantar kepada lebih sedikit penerima atau pilih pelan. Lihat Had mesej.
Daily limit reached: … messages requested, … more can go out from this number in the next 24 hours.Bahagikan senarai kepada beberapa hari atau nombor. Lihat Had mesej.
Invalid whatsapp clientID whatsapp_client itu tiada dalam ruang kerja anda.
No valid contacts foundSetiap item dalam phone kosong atau dilangkau. Pastikan nombor sepanjang 7 hingga 15 digit termasuk kod negara.
Demo Account can not access apisGunakan akaun biasa.
Invalid JSON format: …Badan JSON tidak sah, atau anda menghantar medan borang tanpa client_id.

Petua#

  • Hantar phone sebagai rentetan: gabungkan senarai anda dengan koma. Tatasusunan JSON memulangkan {}.
  • Jangan gunakan send_bulk_messages klien Python buat masa ini: ia menghantar senarai sebagai phones, yang diabaikan oleh endpoint ini. Panggil endpoint secara terus seperti dalam contoh di atas.
  • Jejaki setiap mesej: simpan setiap msg_id daripada messages, atau hantar webhook untuk dimaklumkan apabila setiap mesej dihantar, gagal, dibatalkan atau tamat tempoh.
  • Pastikan nombor anda kekal disambungkan: setiap mesej dihantar dari nombor WhatsApp anda, jadi ia mesti kekal disambungkan di tetapan WhatsApp sehingga keseluruhan kelompok selesai dihantar.
  • Teks berbeza bagi setiap orang: endpoint ini menghantar msg yang sama kepada semua orang. Panggil Hantar mesej sekali bagi setiap penerima untuk memperibadikan setiap mesej.