İçeriğe geç
WbizTool

API v2 (beta)

Mesajlar

Bir telefon numarasına, bir WhatsApp grubuna, kayıtlı bir kişiye veya bir Telegram kullanıcı adına hemen ya da belirlediğiniz bir saatte mesaj gönderin. Aynı mesajı tek bir istekte en fazla 1.000 alıcıya gönderin, geçmişi okuyun, bir mesajın durumunu takip edin ve beklerken iptal edin.

İşlemEndpointKapsam
Mesaj gönderinPOST /api/v2/messagesmessages:send
Birçok alıcıya gönderinPOST /api/v2/messages/batchmessages:send
Mesajları listeleyinGET /api/v2/messagesmessages:read
Bir mesajı alınGET /api/v2/messages/{id}messages:read
Bir mesajı iptal edinDELETE /api/v2/messages/{id}messages:send

Anahtarlar, hatalar, Idempotency-Key ve sınırlar API v2'ye genel bakış sayfasında anlatıldığı gibi çalışır. Bir mesajın gönderildiğini veya başarısız olduğunu sürekli sorgulamadan öğrenmek için bir webhook uç noktası ekleyin.

Mesaj gönderin#

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

Gövde: JSON (application/json)

Mesaj kuyruğa alınır ve yanıt, mesaj gönderilmeden önce gelir: HTTP 202 ve queued durumundaki (gelecekte bir send_at varsa scheduled durumundaki) Message. Mesajı Bir mesajı alın veya bir webhook ile takip edin.

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

Yanıt (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
}

Gövde

toobjectzorunlu

Mesajı kimin alacağı: phone, group, contact_id veya username alanlarından tam olarak biri. Bkz. Alıcılar.

frominteger or nullÇalışma alanında tek bir bağlı numara yoksa zorunlu

Mesajı gönderen numaranın id değeri; Numaraları listeleyin ile alınır. Gönderilmezse bağlı tek numara gönderir: bir Telegram hesabı da bağlı olsa bile bağlı tek WhatsApp numarası kullanılır; bir Telegram hesabı ise yalnızca hiçbir WhatsApp numarası bağlı değilken kullanılır. Oturumu kapanmış bir numara da kabul edilir: mesajları numara yeniden bağlanana kadar bekler.

textstringMedya gönderilmiyorsa zorunlu

Mesaj, en fazla 3.000 karakter. media ile birlikte açıklama (caption) olur ve gönderilmeyebilir. WhatsApp biçimlendirmesi çalışır: *bold*, _italic_, ~strikethrough~. JSON'da yeni satırları \n olarak yazın.

mediaobject or nullisteğe bağlı

Gönderilecek bir görsel veya dosya. Bkz. Medya.

send_atstring or nullisteğe bağlı

Hemen değil, bu saatte gönderin: ofsetiyle birlikte ISO 8601, örneğin 2026-10-20T09:30:00+05:30. Gelecekte olmalıdır. Bkz. Zamanlama ve geçerlilik süresi.

expires_atstring or nullisteğe bağlı

Bu saatten sonra göndermeyin: mesaj bunun yerine expired olur. Ofsetiyle birlikte ISO 8601; gelecekte ve send_at değerinden sonra olmalıdır.

Başlıklar

Authorizationheaderzorunlu

Bearer wbz_live_…, messages:send kapsamına sahip bir anahtar.

Idempotency-Keyheaderisteğe bağlı

Benzersiz herhangi bir metin; böylece yeniden deneme asla ikinci bir mesaj göndermez. Bkz. Idempotency-Key.

Gönderirken oluşan hatalar#

