Langkau ke kandungan
WbizTool

API v2 (beta)

Mesej

Hantar mesej sekarang atau pada masa yang ditetapkan, kepada nombor telefon, kumpulan WhatsApp, kenalan yang disimpan atau nama pengguna Telegram. Hantar mesej yang sama kepada sehingga 1,000 penerima dalam satu permintaan, baca sejarah, ikuti status mesej dan batalkannya semasa ia menunggu.

OperasiEndpointSkop
Hantar mesejPOST /api/v2/messagesmessages:send
Hantar kepada ramai penerimaPOST /api/v2/messages/batchmessages:send
Senaraikan mesejGET /api/v2/messagesmessages:read
Dapatkan mesejGET /api/v2/messages/{id}messages:read
Batalkan mesejDELETE /api/v2/messages/{id}messages:send

Kunci, ralat, Idempotency-Key dan had berfungsi seperti yang diterangkan dalam Gambaran keseluruhan API v2. Untuk mengetahui bila mesej dihantar atau gagal tanpa meninjau berulang kali, tambah endpoint webhook.

Hantar mesej#

POSThttps://wbiztool.com/api/v2/messages

Body: JSON (application/json)

Mesej dimasukkan ke dalam baris gilir dan respons tiba sebelum ia dihantar, dengan HTTP 202 dan Message berstatus queued (atau scheduled dengan send_at pada masa hadapan). Ikutinya dengan Dapatkan mesej atau webhook.

curl -X POST https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-1042-ready" \
  -d '{
    "from": 101,
    "to": { "phone": "+919876543210" },
    "text": "Hi Asha, your order #1042 is ready."
  }'

Respons (202):

{
  "id": 9817263,
  "status": "queued",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": null,
  "error": null
}

Badan

toobjectwajib

Siapa yang menerimanya: tepat satu daripada phone, group, contact_id atau username. Lihat Penerima.

frominteger or nullWajib kecuali ruang kerja mempunyai satu nombor yang disambungkan

id nombor yang menghantarnya, daripada Senaraikan nombor. Jika tidak disertakan, satu-satunya nombor yang disambungkan akan menghantarnya: satu nombor WhatsApp yang disambungkan digunakan walaupun akaun Telegram turut disambungkan, dan akaun Telegram hanya digunakan apabila tiada nombor WhatsApp yang disambungkan. Nombor yang telah log keluar tetap diterima: mesejnya menunggu sehingga ia disambungkan semula.

textstringWajib kecuali media dihantar

Mesej itu, sehingga 3,000 aksara. Dengan media, ia menjadi kapsyen dan boleh ditinggalkan. Format WhatsApp berfungsi: *bold*, _italic_, ~strikethrough~. Dalam JSON, tulis baris baharu sebagai \n.

mediaobject or nullpilihan

Imej atau fail untuk dihantar. Lihat Media.

send_atstring or nullpilihan

Hantar pada masa ini dan bukannya sekarang: ISO 8601 dengan ofsetnya, seperti 2026-10-20T09:30:00+05:30. Ia mesti pada masa hadapan. Lihat Penjadualan dan tamat tempoh.

expires_atstring or nullpilihan

Jangan hantar selepas masa ini: mesej menjadi expired sebaliknya. ISO 8601 dengan ofsetnya, pada masa hadapan dan selepas send_at.

Pengepala

Authorizationheaderwajib

Bearer wbz_live_…, kunci dengan skop messages:send.

Idempotency-Keyheaderpilihan

Sebarang rentetan unik, supaya cubaan semula tidak sekali-kali menghantar mesej kedua. Lihat Idempotency-Key.

Ralat semasa menghantar#

HTTPKodBila
400validation_failedMedan tiada, jenisnya salah atau tidak dikenali; to tidak mempunyai satu pun atau mempunyai beberapa medannya; media mempunyai kedua-dua atau tiada satu pun daripada url dan media_id; expires_at tidak selepas send_at
400text_requiredTiada text dan tiada media
400text_too_longtext melebihi 3,000 aksara
400invalid_datetimesend_at atau expires_at bukan ISO 8601 dengan ofset
402no_creditsRuang kerja tiada mesej berbaki dalam pelannya
403number_not_allowedKunci dihadkan kepada nombor lain
403account_disabledAkaun pemilik ruang kerja dinyahdayakan
422invalid_phoneto.phone bukan nombor telefon dalam format antarabangsa dengan +
422invalid_usernameto.username bukan nama pengguna, pautan atau ID tg: Telegram
422username_needs_telegramto.username dengan nombor WhatsApp sebagai from
422contact_not_foundTiada kenalan dengan to.contact_id itu
422media_not_foundTiada fail dengan media.media_id itu
422invalid_media_urlmedia.url bukan pautan http(s) awam
422time_in_pastsend_at atau expires_at telah berlalu
422number_not_foundfrom bukan nombor ruang kerja ini
422from_requiredTiada from, dan ruang kerja tiada nombor yang disambungkan atau mempunyai beberapa
422message_rejectedMesej tidak dapat dimasukkan ke dalam baris gilir; message menyatakan sebabnya
429number_daily_cap_reachedNombor itu telah menghantar 1,000 mesej dalam 24 jam yang lalu

