Langsung ke konten
WbizTool

API v2 (beta)

Pesan

Kirim pesan sekarang atau pada waktu yang ditentukan, ke nomor telepon, grup WhatsApp, kontak tersimpan, atau username Telegram. Kirim pesan yang sama ke hingga 1.000 penerima dalam satu request, baca riwayat, ikuti status pesan, dan batalkan selama pesan masih menunggu.

OperasiEndpointScope
Mengirim pesanPOST /api/v2/messagesmessages:send
Mengirim ke banyak penerimaPOST /api/v2/messages/batchmessages:send
Daftar pesanGET /api/v2/messagesmessages:read
Mengambil pesanGET /api/v2/messages/{id}messages:read
Membatalkan pesanDELETE /api/v2/messages/{id}messages:send

Kunci, error, Idempotency-Key, dan batas berfungsi seperti dijelaskan di Ikhtisar API v2. Untuk mengetahui kapan pesan terkirim atau gagal tanpa polling, tambahkan endpoint webhook.

Mengirim pesan#

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

Body: JSON (application/json)

Pesan masuk antrean dan respons datang sebelum pesan dikirim, dengan HTTP 202 dan Message berstatus queued (atau scheduled jika send_at di masa mendatang). Ikuti pesan dengan Mengambil pesan 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
}

Body

toobjectwajib

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

frominteger or nullWajib kecuali workspace memiliki satu nomor yang terhubung

id nomor yang mengirimnya, dari Daftar nomor. Jika tidak dikirim, satu-satunya nomor yang terhubung yang mengirimnya: satu nomor WhatsApp yang terhubung tetap digunakan meskipun ada akun Telegram yang juga terhubung, dan akun Telegram hanya digunakan jika tidak ada nomor WhatsApp yang terhubung. Nomor yang sedang logout tetap diterima: pesannya menunggu sampai nomor itu terhubung kembali.

textstringWajib kecuali media dikirim

Isi pesan, maksimal 3.000 karakter. Dengan media, ini menjadi keterangan (caption) dan boleh tidak dikirim. Format WhatsApp berfungsi: *bold*, _italic_, ~strikethrough~. Di JSON, tulis baris baru sebagai \n.

mediaobject or nullopsional

Gambar atau file yang dikirim. Lihat Media.

send_atstring or nullopsional

Kirim pada waktu ini, bukan sekarang: ISO 8601 dengan offset-nya, seperti 2026-10-20T09:30:00+05:30. Waktunya harus di masa mendatang. Lihat Penjadwalan dan kedaluwarsa.

expires_atstring or nullopsional

Jangan kirim setelah waktu ini: pesan menjadi expired. ISO 8601 dengan offset-nya, di masa mendatang dan setelah send_at.

Header

Authorizationheaderwajib

Bearer wbz_live_…, kunci dengan scope messages:send.

Idempotency-Keyheaderopsional

String unik apa pun, sehingga percobaan ulang tidak pernah mengirim pesan kedua. Lihat Idempotency-Key.

Error saat mengirim#

HTTPKodeKapan
400validation_failedAda field yang hilang, jenisnya salah, atau tidak dikenal; to tidak memiliki satu pun atau memiliki beberapa field-nya; media memiliki url dan media_id sekaligus atau tidak satu pun; expires_at tidak setelah send_at
400text_requiredTidak ada text dan tidak ada media
400text_too_longtext lebih dari 3.000 karakter
400invalid_datetimesend_at atau expires_at bukan ISO 8601 dengan offset
402no_creditsPesan di paket workspace sudah habis
403number_not_allowedKunci dibatasi ke nomor lain
403account_disabledAkun pemilik workspace dinonaktifkan
422invalid_phoneto.phone bukan nomor telepon dalam format internasional dengan +
422invalid_usernameto.username bukan username, tautan, atau ID tg: Telegram
422username_needs_telegramto.username dengan nomor WhatsApp sebagai from
422contact_not_foundTidak ada kontak dengan to.contact_id tersebut
422media_not_foundTidak ada file dengan media.media_id tersebut
422invalid_media_urlmedia.url bukan tautan http(s) publik
422time_in_pastsend_at atau expires_at sudah lewat
422number_not_foundfrom bukan nomor workspace ini
422from_requiredTidak ada from, dan workspace tidak memiliki nomor yang terhubung atau memiliki beberapa
422message_rejectedPesan tidak dapat dimasukkan ke antrean; message menyebutkan alasannya
429number_daily_cap_reachedNomor ini sudah mengirim 1.000 pesan dalam 24 jam terakhir

Pengiriman yang ditolak tidak meninggalkan apa pun: tidak ada pesan yang disimpan, jadi tidak ada yang perlu dibatalkan. Error yang dapat terjadi pada request apa pun (kunci, scope, batas laju, Idempotency-Key) ada di halaman error.