HTTPKodNe zaman
400validation_failedBir alan eksik, türü yanlış veya bilinmiyor; to alanlarından hiçbirini ya da birden fazlasını içeriyor; media hem url hem media_id içeriyor ya da ikisini de içermiyor; expires_at, send_at değerinden sonra değil
400text_requiredNe text ne de media var
400text_too_longtext 3.000 karakterden uzun
400invalid_datetimesend_at veya expires_at ofsetli ISO 8601 değil
402no_creditsÇalışma alanının planında mesajı kalmadı
403number_not_allowedAnahtar başka numaralarla sınırlı
403account_disabledÇalışma alanı sahibinin hesabı devre dışı
422invalid_phoneto.phone, + ile uluslararası biçimde bir telefon numarası değil
422invalid_usernameto.username bir Telegram kullanıcı adı, bağlantısı veya tg: kimliği değil
422username_needs_telegramfrom olarak bir WhatsApp numarasıyla to.username gönderildi
422contact_not_foundBu to.contact_id ile bir kişi yok
422media_not_foundBu media.media_id ile bir dosya yok
422invalid_media_urlmedia.url herkese açık bir http(s) bağlantısı değil
422time_in_pastsend_at veya expires_at zaten geçmiş
422number_not_foundfrom bu çalışma alanının bir numarası değil
422from_requiredfrom yok ve çalışma alanında hiç bağlı numara yok ya da birden fazla var
422message_rejectedMesaj kuyruğa alınamadı; nedenini message söyler
429number_daily_cap_reachedNumara son 24 saatte 1.000 mesaj gönderdi

Reddedilen bir gönderim geride hiçbir şey bırakmaz: hiçbir mesaj kaydedilmez, bu yüzden iptal edilecek bir şey de yoktur. Her istekte oluşabilecek hatalar (anahtarlar, kapsamlar, hız sınırları, Idempotency-Key) hatalar sayfasındadır.

Birçok alıcıya gönderin#

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

Gövde: JSON (application/json)

Aynı mesajı en fazla 1.000 alıcıya gönderir. Gövde Mesaj gönderin ile aynıdır; tek fark, to alanının bir alıcı listesi olmasıdır.

  • Ya hepsi ya hiçbiri. Herhangi bir şey kuyruğa alınmadan önce her alıcı kontrol edilir ve listenin tamamı hem planda kalan mesajlara hem de gönderen numaranın önümüzdeki 24 saatteki kalan kapasitesine sığmalıdır. Bir alıcı hatalıysa hiçbir şey kuyruğa alınmaz ve field o alıcıyı belirtir, örneğin to[3].phone.
  • Aynı alıcı iki kez yazılırsa tek bir mesaj alır.
  • Yanıt, data ile birlikte 202 olur: to sırasına göre her alıcı için bir Message.
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."
  }'

Yanıt (202), her alıcı için bir Message; ikinci ve üçüncüsü birincisine benzer, yalnızca to değerleri {"phone": "+447700900123", …} ve {"group": "Bakery staff", …} olur:

{
  "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
    }
  ]
}

Toplu gönderimde oluşan hatalar#

Tek bir mesaj gönderirken oluşanlarla aynıdır; alıcının sırası field içinde yer alır (to[0].phone). Bunlara ek olarak:

HTTPKodNe zaman
400too_many_recipientsto 1.000'den fazla öğe içeriyor
400validation_failedto boş veya bir liste değil
402no_creditsListe kalan mesajlara sığmıyor: ne kadar aştığını requested ve remaining söyler
429number_daily_cap_reachedListe numaranın önümüzdeki 24 saatteki kalan kapasitesine sığmıyor: kaç mesaj olduğunu requested ve room söyler

Mesajları listeleyin#

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

Çalışma alanının son 90 güne ait mesajları, en yeniler önce, sayfalar hâlinde. Buna yalnızca API v2 mesajları değil, panelden, kampanyalardan, hatırlatıcılardan, entegrasyonlardan ve API v1'den gönderilen mesajlar da dahildir. Bazı numaralarla sınırlı bir anahtar yalnızca o numaraların mesajlarını görür.

Sorgu parametreleri

numberintegeristeğe bağlı

Yalnızca bu numara id değerinden gönderilen mesajlar.

statusstringisteğe bağlı

Yalnızca bu durumdaki mesajlar: queued, scheduled, sent, delivered, read, failed, cancelled veya expired.

sincestringisteğe bağlı

Yalnızca bu saatte veya sonrasında oluşturulan mesajlar (ofsetli ISO 8601).

untilstringisteğe bağlı

Yalnızca bu saatten önce oluşturulan mesajlar (ofsetli ISO 8601).

limitintegeristeğe bağlı

Sayfa başına mesaj sayısı, 1 ile 100 arası (varsayılan 25).

