Kendi Uygulamandan WhatsApp Gönderimi (HTTP API)

Panelden tek tek mesaj yazmak küçük listeler için yeterlidir; ama sipariş onayını, randevu hatırlatmasını veya form yanıtını otomatik göndermek istediğinizde insana ihtiyaç duymayan bir kanal gerekir. İşte HTTP API tam olarak bunu yapar: kendi uygulamanız sunucuya küçük bir JSON isteği atar, mesaj güvenli tempoyla WhatsApp'a çıkar. Bu yazıda bu QR tabanlı sistemin (resmi Business API değil) HTTP API entegrasyonunu — endpoint yapısı, auth secret, örnek curl/JSON payload ve kuyruk mantığı — pratik olarak anlatıyoruz.

1. Neden bir HTTP API'ye ihtiyacınız var?

Panel arayüzü elle gönderim için harikadır, ancak üç durumda tıkanır:

• Olay tetikli mesajlar: Bir sipariş oluştuğunda, form dolduğunda veya ödeme alındığında anında bildirim gitmeli. İnsanın panele girip mesaj yazmasını bekleyemezsiniz.
• Mevcut sisteme entegrasyon: E-ticaret altyapınız, CRM'iniz veya muhasebe yazılımınız zaten olayları biliyor; sadece bunları WhatsApp'a köprülemek istersiniz.
• Hacim ve tutarlılık: Yüzlerce kişisel bildirimi (herkese kendi adı, sipariş numarası) elle yazmak imkânsızdır; şablon + veri ile üretmek gerekir.

HTTP API, panelinizi bir "otomasyon uç noktasına" çevirir. Bu, WhatsApp otomatik mesaj gönderme yaklaşımının en programatik hâlidir: tetikleyici artık bir insan değil, kodunuzdur.

2. İstek nereye gidiyor? Mimari akış

Sistemin altın kuralı şudur: sunucu asla mesaj göndermez; yalnızca worker gönderir. HTTP isteğiniz bu zinciri başlatır ama gönderimi doğrudan tetiklemez:

3. Endpoint yapısı ve kimlik doğrulama

API yüzeyi bilinçli olarak sadedir. Örnek olarak tek bir gönderim uç noktası düşünün (kesin yol projenizin sürümüne göre değişebilir; buradaki şekil illüstratiftir):

Kimlik doğrulama tek bir paylaşılan gizli anahtara dayanır: WA_CONTROL_SECRET. Bu değeri kurulumda openssl rand -hex 32 ile üretir, .env dosyasına koyar ve yalnızca sunucu tarafındaki kodunuzdan gönderirsiniz. Sunucu, gelen isteğin başlığındaki secret'ı beklenen değerle karşılaştırmadan hiçbir işi kuyruğa almaz.

4. Örnek istek: curl ve JSON payload

En basit metin gönderimi bir curl ile şöyle görünür:

curl -X POST https://sunucunuz.example.com/api/messages \
  -H "Content-Type: application/json" \
  -H "X-Control-Secret: $WA_CONTROL_SECRET" \
  -d '{
    "to": "905551112233",
    "message": "Merhaba Ayşe, #1043 numaralı siparişiniz hazırlanıyor. İPTAL yazarak bildirimlerden çıkabilirsiniz.",
    "sendAt": null,
    "priority": "high"
  }'

Başarılı yanıt, gönderimin gerçekleştiğini değil, sıraya alındığını bildirir:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
  "status": "queued",
  "jobId": "wa_9f3c1a7b",
  "queuedAt": "2026-07-31T10:14:22+03:00"
}

Alanlara dair birkaç not:

• to: Numarayı ülke koduyla, baştaki + ve 0 olmadan verin (örn. 905551112233). Sistem chatId'e normalize eder; alıcının sizi rehbere kaydetmesine gerek yoktur. Ayrıntı: rehbere kaydetmeden mesaj gönderme.
• message: Düz metin; kişiselleştirmeyi (ad, sipariş no) siz payload'u üretirken doldurursunuz.
• sendAt: ISO 8601 zaman verirseniz iş BullMQ delay ile ertelenir; boş bırakırsanız en yakın uygun pencerede gönderilir. Bkz. zamanlanmış mesaj gönderme.
• priority: Aşağıda anlatılan round-robin sıralamada bu işin ağırlığını belirler.

5. Round-robin öncelik: tek gönderim, birçok kaynak

Worker aynı anda tek bir gönderici olduğu için, farklı kaynaklardan (toplu kampanya + tekil sipariş bildirimi) gelen işler aynı dar boğazı paylaşır. Sistem burada round-robin öncelik uygular: yüksek öncelikli tekil bildirimler (sipariş onayı, randevu hatırlatması), binlerce kişilik bir kampanyanın arasında sıkışıp saatlerce beklemez; kampanya işleri arasında adil biçimde araya sokulur.

6. Kullanım senaryoları

6.1 E-ticaret sipariş ve kargo sistemi

Sipariş durumu değiştiğinde (onaylandı, kargolandı, teslim edildi) arka ucunuz bir POST atar; müşteri anında bilgilenir. Bu, hizmet bildirimi kategorisine girdiği için pazarlama iznine göre daha esnektir — yine de detaylar için e-ticaret sipariş/kargo bildirimi yazısına göz atın.

6.2 Web formu ve lead bildirimi

Bir iletişim formu dolduğunda hem ekibinize hem de kullanıcıya otomatik "talebinizi aldık" mesajı gidebilir. Form arka ucunuz doğrudan endpoint'e istek atar.

6.3 CRM ve otomasyon araçları

CRM'inizdeki bir aşama değişikliği ya da n8n/Zapier gibi bir otomasyon akışı, HTTP düğümüyle bu API'yi çağırabilir. Böylece koda dokunmadan görsel akışlarla WhatsApp adımı eklersiniz.

Bu senaryoların tümünün altyapı tarafında ne anlama geldiğini self-hosted mesaj sistemi yazısında bulabilirsiniz; API'yi çevreleyen worker/kuyruk mimarisi tamamen sizin sunucunuzda çalışır.

Sık sorulan sorular