Penghantaran yang ditolak tidak meninggalkan apa-apa: tiada mesej disimpan, jadi tiada apa yang perlu dibatalkan. Ralat yang boleh berlaku pada sebarang permintaan (kunci, skop, had kadar, Idempotency-Key) ada di halaman ralat.

Hantar kepada ramai penerima#

POSThttps://wbiztool.com/api/v2/messages/batch

Body: JSON (application/json)

Menghantar mesej yang sama kepada sehingga 1,000 penerima. Badannya sama seperti Hantar mesej, kecuali to ialah senarai penerima.

  • Semua atau tiada. Setiap penerima disemak sebelum apa-apa dimasukkan ke dalam baris gilir, dan seluruh senarai mesti muat dalam baki mesej pelan dan dalam ruang nombor penghantar untuk 24 jam yang akan datang. Jika satu penerima salah, tiada apa yang dimasukkan ke dalam baris gilir, dan field menamakannya, seperti to[3].phone.
  • Penerima yang sama dua kali mendapat satu mesej.
  • Responsnya ialah 202 dengan data: satu Message bagi setiap penerima, mengikut susunan to.
curl -X POST https://wbiztool.com/api/v2/messages/batch \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: opening-hours-2026-10-20" \
  -d '{
    "from": 101,
    "to": [
      { "phone": "+919876543210" },
      { "phone": "+447700900123" },
      { "group": "Bakery staff" }
    ],
    "text": "We open at 10 tomorrow."
  }'

Respons (202), satu Message bagi setiap penerima; yang kedua dan ketiga kelihatan seperti yang pertama, dengan to ditetapkan kepada {"phone": "+447700900123", …} dan {"group": "Bakery staff", …}:

{
  "data": [
    {
      "id": 9817264,
      "status": "queued",
      "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
      "to": { "phone": "+919876543210", "contact_id": 991 },
      "text": "We open at 10 tomorrow.",
      "media": null,
      "send_at": null,
      "expires_at": null,
      "created_at": "2026-10-19T16:02:40.118Z",
      "sent_at": null,
      "error": null
    }
  ]
}

Ralat semasa menghantar kelompok#

Sama seperti semasa menghantar satu mesej, dengan kedudukan penerima dalam field (to[0].phone), dan juga:

HTTPKodBila
400too_many_recipientsto mempunyai lebih daripada 1,000 entri
400validation_failedto kosong atau bukan senarai
402no_creditsSenarai tidak muat dalam baki mesej: requested dan remaining menunjukkan berapa banyak lebihnya
429number_daily_cap_reachedSenarai tidak muat dalam ruang nombor untuk 24 jam yang akan datang: requested dan room menunjukkan jumlahnya

Senaraikan mesej#

GEThttps://wbiztool.com/api/v2/messages

Mesej ruang kerja dalam 90 hari yang lalu, yang terbaharu dahulu, dalam halaman. Ini termasuk mesej yang dihantar dari papan pemuka, kempen, peringatan, integrasi dan API v1, bukan hanya mesej API v2. Kunci yang dihadkan kepada sebahagian nombor hanya melihat mesej nombor itu.

Parameter pertanyaan

numberintegerpilihan

Hanya mesej daripada id nombor ini.

statusstringpilihan

Hanya mesej dengan status ini: queued, scheduled, sent, delivered, read, failed, cancelled atau expired.

sincestringpilihan

Hanya mesej yang dicipta pada atau selepas masa ini (ISO 8601 dengan ofset).

untilstringpilihan

Hanya mesej yang dicipta sebelum masa ini (ISO 8601 dengan ofset).

limitintegerpilihan

Mesej bagi setiap halaman, 1 hingga 100 (lalai 25).

cursorstringpilihan

next_cursor halaman terakhir, dengan penapis yang sama.