cursorstringisteğe bağlı

Önceki sayfanın next_cursor değeri, aynı filtrelerle.

Filtreler birlikte kullanılabilir. Sorgu metninde bir ofsetin + işaretini %2B olarak yazın (düz bir + boşluk olarak gelir ve o da + olarak okunur) veya Z kullanın.

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"

Yanıt {"data": [Message, …], "next_cursor": "…" or null} biçimindedir.

Listelerken oluşan hatalar#

HTTPKodNe zaman
400validation_failednumber bir numara kimliği değil, status durumlardan biri değil veya limit 1 ile 100 arasında değil
400invalid_datetimesince veya until ofsetli ISO 8601 değil
400invalid_cursorCursor bozuk veya başka filtrelerle oluşturulmuş

Bir mesajı alın#

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

Tek bir mesaj ve şu anki durumu.

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

Yanıt (200), teslim edilmiş bir mesaj:

{
  "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
}

Var olmayan, başka bir çalışma alanına ait olan veya (bazı numaralarla sınırlı bir anahtar için) başka bir numaradan gönderilmiş bir mesaj 404 message_not_found döndürür.

Bir mesajı iptal edin#

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

Hâlâ bekleyen (queued veya scheduled) bir mesajı, kimin oluşturduğundan bağımsız olarak iptal eder. Yanıt, artık cancelled durumundaki Message ile birlikte 200 olur. Bir webhook uç noktası message.cancelled alır.

Gönderilmiş bir mesaj geri alınamaz. Gönderen numaranın tam o anda işleme aldığı bir mesaj yine de gönderilebilir; bu önemliyse ardından durumunu kontrol edin.

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

Mesaj iptalinde oluşan hatalar#

HTTPKodNe zaman
404message_not_foundBu anahtar için böyle bir mesaj yok
409not_cancellableMesaj artık beklemiyor; hatadaki status şu anki durumunu söyler, örneğin sent

Message nesnesi#

Bu sayfadaki her işlem Message nesneleriyle yanıt verir ve webhook olayları data.message içinde bir tane taşır.

AlanTürAçıklama
idintegerMesajın kimliği. Mesajı almak veya iptal etmek için kullanın.
statusstringMesajın şu an nerede olduğu. Bkz. Durumlar.
fromobjectGönderen numara: id, phone (ülke koduyla birlikte rakamları, + olmadan) ve platform (whatsapp veya telegram).
toobjectAlıcı: phone (+ ile), group veya username ve mesajın gittiği kayıtlı kişi olan contact_id. İlk kez mesaj gönderilen bir telefon numarası veya grup kişi olarak kaydedilir. (contact_id yalnızca kayıtlı olmayan bir numaraya gönderilen bir test mesajında null olur.)
textstringMetin veya açıklama; yoksa "".
mediaobject or nulltype (image veya file), url ve file_name (görsellerde null). url sınırlı bir süre çalışan bir bağlantı olabilir; saklamayın.
send_atstring or nullMesajın zamanlandığı saat veya "hemen" için null.
expires_atstring or nullBu saatten sonra mesaj gönderilmez; ya da null.
created_atstringMesajın oluşturulduğu zaman.
sent_atstring or nullMesajın gönderildiği zaman, gönderildikten sonra (sent, delivered veya read).
errorobject or nullfailed veya expired bir mesajda message nedenini söyler, örneğin File exceeds WhatsApp size limit (16MB max). Diğer durumlarda null.

Durumlar#

