İçeriğe geç
WbizTool

Mesajlaşma API'si

Mesaj gönderme API'si

Bağlı WhatsApp numaranızdan tek bir telefon numarasına WhatsApp metni, görseli veya belgesi gönderin. Sipariş onayları, ödeme hatırlatmaları, uyarılar ve destek yanıtları için kullanın.

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

Gövde: JSON, form alanları veya dosya yüklerken multipart/form-data

Mesaj kuyruğa alınır ve birkaç saniye içinde WhatsApp numaranızdan gönderilir. Yanıt, durumunu kontrol etmek için kullanabileceğiniz bir msg_id verir.

Hızlı örnek#

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

YOUR_API_KEY ve 678 değerlerini kendi anahtarınız ve numara ID'nizle değiştirin. Bunları nerede bulacağınız için Kimlik doğrulama bölümüne bakın. Anahtar Authorization: Bearer başlığına yazılır (önerilir); gövdede JSON veya form alanları olarak client_id ve api_key de çalışır – aşağıdaki örnekler bunları kullanır.

İstek parametreleri#

Kimlik doğrulama

AuthorizationheaderÖnerilir

Bearer YOUR_API_KEY: Ayarlar → API anahtarları sayfasındaki API anahtarınız. Bu başlıkla client_id ve api_key gövdeden çıkarılabilir; ikisi birden gönderilirse başlıktaki geçerli anahtar kullanılır. Bkz. Anahtarı başlıkta gönderin.

client_idintegerAuthorization başlığı olmadan

Ayarlar → API anahtarları sayfasındaki API Client ID'niz. Başlıkla isteğe bağlıdır; gönderirseniz anahtarın çalışma alanına ait olmalıdır.

api_keystringAuthorization başlığı olmadan

Aynı sayfadaki API anahtarınız; başlıkta göndermediğinizde.

whatsapp_clientintegerBirden fazla numaranız varsa zorunlu

Gönderimin yapılacağı WhatsApp numarasının veya Telegram hesabının ID'si; WhatsApp ayarları sayfasında bulunur. Bu alanı göndermezseniz bağlı tek numara kullanılır, önce WhatsApp: bir Telegram hesabı da bağlı olsa bile bağlı tek bir WhatsApp numarası kullanılır; bir Telegram hesabı ise yalnızca hiçbir WhatsApp numarası bağlı değilken kullanılır. Bir @username, bağlı tek Telegram hesabını kullanır. Hiçbir WhatsApp numarası bağlı değilken, tarayıcısı kapalı olan tek Chrome uzantısı numarası kullanılır; böylece mesaj başarısız olmak yerine bekler.

Alıcı ve mesaj

phonestringzorunlu

Alıcının WhatsApp numarası. Boşluklar, +, -, ., parantezler ve baştaki 00 sizin için kaldırılır, yani +91 98765-43210 çalışır. 919876543210.0 ve 9.19876543210E+11 gibi tablo değerleri rakamlarıyla okunur, ancak 9.19877E+11 gibi yuvarlanmış bir değer, rakamları eksik olduğu için reddedilir. Numarayı ya ülke koduyla birlikte (919876543210) ya da ülke kodu olmadan (9876543210) country_code ile birlikte gönderin. Baştaki 0 ile yazılmış yerel bir numara da çalışır: 09876543210, country_code 91 ile 919876543210 numarasına; 0612345678 ise 39 ile (İtalya, burada 0 numaranın parçasıdır) 390612345678 numarasına gider. + veya 00 ile yazılmış bir numara kendi ülke kodunu taşır: ona country_code eklenmez ve ülke kodundan sonra parantez içindeki (0) atılır; yani +44 (0)20 7946 0018, 442079460018 numarasına gider. Bir Telegram hesabından gönderirken phone bir @username, bir t.me/username bağlantısı veya tg:<id> da olabilir.

country_codestringisteğe bağlı

+ olmadan ülke telefon kodu; örneğin Hindistan için 91, ABD için 1. Numara zaten bununla başlamıyorsa ve + ya da 00 ile yazılmamışsa phone değerinin önüne eklenir. İstisna: 91 ile 10 haneli bir numaraya önek her zaman eklenir. Diğer kodlarda, aynı rakamlarla başlayan yerel bir numaraya önek eklenmez; bu yüzden onu ülke koduyla birlikte gönderin.

msg_typeintegeristeğe bağlı

0 metin (varsayılan), 1 görsel, 2 dosya veya belge.