Mengirim ke banyak penerima#

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

Body: JSON (application/json)

Mengirim pesan yang sama ke hingga 1.000 penerima. Body-nya sama dengan Mengirim pesan, kecuali to berupa daftar penerima.

  • Semua atau tidak sama sekali. Setiap penerima diperiksa sebelum apa pun masuk antrean, dan seluruh daftar harus muat dalam sisa pesan paket dan dalam kapasitas nomor pengirim untuk 24 jam ke depan. Jika satu penerima salah, tidak ada yang masuk antrean, dan field menyebutkannya, seperti to[3].phone.
  • Penerima yang sama dua kali mendapat satu pesan.
  • Responsnya 202 dengan data: satu Message per penerima, sesuai urutan 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 per penerima; yang kedua dan ketiga mirip dengan yang pertama, dengan to berisi {"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
    }
  ]
}

Error saat mengirim batch#

Sama seperti saat mengirim satu pesan, dengan posisi penerima di field (to[0].phone), ditambah:

HTTPKodeKapan
400too_many_recipientsto berisi lebih dari 1.000 entri
400validation_failedto kosong atau bukan daftar
402no_creditsDaftar tidak muat dalam sisa pesan: requested dan remaining menunjukkan selisihnya
429number_daily_cap_reachedDaftar tidak muat dalam kapasitas nomor untuk 24 jam ke depan: requested dan room menunjukkan jumlahnya

Daftar pesan#

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

Pesan workspace dalam 90 hari terakhir, yang terbaru lebih dulu, dalam halaman. Ini termasuk pesan yang dikirim dari dashboard, kampanye, pengingat, integrasi, dan API v1, bukan hanya dari API v2. Kunci yang dibatasi ke sebagian nomor hanya melihat pesan dari nomor-nomor itu.

Parameter query

numberintegeropsional

Hanya pesan dari id nomor ini.

statusstringopsional

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

sincestringopsional

Hanya pesan yang dibuat pada atau setelah waktu ini (ISO 8601 dengan offset).

untilstringopsional

Hanya pesan yang dibuat sebelum waktu ini (ISO 8601 dengan offset).

limitintegeropsional

Pesan per halaman, 1 hingga 100 (default 25).

cursorstringopsional

next_cursor dari halaman terakhir, dengan filter yang sama.

Filter dapat digabungkan. Di query string, tulis + pada offset sebagai %2B (+ biasa tiba sebagai spasi, yang juga 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 {"data": [Message, …], "next_cursor": "…" or null}.

Error saat menampilkan daftar#

HTTPKodeKapan
400validation_failednumber bukan ID nomor, status bukan salah satu status, atau limit tidak di antara 1 dan 100
400invalid_datetimesince atau until bukan ISO 8601 dengan offset
400invalid_cursorCursor rusak atau dibuat dengan filter lain

Mengambil pesan#

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

Satu pesan beserta statusnya saat ini.

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

Respons (200), pesan yang sudah 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
}

Pesan yang tidak ada, milik workspace lain, atau (untuk kunci yang dibatasi ke sebagian nomor) dikirim dari nomor lain dijawab dengan 404 message_not_found.

Membatalkan pesan#

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

Membatalkan pesan yang masih menunggu (queued atau scheduled), siapa pun yang membuatnya. Responsnya 200 dengan Message, yang kini berstatus cancelled. Endpoint webhook mendapat message.cancelled.

Pesan yang sudah dikirim tidak dapat ditarik kembali. Pesan yang sedang diambil oleh nomor pengirim pada saat itu mungkin tetap terkirim, jadi periksa statusnya setelahnya jika hal ini penting.

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

Error saat membatalkan#

HTTPKodeKapan
404message_not_foundTidak ada pesan seperti itu untuk kunci ini
409not_cancellablePesan sudah tidak menunggu; status di error menyebutkan statusnya sekarang, seperti sent

Objek Message#

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

FieldJenisKeterangan
idintegerID pesan. Gunakan untuk mengambil atau membatalkan pesan.
statusstringPosisi pesan saat ini. Lihat Status.
fromobjectNomor pengirim: id, phone (digitnya dengan kode negara, tanpa +), dan platform (whatsapp atau telegram).
toobjectPenerima: phone (dengan +), group, atau username, serta contact_id, kontak tersimpan yang dituju. Nomor telepon atau grup yang baru pertama kali dikirimi disimpan sebagai kontak. (contact_id bernilai null hanya untuk pesan uji ke nomor yang tidak tersimpan.)
textstringTeks atau keterangan; "" jika tidak ada.
mediaobject or nulltype (image atau file), url, dan file_name (null untuk gambar). url dapat berupa tautan yang hanya berlaku sementara; jangan simpan.
send_atstring or nullWaktu pesan dijadwalkan, atau null untuk "sekarang".
expires_atstring or nullWaktu setelahnya pesan tidak dikirim, atau null.
created_atstringKapan pesan dibuat.
sent_atstring or nullKapan pesan dikirim, setelah terkirim (sent, delivered, atau read).
errorobject or nullUntuk pesan failed atau expired, message menyebutkan alasannya, seperti File exceeds WhatsApp size limit (16MB max). Selain itu null.

