WhatsApp API Entegrasyonu: API ile Mesaj Gönderme

Başlamadan: entegrasyonun ön koşulları

WhatsApp entegrasyonu, herkese açık bir API'ye kayıt olmakla değil, doğrulanmış bir WhatsApp Business API hesabıyla başlar. Meta işletme doğrulaması ve numara bağlama tamamlandığında API anahtarınız (X-Api-Key) VatanSMS tarafından teslim edilir — anahtarın neden satın alınamadığını API key rehberinde anlattık. Hesabınız yoksa WhatsApp Business API nasıl alınır rehberiyle başlayın; kurulum sürecini Türkiye'den Meta teknik partneri olarak VatanSMS yürütür.

Temel kavram: oturum mesajı ve şablon

Pazarlama içerikli şablon gönderimlerinde alıcının opt-in vermiş olması gerekir — ayrıntılar reklam mesajı rehberinde.

Uç nokta listesi

1. Metin mesajı gönderme

WhatsApp API ile mesaj göndermenin en basit hâli: aktif oturuma düz metin. business_device_id (cihaz ID'si, int) veya phone_number_id (string) alanlarından biri zorunludur; ikisi birden gönderilirse business_device_id esas alınır.

POST https://api.toplusms.app/api/v1/wabusiness/message/send
X-Api-Key: <API-KEY>
Content-Type: application/json

{
    "business_device_id": 123,
    "to": "905XXXXXXXXX",
    "message_type": 1,
    "payload": {
        "text_message": { "message": "Merhaba!" }
    }
}

curl ile aynı istek:

curl -X POST "https://api.toplusms.app/api/v1/wabusiness/message/send" \
  -H "X-Api-Key: <API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{"business_device_id":123,"to":"905XXXXXXXXX","message_type":1,"payload":{"text_message":{"message":"Merhaba!"}}}'

2. Medya gönderme (görsel, video, belge)

Aynı message/send uç noktası, multipart/form-data ile medya taşır: params alanına JSON metni, medya alanına dosya eklenir. Seçtiğiniz message_type ile doldurduğunuz dosya alanı eşleşmelidir.

curl -X POST "https://api.toplusms.app/api/v1/wabusiness/message/send" \
  -H "X-Api-Key: <API-KEY>" \
  -F 'params={"business_device_id":123,"to":"905XXXXXXXXX","message_type":2,"payload":{}}' \
  -F "image=@/yol/urun-gorseli.jpg"

3. Şablon kampanyası gönderme

Onaylı şablonu tek alıcıya veya listeye gönderir; 24 saat penceresi gerektirmez. Bu uç noktada business_device_id, Meta'nın phone_number_id değeridir (string). Şablon değişkenleri recipients[].params.body ile doldurulur; değişken yoksa params: {} bırakılır.

POST https://api.toplusms.app/api/v1/wabusiness/template/send
X-Api-Key: <API-KEY>
Content-Type: application/json

{
    "template_id": "2xxxxxxxxxx",
    "recipients": [{
        "to": "905XXXXXXXXX",
        "params": { "body": [{ "key": "1", "value": "Vatansoft" }] }
    }],
    "campaign_name": "Test",
    "business_device_id": "123456789012345",
    "requests_per_minute": 60,
    "complete_in_seconds": 0,
    "image_url": "",
    "video_url": "",
    "document_url": ""
}

Hız kontrolü: requests_per_minute (dakika başına istek) veya complete_in_seconds (toplam tamamlanma süresi) alanlarından birini kullanın; kullanmadığınızı 0 bırakın. Başlığı medya içeren şablonlarda dosyayı multipart/form-data ile ekleyebilirsiniz; dosya eklenmezse şablonun varsayılan medyası kullanılır.

4. Şablon oluşturma

Yeni şablon POST /template ile oluşturulur ve Meta onayına gider — onaylanana kadar gönderimde kullanılamaz. Şablon adı küçük harf ve alt çizgiden oluşur (ör. kampanya_ismi); kategori MARKETING, UTILITY veya AUTHENTICATION olabilir.

{
    "business_device_id": "817271283718237812",
    "template": {
        "name": "kampanya_ismi",
        "category": "MARKETING",
        "language": "tr",
        "parameter_format": "NAMED",
        "components": [
            { "type": "HEADER", "format": "TEXT", "text": "Burası başlıktır" },
            { "type": "BODY", "text": "Mesaj almak istediğiniz için teşekkürler!" },
            { "type": "BUTTONS", "buttons": [
                { "type": "CANCEL_BUTTON", "text": "Mesaj almak istemiyorum" },
                { "type": "QUICK_REPLY", "text": "Teşekkürler!" }
            ]}
        ]
    }
}

Onay sürecinde ret yememek için şablon onay rehberindeki kurallara göz atın.

5. Kampanya listesi ve teslim raporları

Gönderdiğiniz kampanyaları GET /campaigns ile listeler, dönen campaign_id ile GET /campaigns/:id/reports üzerinden gönderim ve teslim raporunu çekersiniz. Böylece entegrasyonunuz yalnızca göndermekle kalmaz, sonucu da kendi sisteminize işler.

curl "https://api.toplusms.app/api/v1/wabusiness/campaigns/1000/reports" \
  -H "X-Api-Key: <API-KEY>"

Tipik entegrasyon senaryoları

• E-ticaret: Sipariş onayı ve kargo bildirimi şablonla; "siparişim nerede?" sorusuna oturum mesajıyla yanıt. E-ticaret çözümleri
• CRM / randevu yazılımı: Randevu oluşunca şablonla hatırlatma tetikleyin; onay yanıtını raporla eşleştirin. Hazır metinler
• Otomasyon araçları: HTTP isteği atabilen her platform (n8n, kendi cron'unuz) bu uç noktaları doğrudan çağırabilir.
• Çift kanal: WhatsApp'ı olmayan/açmayan kitleye aynı akışta SMS API ile ulaşın; iki kanal tek panelde raporlanır.