msgstringmsg_type 0 olduğunda zorunlu

Mesaj metni, en fazla 3.000 karakter. Görsel ve dosyalarda açıklama metnidir ve boş olabilir. WhatsApp biçimlendirmesi çalışır: *bold*, _italic_, ~strikethrough~. message da takma ad olarak kabul edilir.

Görseller ve dosyalar

img_urlstringmsg_type 1 olduğunda ve dosya yüklenmediğinde zorunlu

Görselin herkese açık http veya https URL'si.

file_urlstringmsg_type 2 olduğunda ve dosya yüklenmediğinde zorunlu

Dosyanın doğrudan indirilebileceği herkese açık http veya https URL'si.

filefileisteğe bağlı

URL vermek yerine görseli veya dosyayı yükleyin. İsteği multipart/form-data olarak, alan adı file olacak şekilde gönderin.

file_namestringisteğe bağlı

Alıcının gördüğü dosya adı, örneğin invoice-4821.pdf. Dosyanın nasıl gönderileceğini uzantısı belirler, bu yüzden bir uzantı ekleyin. Küçük harflerle gönderilir, & : ? * $ ; gibi karakterler _ ile değiştirilir ve 150 karaktere kısaltılır. Göndermezseniz ad URL'den veya yüklenen dosyadan alınır.

Teslimat seçenekleri

expire_after_secondsintegeristeğe bağlı

Mesaj bu kadar saniye içinde gönderilmediyse süresi dolmuş (durum 4) olarak işaretlenir; örneğin bir saat için 3600. Teslimat tahmini gibi zamana duyarlı mesajlar için kullanışlıdır. Bunu bir arka plan işi süre dolduktan en az 30 saniye sonra yapar; bu yüzden bir dakikadan kısa süreler için buna güvenmeyin.

webhookstringisteğe bağlı

Mesaj gönderildiğinde, başarısız olduğunda, iptal edildiğinde veya süresi dolduğunda bir POST alan URL. Bkz. Webhook.

idempotency_keystringisteğe bağlı

İsteğe bağlı, en fazla 255 karakter. 24 saat boyunca aynı değerle yeniden denediğinizde ikinci bir mesaj yerine ilk yanıtı alırsınız. Bunun yerine Idempotency-Key başlığı olarak da gönderebilirsiniz. Bkz. Güvenle yeniden deneme.

Güvenle yeniden deneme#

Zaman aşımı veya kopan bir bağlantıdan sonra isteğinizin ulaşıp ulaşmadığını bilemezsiniz ve yeniden göndermek müşteriye iki kez mesaj gitmesine yol açabilir. Güvenle yeniden denemek için, bu mesaja özgü kendi değerinizle, örneğin sipariş kimliğiniz veya bir UUID ile, bir idempotency_key alanı ya da Idempotency-Key başlığı gönderin ve yeniden denerken aynı değeri ve aynı isteği kullanın.

Mesaj gönderme, Gruba gönderme, Birden fazla numaraya gönderme ve Mesaj zamanlama için geçerlidir. Her API anahtarının kendi değerleri vardır ve 24 saat saklanır. Değer olmadan veya boş bir değerle her istek her zamanki gibi gönderilir.

Ne olurYanıt
Bu değerle yapılan ilk istekNormal yanıt.
Başarılı olduktan sonra yeniden denemeIdempotent-Replayed: true başlığıyla yine ilk yanıt. Yeni mesaj yok.
Reddedildikten sonra yeniden deneme (status 0)Yeniden çalışır: reddedilen istekler hatırlanmaz, bu yüzden isteği düzeltip aynı değerle yeniden deneyebilirsiniz.
İlk istek hâlâ çalışırken yeniden denemeHTTP 409, code idempotency_in_progress, Retry-After: 1 ile.
Farklı bir istekle aynı değerHTTP 409, code idempotency_key_reused.
255 karakterden uzun veya satır sonu içeren bir değerHTTP 400, code invalid_idempotency_key.

Idempotency anahtarı yalnızca aynı isteğin ikinci bir mesaj oluşturmasını engeller. Mesajın WhatsApp'a ulaşıp ulaşmadığını söylemez: bunun için bir webhook veya Mesaj durumu kullanın.

Görsel ve dosya gönderme#

