Bildirim gönderme

Tek seferlik (transactional ya da toplu) mesajlar POST /v1/notifications ile oluşturulur. Yanıt 202 ve { id, status, recipients_estimate, external_id_missing } döner; teslimat asenkrondur, sonuçlar sayaçlara, Mesaj İzleme ekranına ve webhook'lara düşer. Tüm alanlar ve 8 dilde örnek: API → Bildirimler. Tekrarlı/zamanlanmış toplu gönderimler için kampanyalar.

POST /v1/notifications
{
  "app_id": "app_…",
  "idempotency_key": "order-1001",
  "target": { "include_external_ids": ["user_42"], "channels": ["ios_push", "android_push", "web_push"] },
  "headings": { "tr": "Siparişiniz yola çıktı", "en": "Your order has shipped" },
  "contents": { "tr": "Takip bağlantısı içeride", "en": "Tracking link inside" },
  "url": "https://example.com/orders/1001",
  "data": { "order_id": "1001" },
  "send_after": "2026-10-18T09:00:00Z",
  "delayed_option": "timezone",
  "delivery_time_of_day": "09:00"
}

Hedefleme (target)Bağlantıyı kopyala

Gönderim yapmadan alıcı sayısı: POST /v1/notifications/estimate { target, include_unsubscribed? }. Hedef boşsa 422 HS_NO_RECIPIENTS, kanal yapılandırılmamışsa 422 HS_CHANNEL_NOT_CONFIGURED.

İçerikBağlantıyı kopyala

• Çok dilli metin: headings, contents, subtitle dil haritasıdır ({ "tr": …, "en": … }); alıcının dili yoksa en, o da yoksa ilk dil.
• Liquid: tüm metin alanları kişiselleştirilir: {{ user.tags.name }}, {{ user.properties.city }}, {{ subscription.language }}, {{ event.properties.* }} (journey'de), Data Feeds ve Content Tables değişkenleri. Sandbox'lı Liquid; dosya/ağ erişimi yok.
• Şablon: template_id ile sürümlü şablon kullanılır; gövdedeki alanlar şablonu ezer.
• Tıklama: url (web/tarayıcı), app_url (deeplink), buttons / web_buttons (aksiyon düğmeleri), data (özel yük).
• Kanal alanları: iOS (ios_sound, ios_badge_type, ios_interruption_level, ios_attachments, thread_id…), Android (android_channel_id, small_icon, big_picture…), Web (chrome_web_icon, chrome_web_image, require_interaction…), e-posta (email_subject, email_mjml/email_body, email_preheader…), SMS (sms_from, sms_media_urls), WhatsApp (whatsapp_template, whatsapp_media, whatsapp_interactive), RCS (rcs_card, rcs_suggestions, rcs_fallback_text). Ayrıntı: ilgili kanal sayfaları.
• Bildirim kutusu: add_to_inbox, inbox_ttl (inbox).
• Meta: name (dashboard'da görünen ad), labels (filtreleme), category (tercih kategorisi).

İçerik kuralları (uzunluk, URL şeması, Liquid sözdizimi, 4 KB push yükü) ihlalinde 422 HS_CONTENT_INVALID.

ZamanlamaBağlantıyı kopyala

Zamanlanmış/kuyruktaki mesaj DELETE /v1/notifications/{id} ile iptal edilir; gönderimi başlamış mesaj iptal edilemez.

Teslimat politikalarıBağlantıyı kopyala

App ayarlarında (Ayarlar → Teslimat politikaları) tanımlanan kurallar her gönderime uygulanır:

• Frekans sınırı: kullanıcı başına pencere(ler) (ör. günde 3, haftada 10); frequency_cap_exempt: true işlemsel mesajı muaf tutar.
• Sessiz saat: alıcının yerel saatinde tanımlı aralıkta push gönderilmez, pencere sonuna ertelenir; quiet_hours_exempt: true muaf tutar.
• Tek kullanıcı başına bir: one_per_user: true ile aynı kullanıcının birden çok cihazına yalnızca bir teslimat.
• Hız sınırı: throttle_rate_per_minute ile dakikada en fazla N teslimat (sağlayıcı/kendi arka ucunuzu korumak için).
• Kategori/tercih: category verilen mesaj, kullanıcının o kategori/kanal tercihine göre bastırılır.
• Suppression list, abonelik durumu, kanal durumu her zaman uygulanır.

Bastırılan teslimatlar suppressed durumunda suppression_reason ile kaydedilir ve counts.suppressed sayacında görünür: frequency_cap, category_opt_out (tercih), suppression_list, no_opt_in, channel_inactive, invalid_address, whatsapp_window_closed (24 saatlik pencere), holdout (A/B kontrol grubu).

IdempotencyBağlantıyı kopyala

Idempotency-Key başlığı ya da gövdede idempotency_key: aynı anahtar + aynı gövde 24 saat boyunca aynı yanıtı döner; farklı gövde 409 HS_IDEMPOTENCY_CONFLICT, sürmekte olan istek 409 HS_IDEMPOTENCY_IN_PROGRESS. Sunucu SDK'ları anahtar verilmezse otomatik UUID üretir ve yeniden denemelerde aynı anahtarı kullanır. Ayrıntı: idempotency.

Durum ve teslimatlarBağlantıyı kopyala

• GET /v1/notifications/{id} → status (queued, processing, completed, cancelled, failed) ve counts (targeted, suppressed, sent, delivered, failed, errored, expired, opened, clicked, converted, bounced, complained, unsubscribed, sms_segments).
• GET /v1/notifications/{id}/deliveries?status=&cursor= → abonelik bazlı teslimatlar (queued → sent → delivered/received → opened/clicked, failed + error_code).
• GET /v1/notifications/{id}/history → teslimat CSV işi; POST …/export_events → olay CSV işi (download_url tamamlanınca).
• GET /v1/notifications?app_id=&source=&status=&label=&cursor= → mesaj listesi (source: api, campaign, journey, test).

Teslimat zaman çizelgesi ve sağlayıcı yanıtları dashboard Mesaj İzleme'de; teslimat geçici hataları 30 sn / 2 dk / 10 dk / 30 dk / 2 sa planıyla yeniden denenir, geçersiz token aboneliği invalid yapar.