DurumAnlamı
queuedGönderilmeyi bekliyor.
scheduledsend_at saatini bekliyor.
sentNumaranızdan gönderildi (WhatsApp'ta tek tik).
deliveredAlıcının telefonuna teslim edildi (iki tik).
readAlıcı tarafından okundu (mavi tikler).
failedGönderilemedi; nedenini error.message söyler.
cancelledGönderilmeden önce iptal edildi: Bir mesajı iptal edin ile, panelden veya numarası ya da kampanyası kaldırıldığı için.
expiredexpires_at saatinden önce gönderilemedi.

queued ve scheduled iptal edilebilir. sent daha sonra delivered ve ardından read olabilir. failed, cancelled, expired ve read son durumlardır. Webhook'lar sent, failed, cancelled ve expired durumlarını bildirir; delivered ve read durumlarını görmek için mesajı alın.

Alıcılar#

to bu alanlardan tam olarak birini alır:

AlanÖrnekKim alır
phone{"phone": "+919876543210"}+ ile uluslararası biçimde (E.164) bir telefon numarası. Boşluk ve tireye izin verilir.
group{"group": "Bakery staff"}Gönderen numaranın üyesi olduğu bir WhatsApp grubu, tam adıyla (en fazla 200 karakter).
contact_id{"contact_id": 991}Çalışma alanında kayıtlı bir kişi, kimliğiyle (örneğin önceki bir mesajın contact_id değeri). Mesaj o kişinin numarasına veya grubuna gider.
username{"username": "@asha_bakes"}Bir Telegram kullanıcısı: @name, bir t.me/name bağlantısı veya tg: ve bir kullanıcı kimliği. Yalnızca bir Telegram hesabından gönderilebilir; bu yüzden from olarak bir Telegram hesabı verin (veya yalnızca bir tane bağlı olsun).

Grup ve Telegram gönderimlerinde gönderen numaranın o grupta olması veya o kullanıcıya ulaşabilmesi gerekir; buradaki sorunlar gönderirken hata olarak değil, failed bir mesaj olarak görünür.

Medya#

media, açıklaması text olan bir görsel veya dosya gönderir. url veya media_id alanlarından tam olarak birini verin:

media.urlstringurl veya media_id'den biri

Dosyaya giden herkese açık bir http veya https bağlantısı, en fazla 1.000 karakter. Özel veya yerel adreslere giden bağlantılar invalid_media_url ile reddedilir.

media.media_idintegerurl veya media_id'den biri

Çalışma alanının Medya klasöründeki bir dosya; Dosya yükleyin ile alınır. Bir dosyayı bir kez yükleyin ve istediğiniz kadar gönderin.

media.typestringisteğe bağlı

image veya file. Gönderilmezse .jpg, .jpeg, .png, .gif veya .webp ile biten bir bağlantı görsel olarak, diğer her şey dosya olarak gönderilir; bir media_id ise dosyanın yüklendiği türü kullanır.

media.file_namestringisteğe bağlı

Bir file için: alıcının gördüğü ad, örneğin invoice-1042.pdf (en fazla 100 karakter). Gönderilmezse ad bağlantıdan veya yüklenen dosyadan alınır. Dosyanın nasıl gönderileceğini uzantısı belirler, bu yüzden bir uzantı ekleyin. Görsellerde yok sayılır.

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

Dosya API'yi çağırdığınızda değil, mesaj gönderilirken alınır; bu yüzden bozuk bir bağlantı veya çok büyük bir dosya, nedeni error.message içinde yazan failed bir mesaj olarak görünür. Boyut ve tür kuralları v1'dekilerle aynıdır: bkz. Görsel ve dosya gönderme.

Zamanlama ve geçerlilik süresi#

  • send_at mesajı zamanlar. Mesaj o saate kadar scheduled kalır ve gönderilene kadar iptal edilebilir. Saati ofsetiyle birlikte yazın; örneğin 2026-10-20T09:30:00+05:30, Hindistan saatiyle 09:30 demektir. Tekrarlanan mesajlar için hatırlatıcıları kullanın.
  • expires_at bir son tarihtir: mesaj o saate kadar gönderilmemişse (örneğin numaranın oturumu kapalıysa) geç gönderilmek yerine expired olur. Tek kullanımlık kodlar, teslimat saatleri ve kampanyalı teklifler için kullanın. Bir arka plan işi mesajı son tarihten en az 30 saniye sonra süresi dolmuş olarak işaretler; bu yüzden bir dakikadan kısa son tarihlere güvenmeyin.
  • İkisi de gelecekte olmalıdır ve expires_at, send_at değerinden sonra olmalıdır.

İlgili sayfalar#

  • Webhook'lar: sürekli sorgulamak yerine message.sent ve message.failed alın.
  • Medya: media_id ile göndermek için dosya yükleyin.
  • Numaralar: from olarak kullanılacak id.
  • Hatalar