img_url ve file_url için indirme sınırları:

  • URL herkese açık olmalıdır: http veya https, internetten erişilebilir. En fazla 5 yönlendirme izlenir ve her biri de herkese açık bir adrese gitmelidir.
  • Bağlantılı dosyalar en fazla 100 MB olabilir. Sunucu 45 saniye içinde yanıt vermeye başlamalı ve bundan uzun süre takılmamalıdır.
  • Dosya API'yi çağırdığınızda indirilir, bu yüzden bozuk bir bağlantı Invalid file url hatasıyla hemen başarısız olur.

msg_type 2 ile gönderilen dosyalar şu uzantıları korur:

KategoriUzantılar
Görseller.jpg, .jpeg, .jpe, .png, .gif, .webp, .bmp
Belgeler.pdf, .doc, .docx, .docm, .xls, .xlsx, .xlsm, .xlsb, .ppt, .pptx, .pptm, .txt, .csv
Ses.mp3, .mpga, .m4a, .aac, .wav, .ogg, .oga
Video.mp4, .mov, .avi, .webm
Arşivler.zip, .rar

Bu kontroller API'yi çağırdığınızda değil, mesaj gönderilirken yapılır; bu yüzden hatalar yalnızca Mesaj durumu ve webhook üzerinden görünür:

SorunMesaj durumundaki error
16 MB'tan büyük bir görsel (msg_type 1)File exceeds WhatsApp size limit (16MB max)
64 MB'tan büyük bir video (.mp4, .webm), görsel olarak (msg_type 1) gönderilse bileFile exceeds WhatsApp size limit (64MB max)
100 MB'tan büyük diğer her dosya (msg_type 2)File exceeds WhatsApp size limit (100MB max)
Boş bir dosya (0 bayt)The file is empty
Görsel olarak (msg_type 1) gönderilen bir .wav veya .ogg dosyasıFile type not supported

WAV ve OGG ses dosyaları görsel olarak (msg_type 1) gönderilemez. Dosya olarak (msg_type 2) gönderildiklerinde, recording.wav gibi kendi adlarıyla belge olarak ulaşırlar. .mp3, .mpga, .m4a ve .aac dosyaları sohbette çalan ses olarak ulaşır ve msg ayrı bir metin mesajı olarak ardından gelir (seste açıklama yoktur).

URL'den görsel
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 🎉"
  }'
Dosya yükleme
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

Resmi istemcileri kullanma#

Python ve Node.js istemcileri bu endpoint'i sizin için çağırır.

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)

Hatalar requests.HTTPError fırlatır. Nedeni e.response.json()["message"] ile okuyun.

Yanıt#

Başarılı bir istek HTTP 200 döndürür:

{
  "status": 1,
  "message": "Created",
  "msg_id": 9817263
}
AlanTürAçıklama
statusintegerMesaj kuyruğa alındıysa 1, istek başarısız olduysa 0.
messagestringBaşarıda Created, aksi halde hata mesajı.
msg_idintegerKuyruğa alınan mesajın ID'si. Durumu daha sonra kontrol etmek için kaydedin. Yalnızca başarıda bulunur.

"status": 1, mesajın alıcıya ulaştığı değil, kuyruğa alındığı anlamına gelir. Gönderildiğini doğrulamak için bir webhook veya Mesaj durumu kullanın.

Hatalar#

Hatalar, status değeri 0 olarak HTTP 400 döndürür (Account Disabled yanıtında status alanı yoktur):