Penapis boleh digabungkan. Dalam rentetan pertanyaan, tulis + pada ofset sebagai %2B (+ biasa tiba sebagai ruang, yang turut dibaca sebagai +), atau gunakan Z.

curl -G https://wbiztool.com/api/v2/messages \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY" \
  --data-urlencode "status=failed" \
  --data-urlencode "since=2026-10-01T00:00:00+05:30" \
  --data-urlencode "limit=100"

Responsnya ialah {"data": [Message, …], "next_cursor": "…" or null}.

Ralat semasa menyenaraikan#

HTTPKodBila
400validation_failednumber bukan ID nombor, status bukan salah satu status, atau limit bukan 1 hingga 100
400invalid_datetimesince atau until bukan ISO 8601 dengan ofset
400invalid_cursorKursor rosak atau dicipta dengan penapis lain

Dapatkan mesej#

GEThttps://wbiztool.com/api/v2/messages/{id}

Satu mesej dan statusnya sekarang.

curl https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Respons (200), mesej yang telah sampai:

{
  "id": 9817263,
  "status": "delivered",
  "from": { "id": 101, "phone": "919800000000", "platform": "whatsapp" },
  "to": { "phone": "+919876543210", "contact_id": 991 },
  "text": "Hi Asha, your order #1042 is ready.",
  "media": null,
  "send_at": null,
  "expires_at": null,
  "created_at": "2026-10-18T10:15:02.311Z",
  "sent_at": "2026-10-18T10:15:09.870Z",
  "error": null
}

Mesej yang tidak wujud, milik ruang kerja lain, atau (bagi kunci yang dihadkan kepada sebahagian nombor) dihantar dari nombor lain menjawab 404 message_not_found.

Batalkan mesej#

DELETEhttps://wbiztool.com/api/v2/messages/{id}

Membatalkan mesej yang masih menunggu (queued atau scheduled), tidak kira siapa yang menciptanya. Responsnya ialah 200 dengan Message, kini berstatus cancelled. Endpoint webhook mendapat message.cancelled.

Mesej yang telah dihantar tidak boleh ditarik semula. Mesej yang sedang diambil oleh nombor penghantar pada saat itu mungkin masih dihantar, jadi semak statusnya selepas itu jika ia penting.

curl -X DELETE https://wbiztool.com/api/v2/messages/9817263 \
  -H "Authorization: Bearer $WBIZTOOL_API_KEY"

Ralat semasa membatalkan#

HTTPKodBila
404message_not_foundTiada mesej sedemikian untuk kunci ini
409not_cancellableIa tidak lagi menunggu; status dalam ralat menyatakan statusnya sekarang, seperti sent

Objek Message#

Setiap operasi di halaman ini menjawab dengan objek Message, dan peristiwa webhook membawa satu dalam data.message.

MedanJenisPenerangan
idintegerID mesej. Gunakannya untuk mendapatkan atau membatalkan mesej.
statusstringKedudukannya sekarang. Lihat Status.
fromobjectNombor penghantar: id, phone (digitnya dengan kod negara, tanpa +) dan platform (whatsapp atau telegram).
toobjectPenerima: phone (dengan +), group atau username, dan contact_id, kenalan yang disimpan yang menerimanya. Nombor telefon atau kumpulan yang dihantar buat kali pertama disimpan sebagai kenalan. (contact_id ialah null hanya bagi mesej ujian kepada nombor yang tidak disimpan.)
textstringTeks atau kapsyen; "" apabila tiada.
mediaobject or nulltype (image atau file), url dan file_name (null bagi imej). url mungkin pautan yang berfungsi untuk masa terhad sahaja; jangan simpannya.
send_atstring or nullMasa ia dijadualkan, atau null untuk "sekarang".
expires_atstring or nullMasa selepasnya ia tidak dihantar, atau null.
created_atstringBila ia dicipta.
sent_atstring or nullBila ia dihantar, setelah ia dihantar (sent, delivered atau read).
errorobject or nullBagi mesej failed atau expired, message menyatakan sebabnya, seperti File exceeds WhatsApp size limit (16MB max). Jika tidak, null.

Status#

StatusMaksud
queuedMenunggu untuk dihantar.
scheduledMenunggu send_at-nya.
sentDihantar dari nombor anda (satu tanda di WhatsApp).
deliveredSampai ke telefon penerima (dua tanda).
readDibaca oleh penerima (tanda biru).
failedIa tidak dapat dihantar; error.message menyatakan sebabnya.
cancelledDibatalkan sebelum dihantar: dengan Batalkan mesej, dari papan pemuka, atau kerana nombor atau kempennya dibuang.
expiredTidak dihantar sebelum expires_at-nya.

