İç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 "Content-Type: application/json" \
  -d '{
    "client_id": 12345,
    "api_key": "YOUR_API_KEY",
    "whatsapp_client": 678,
    "msg_type": 0,
    "country_code": "91",
    "phone": "9876543210",
    "msg": "Hi Aman, your order #4821 has shipped and will arrive on Thursday."
  }'

12345, YOUR_API_KEY ve 678 değerlerini kendi değerlerinizle değiştirin. Bunları nerede bulacağınız için Kimlik doğrulama bölümüne bakın.

İstek parametreleri#

Kimlik doğrulama

client_idintegerzorunlu

Ayarlar → API anahtarları sayfasındaki API Client ID'niz.

api_keystringzorunlu

Aynı sayfadaki API anahtarınız.

whatsapp_clientintegerBirden fazla numaranız varsa zorunlu

Gönderimin yapılacağı WhatsApp numarasının ID'si; WhatsApp ayarları sayfasında bulunur. Bu alanı göndermezseniz ve çalışma alanınızda tam olarak bir bağlı numara varsa, o numara kullanılır.

Alıcı ve mesaj

phonestringzorunlu

Alıcının WhatsApp numarası, yalnızca rakamlar. Boşluklar, +, -, . ve parantezler sizin için kaldırılır. Numarayı ya ülke koduyla birlikte (919876543210) ya da ülke kodu olmadan (9876543210) country_code ile birlikte gönderin. Form alanlarıyla gönderirken baştaki yerel 0 önekini (09876543210) eklemeyin: country_code eklenmeden önce kaldırılmaz, bu yüzden mesaj yanlış numaraya gider. JSON isteklerinde sizin için kaldırılır.

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 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 veya başarısız olduğunda bir POST alan URL. Bkz. Webhook.

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.

Desteklenen uzantılar: .pdf, .xlsx, .xls, .txt, .docx, .png, .jpg, .jpeg, .webp, .mp3, .mpga, .m4a, .mp4, .webm.

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) veya boş bir dosyaFile exceeds WhatsApp size limit (…)
Bir .ogg dosyası veya görsel olarak (msg_type 1) gönderilen bir .wav dosyasıFile type not supported

WAV ve OGG ses dosyaları desteklenmez. Dosya olarak (msg_type 2) gönderilen bir .wav dosyası reddedilmez ama recording.wav.pdf olarak ulaşır. Sesi önce .mp3 veya .m4a biçimine dönüştürün.

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 yalnızca rakam (6–17 adet) içermeli, isteğe bağlı olarak + ile başlayabilir.
Invalid Contact Number "…"Ülke kodu eklendikten sonra numara 6–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.
Not enough creditsPlanınızda mesaj hakkı kalmadı.
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 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 veya FAILED

Herhangi bir 2xx koduyla yanıt verin. Endpoint'iniz zaman aşımına uğrarsa (3 saniye sonra) veya 5xx döndürürse, çağrı toplamda en fazla 3 kez denenir. 4xx yanıtı yeniden denenmez. Bir mesaj iptal edildiğinde veya süresi dolduğunda webhook gönderilmez; bunlar için Mesaj durumu endpoint'ini kullanın.

İ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.