Hızlı Başlangıç | WA2Notify Docs

WA2Notify public müşteri API’sini üretime almak için önerilen akış aşağıdaki sırayı izler:

1Panelde API key üret

Mesaj, kampanya, kişi listesi, şablon ve webhook izinlerini seç. Public entegrasyon burada başlar.

2Dashboard’dan device_id al

WhatsApp cihazını panelden bağla; public API cihaz eşleme yapmaz.

3Veriyi içeri al

Gerekirse önce medya yükle, CSV/XLSX kişi listesi import et veya şablon oluştur.

4Mesajı gönder, webhook ile izle

Tekli mesaj veya kampanya çağrısını başlat; teslim, okundu ve hata message.* olaylarını webhook ile yakala.

Önerilen başlangıç akışı

Eğer ilk gün içinde canlıya çıkmak istiyorsanız sırayı değiştirmeyin: önce device_id, sonra message-assets, sonra kişi listesi import’u ve en son gönderim.

POST/v1/message-assets

X-API-Key200 OK

Güvenli dosya yükle

Medya, PDF veya ofis belgesini tenant-owned asset olarak yükler ve mesajlarda kullanacağınız `asset_id` döner.

Form alanıfile zorunludur. Dosya içeriği MIME sniffing ve uzantı kontrolünden geçer.

Sonraki kullanımDönen id değerini mesaj veya kampanya isteklerinde asset_id alanına koyarsınız.

Free plan dosya göndermez. Pro görsel ve belge, Growth buna ek olarak video desteği sunar.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/message-assets \
--header "X-API-Key: {{API_KEY}}" \
--form "[email protected]"

Yanıt

JSON

{
"data": {
  "id": "b84b4f8d-2fd8-4c6d-b90a-fc5dd7f4aef2",
  "original_name": "kampanya.pdf",
  "mime_type": "application/pdf",
  "size_bytes": 184320,
  "kind": "document",
  "created_at": "2026-04-01T09:15:00Z"
}
}

POST/v1/contact-lists/import

X-API-Key200 OK

CSV veya XLSX kişi listesi içe aktar

CSV veya XLSX dosyasını backend hattında parse eder, telefonları normalize eder ve listeyi doğrudan oluşturur.

Telefon kolonu otomatik tespit edilir ve uluslararası formata normalize edilir.
Boş satırlar, mükerrer kayıtlar ve geçersiz numaralar sessizce elenir.
Formül içerikleri string olarak alınır ve nötralize edilir.

Yalnızca `csv` ve `xlsx` desteklenir. `xls`, `xlsm` ve makrolu legacy formatlar reddedilir.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/contact-lists/import \
--header "X-API-Key: {{API_KEY}}" \
--form "name=Ankara Musterileri" \
--form "description=Nisan bulteni alicilari" \
--form "[email protected]"

Yanıt

JSON

{
"data": {
  "id": "6876b126-8e88-4937-9bbf-0f14a368d65f",
  "name": "Ankara Musterileri",
  "source": "excel",
  "total_contacts": 248,
  "variable_fields": ["ad", "sehir", "segment"],
  "created_at": "2026-04-01T09:17:12Z"
}
}

POST/v1/messages/send

X-API-Key200 OK

İlk mesajı gönder

Tekli veya çoklu alıcıya anlık mesaj gönderir. Aynı çağrıda `template_id`, `variables` ve `asset_id` birlikte kullanılabilir.

Zorunlu alanlardevice_id ve en az bir alıcı içeren to dizisi zorunludur.

Opsiyonel alanlartext, template_id, variables ve asset_id birlikte ya da ayrı kullanılabilir.

Mesaj kotası alıcı sayısı üzerinden işler. `to` dizisindeki her numara plan kotasından ayrı düşer.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/messages/send \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
  "device_id": "{{DEVICE_ID}}",
  "to": ["+905551112233"],
  "text": "Merhaba {{ad}}, siparişiniz hazır.",
  "asset_id": "{{ASSET_ID}}",
  "variables": {
    "ad": "Ayşe"
  }
}'

Yanıt

JSON

{
"data": {
  "messages": [
    {
      "id": "7ac71306-3a37-4c45-a178-81dfbbca8728",
      "to": "+905551112233",
      "status": "sent",
      "created_at": "2026-04-01T09:18:30Z"
    }
  ],
  "total_count": 1,
  "success_count": 1,
  "failed_count": 0
}
}

POST/v1/webhooks

X-API-Key200 OK

Webhook kaydı oluştur

Teslim, okundu ve hata gibi `message.*` olaylarını kendi sisteminize taşıyacak outbound webhook kaydını oluşturur. Kampanya ilerleyişini `batch_id` ile bu olaylardan izleyebilirsiniz.

HTTPS şiddetle önerilir: payload mesaj içeriği ve telefon numarası taşır.
Yanıttaki secret yalnızca bir kez döner; gelen isteklerin X-WA2Notify-Signature başlığını doğrulamak için saklayın.
Başarısız teslimatlar otomatik retry alır ve failure_count ile izlenir.

Webhook teslimatları kullanıcı scope’unda tutulur. Aynı event farklı hedef URL’lere ayrı ayrı yönlendirilebilir. Geçerli event listesi için Webhooklar sayfasına bakın.

İstek

curl --request POST \
--url {{BASE_URL}}/v1/webhooks \
--header "X-API-Key: {{API_KEY}}" \
--header "Content-Type: application/json" \
--data '{
  "url": "https://erp.ornek.com/hooks/wa2notify",
  "events": ["message.delivered", "message.read", "message.failed"]
}'

Yanıt

JSON

{
"data": {
  "id": "8ebbc8af-0ef1-4ea7-bb5b-c4aa8fa3f946",
  "url": "https://erp.ornek.com/hooks/wa2notify",
  "events": ["message.delivered", "message.read", "message.failed"],
  "secret": "8f2c1e6a-4b7d-4b1a-9c2e-3f5a7d9b0c11",
  "is_active": true,
  "failure_count": 0
}
}

Sonraki adımlar

Yetki modeli için API Key Kullanımı
Kampanya akışları için Kampanyalar
Liste import detayları için Kişi Listeleri
Hazır istek koleksiyonu için Postman