queued dan scheduled boleh dibatalkan. sent masih boleh menjadi delivered dan kemudian read. failed, cancelled, expired dan read adalah muktamad. Webhook melaporkan sent, failed, cancelled dan expired; untuk melihat delivered dan read, dapatkan mesej itu.

Penerima#

to menerima tepat satu daripada medan ini:

MedanContohSiapa yang menerimanya
phone{"phone": "+919876543210"}Nombor telefon dalam format antarabangsa dengan + (E.164). Ruang dan sengkang dibenarkan.
group{"group": "Bakery staff"}Kumpulan WhatsApp yang disertai oleh nombor penghantar, mengikut nama tepatnya (sehingga 200 aksara).
contact_id{"contact_id": 991}Kenalan yang disimpan dalam ruang kerja, mengikut ID-nya (contohnya contact_id daripada mesej sebelumnya). Ia dihantar ke nombor atau kumpulan kenalan itu.
username{"username": "@asha_bakes"}Pengguna Telegram: @name, pautan t.me/name, atau tg: diikuti ID pengguna. Hanya dari akaun Telegram, jadi berikan satu sebagai from (atau pastikan tepat satu disambungkan).

Penghantaran ke kumpulan dan Telegram memerlukan nombor penghantar berada dalam kumpulan itu atau dapat menghubungi pengguna itu; masalah di sana muncul sebagai mesej failed, bukan sebagai ralat semasa anda menghantar.

Media#

media menghantar imej atau fail, dengan text sebagai kapsyennya. Berikan tepat satu daripada url atau media_id:

media.urlstringSama ada url atau media_id

Pautan http atau https awam ke fail, sehingga 1,000 aksara. Pautan ke alamat peribadi atau setempat ditolak dengan invalid_media_url.

media.media_idintegerSama ada url atau media_id

Fail dalam Direktori media ruang kerja, daripada Muat naik fail. Muat naik fail sekali dan hantarnya sekerap yang anda mahu.

media.typestringpilihan

image atau file. Jika tidak disertakan, pautan yang berakhir dengan .jpg, .jpeg, .png, .gif atau .webp dihantar sebagai imej dan yang lain sebagai fail; media_id menggunakan jenis yang digunakan semasa fail dimuat naik.

media.file_namestringpilihan

Bagi file: nama yang dilihat oleh penerima, seperti invoice-1042.pdf (sehingga 100 aksara). Jika tidak disertakan, nama diambil daripada pautan atau fail yang dimuat naik. Sambungan failnya menentukan cara fail dihantar, jadi sertakan satu. Diabaikan bagi imej.

{
  "to": { "phone": "+919876543210" },
  "text": "Your invoice for order #1042",
  "media": { "url": "https://example.com/invoices/1042.pdf", "type": "file", "file_name": "invoice-1042.pdf" }
}

Fail diambil semasa mesej dihantar, bukan semasa anda memanggil API, jadi pautan yang rosak atau fail yang terlalu besar muncul sebagai mesej failed dengan sebabnya dalam error.message. Peraturan saiz dan jenis adalah sama seperti v1: lihat Menghantar imej dan fail.

Penjadualan dan tamat tempoh#

  • send_at menjadualkan mesej. Ia kekal scheduled sehingga masa itu dan boleh dibatalkan sehingga ia dihantar. Tulis masa dengan ofsetnya, jadi 2026-10-20T09:30:00+05:30 bermaksud 09:30 di India. Untuk mesej yang berulang, gunakan peringatan.
  • expires_at ialah tarikh akhir: jika mesej belum dihantar menjelang masa itu (contohnya nombor telah log keluar), ia menjadi expired dan bukannya dihantar lewat. Gunakannya untuk kod sekali guna, masa penghantaran dan tawaran. Tugas latar belakang menandakannya tamat tempoh sekurang-kurangnya 30 saat selepas tarikh akhir, jadi jangan bergantung pada tarikh akhir yang lebih pendek daripada seminit.
  • Kedua-duanya mesti pada masa hadapan, dan expires_at mesti selepas send_at.

Berkaitan#

  • Webhook: dapatkan message.sent dan message.failed tanpa meninjau berulang kali.
  • Media: muat naik fail untuk dihantar dengan media_id.
  • Nombor: id untuk digunakan sebagai from.
  • Ralat