{ "status": 0, "message": "Msg cant be null" }
MesajNasıl düzeltilir
Auth Error - Please send correct API key and Client idBoş olmayan bir api_key gönderin.
Invalid client id.client_id değerini sayı olarak gönderin.
Auth Error: invalid api keyAnahtarın mevcut olduğunu, silinmediğini ve bu client_id değerine ait olduğunu kontrol edin.
Either phone or group_name parameter is requiredphone ekleyin.
Please provide either phone OR group_name, not bothBirini kaldırın.
Invalid phone numberphone 6–17 rakamlı bir numara olmalıdır. Harflere ve diğer simgelere izin verilmez; 9.19877E+11 gibi yuvarlanmış bir tablo değerine de izin verilmez.
Invalid Contact Number "…"Ülke kodu eklendikten sonra numara 7–15 haneli olmalıdır.
Msg cant be nullMetin mesajları (msg_type 0) msg gerektirir.
Message length is too longmsg değerini 3.000 karakter veya daha kısa tutun.
Image Url Can't be nullmsg_type 1 için img_url gönderin veya bir file yükleyin.
File Url Can't be nullmsg_type 2 için file_url gönderin veya bir file yükleyin.
Invalid file url, Can't download / Invalid file urlURL herkese açık değil, zaman aşımına uğradı veya dosya 100 MB'tan büyük.
Invalid whatsapp clientBu whatsapp_client ID'si çalışma alanınızda değil.
Invalid whatsapp client id.whatsapp_client gönderin. Çalışma alanınızda birden fazla bağlı numara varsa zorunludur.
Telegram usernames can only be sent to from a Telegram account: pass its id as whatsapp_clientphone içindeki bir @username, t.me bağlantısı veya tg:<id> için whatsapp_client olarak bir Telegram hesabı gerekir.
Not enough creditsÇalışma alanı ücretsiz planda ve mesajı kalmadı: ücretli planlar sınırsız mesaj gönderir. Bkz. Mesajlarınız bittiğinde.
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")Bu numara son 24 saatte 1.000 mesaj aldı (adil kullanım). Yanıtta reddedilen mesajın msg_id değeri yine bulunur; bu mesaj başarısız görünür. Kalanını daha sonra veya başka bir numaradan gönderin.
Demo Account can not access apisNormal bir hesap kullanın.
Account DisabledHesabınız devre dışı. Destekle iletişime geçin.
Invalid JSON format: …JSON gövdesi geçerli değil; genellikle sondaki bir virgül veya msg içindeki kaçışsız bir satır sonu nedeniyle. Yeni satırlar için \n kullanın.

Kuyruğa alınmış bir mesaj gönderilirken yine de başarısız olabilir; örneğin File exceeds WhatsApp size limit (…) ile. Bu hatalar bu yanıtta hiçbir zaman görünmez. Görsel ve dosya gönderme bölümüne bakın ve Mesaj durumu ile kontrol edin.

Webhook#

webhook iletirseniz, WbizTool mesaj gönderildiğinde veya başarısız olduğunda, ayrıca gönderilmeden önce iptal edildiğinde veya süresi dolduğunda bu URL'ye bir POST gönderir. Gövde JSON değil, form kodludur (application/x-www-form-urlencoded):

msg_id=9817263&status=SENT
AlanDeğerler
msg_idMesajı gönderdiğinizde dönen msg_id.
statusSENT, FAILED, CANCELLED (gönderilmeden önce iptal edildi: Mesaj iptal etme ile, panelden veya WhatsApp numarası ya da kampanyası kaldırıldığı için) veya EXPIRED (expire_after_seconds süresi dolmadan gönderilemedi veya gönderim zamanından 48 saat sonra hâlâ bağlantısı kesik bir numarada bekliyordu)

Her webhook imzalıdır: WbizTool-Timestamp ve WbizTool-Signature başlıkları (v1= ve çalışma alanınızın imzalama gizli anahtarıyla <timestamp>.<raw body> üzerinden hesaplanan HMAC-SHA256) webhook'un WbizTool'dan geldiğini doğrulamanızı sağlar. Gizli anahtarı ve Python ile Node.js doğrulama örneklerini Webhook imzaları bölümünde bulabilirsiniz; başlıkları yok sayan alıcılar çalışmaya devam eder.

Herhangi bir 2xx koduyla yanıt verin; yönlendirme en fazla 3 kez izlenir. Endpoint'iniz 10 saniye içinde yanıt vermezse, ulaşılamazsa veya 429 ya da 5xx döndürürse, WbizTool 30 saniye, 1 dakika ve 2 dakika sonra yeniden dener (toplam 4 deneme). Diğer 4xx yanıtları yeniden denenmez. URL herkese açık bir internet adresi olmalıdır: özel veya yerel bir adrese (örneğin 192.168.x.x veya localhost) webhook gönderilmez.

İpuçları#

  • Telefon numaraları: belirsizliği önlemek için numaraları uluslararası biçimde saklayın ve country_code ile gönderin.
  • JSON'da yeni satırlar: bunları msg içinde \n olarak yazın. Ham bir satır sonu JSON'u geçersiz kılar.
  • Numaranızı bağlı tutun: mesajlar WhatsApp numaranızdan gönderilir, bu yüzden numaranın WhatsApp ayarları sayfasında bağlı kalması gerekir.
  • Çok sayıda alıcı: aynı mesajı tek bir istekte birkaç numaraya göndermek için Birden fazla numaraya gönderme endpoint'ini kullanın. Büyük kampanyalar için bunun yerine Kampanyalar sayfasından bir tablo dosyası yükleyin.