Status#

StatusArti
queuedMenunggu untuk dikirim.
scheduledMenunggu send_at-nya.
sentTerkirim dari nomor Anda (satu centang di WhatsApp).
deliveredSampai di ponsel penerima (dua centang).
readDibaca oleh penerima (centang biru).
failedTidak dapat dikirim; error.message menyebutkan alasannya.
cancelledDibatalkan sebelum dikirim: dengan Membatalkan pesan, dari dashboard, atau karena nomor atau kampanyenya dihapus.
expiredTidak terkirim sebelum expires_at-nya.

queued dan scheduled dapat dibatalkan. sent masih dapat menjadi delivered lalu read. failed, cancelled, expired, dan read bersifat final. Webhook melaporkan sent, failed, cancelled, dan expired; untuk melihat delivered dan read, ambil pesannya.

Penerima#

to menerima tepat satu dari field berikut:

FieldContohSiapa yang menerimanya
phone{"phone": "+919876543210"}Nomor telepon dalam format internasional dengan + (E.164). Spasi dan tanda hubung boleh dipakai.
group{"group": "Bakery staff"}Grup WhatsApp tempat nomor pengirim menjadi anggota, berdasarkan nama persisnya (hingga 200 karakter).
contact_id{"contact_id": 991}Kontak yang tersimpan di workspace, berdasarkan ID-nya (misalnya contact_id dari pesan sebelumnya). Pesan dikirim ke nomor atau grup kontak tersebut.
username{"username": "@asha_bakes"}Pengguna Telegram: @name, tautan t.me/name, atau tg: diikuti ID pengguna. Hanya dari akun Telegram, jadi berikan akun Telegram sebagai from (atau pastikan tepat satu yang terhubung).

Pengiriman ke grup dan Telegram mengharuskan nomor pengirim berada di grup itu atau dapat menjangkau pengguna itu; masalah di sana muncul sebagai pesan failed, bukan sebagai error saat Anda mengirim.

Media#

media mengirim gambar atau file, dengan text sebagai keterangannya. Berikan tepat satu dari url atau media_id:

media.urlstringSalah satu dari url atau media_id

Tautan http atau https publik ke file, hingga 1.000 karakter. Tautan ke alamat privat atau lokal ditolak dengan invalid_media_url.

media.media_idintegerSalah satu dari url atau media_id

File di Direktori media workspace, dari Mengunggah file. Unggah file sekali dan kirim sesering yang Anda mau.

media.typestringopsional

image atau file. Jika tidak dikirim, tautan yang berakhiran .jpg, .jpeg, .png, .gif, atau .webp dikirim sebagai gambar dan yang lainnya sebagai file; media_id memakai jenis yang digunakan saat file diunggah.

media.file_namestringopsional

Untuk file: nama yang dilihat penerima, seperti invoice-1042.pdf (hingga 100 karakter). Jika tidak dikirim, nama diambil dari tautan atau file yang diunggah. Ekstensinya menentukan cara file dikirim, jadi sertakan ekstensi. Diabaikan untuk gambar.

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

File diambil saat pesan dikirim, bukan saat Anda memanggil API, sehingga tautan yang rusak atau file yang terlalu besar muncul sebagai pesan failed dengan alasannya di error.message. Aturan ukuran dan jenis file sama dengan v1: lihat Mengirim gambar dan file.

Penjadwalan dan kedaluwarsa#

  • send_at menjadwalkan pesan. Pesan tetap scheduled sampai waktu itu dan dapat dibatalkan sampai dikirim. Tulis waktu dengan offset-nya, jadi 2026-10-20T09:30:00+05:30 berarti pukul 09.30 di India. Untuk pesan berulang, gunakan pengingat.
  • expires_at adalah tenggat: jika pesan belum dikirim sampai saat itu (misalnya nomornya sedang logout), pesan menjadi expired alih-alih terkirim terlambat. Gunakan untuk kode sekali pakai, waktu pengantaran, dan penawaran. Proses latar belakang menandainya kedaluwarsa paling cepat 30 detik setelah tenggat, jadi jangan mengandalkan tenggat yang lebih pendek dari satu menit.
  • Keduanya harus di masa mendatang, dan expires_at harus setelah send_at.

Terkait#

  • Webhook: dapatkan message.sent dan message.failed tanpa polling.
  • Media: unggah file untuk dikirim dengan media_id.
  • Nomor: id yang dipakai sebagai from.
  • Error