İşlemsel mesajlar ve kademeli gönderimler

İşlemsel mesajlar; sipariş onayları, giriş kodları ve teslimat bildirimleridir. Müşteri bunları beklediği için hemen ve ayrı bir kuyruk üzerinden gönderilirler: büyük bir kampanya onları geciktirmez. Kademeli gönderim tek bir mesajı birkaç kanal üzerinden sırayla gönderir. Örneğin önce WhatsApp, 2 dakika içinde teslim edilmezse SMS.

Böyle bir mesajı bir yolculuktan veya kendi sunucunuzdan API üzerinden gönderebilirsiniz.

İşlemsel şablon

Bir mesajın işlemsel sayılması için şablonunda İşlemsel mesaj seçeneğini işaretleyin. Böyle bir mesaj abonelik, sıklık sınırları ve sessiz saatler kontrol edilmeden gönderilir. OneTrace.ru posta hizmeti üzerinden giden e-postalar ısınma olmadan ve ayrı bir akışla, başlıklarda abonelikten çıkma bağlantısı olmadan gönderilir.

Reklamları bu şekilde işaretlemeyin: bu, alıcıların haklarını ihlal eder ve göndericinin itibarını zedeler.

İşlemsel mesaj bile, kanal alıcı için kapalıysa gönderilmez:

Böyle bir mesaj “kanal alıcı için engelli” nedeniyle “Atlandı” durumunu alır. Müşteri yeniden abone olduğunda kanal tekrar açılır, örneğin botta “Start” düğmesine bastığında. Spam şikâyeti kanalı kapatmaz: siparişlerle ilgili e-postalar bu adrese gelmeye devam eder.

API üzerinden gönderim

Sunucunuz mesajı POST /api/v1/messages isteğiyle gönderir. “Tekil mesaj gönderme” yetkisine sahip bir gizli anahtar gerekir, bkz. API anahtarları.

curl -X POST https://cdp.onetrace.ru/api/v1/messages \
  -H "Authorization: Bearer $CDP_SECRET_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-A-1001" \
  -d '{
    "identity": {"type": "email", "value": "anna@example.com"},
    "template_id": 12,
    "traits": {"first_name": "Ayşe"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

202 yanıtı mesajın id değerini ve durumunu içerir. Güncel durumu GET /api/v1/messages/{id} döndürür: queued, sent, delivered, failed, skipped ve diğerleri, atlama veya hata nedeniyle birlikte.

• Yineleme güvenlidir. Aynı Idempotency-Key başlığına sahip istek, önceden oluşturulmuş mesajı döndürür; ikinci mesaj gönderilmez. Sipariş numarasını veya işlem kimliğini kullanın.
• Alıcı başına sınır: API üzerinden saatte 20 mesaj. Aşıldığında Retry-After başlığıyla 429 yanıtı gelir.
• “İşlemsel” işareti olmayan normal bir şablon da API üzerinden gönderilebilir. Bu durumda tüm gönderim kuralları kontrol edilir.

Hazır PHP kütüphanesinde bu $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), Laravel paketinde ise messages()->send(...) çağrısıdır.

Yolculukta kademeli gönderim

Yolculuğa “İşlemler” grubundan Kademeli gönderim düğümünü ekleyin. Sırayla kanallar alanında 2 ile 5 arasında adım belirleyin. Her adım için şunları belirtin:

• Kanalın Entegrasyon ve Şablon alanları.
• Bekle: neyin başarı sayılacağı; “gönderildi”, “teslim edildi” veya “okundu”.
• Bekleme süresi: “teslim edildi” ve “okundu” için, varsayılan olarak 15 dakika.

Kademeli gönderim şu durumlarda sonraki adıma geçer:

• profilin kanal için adresi veya numarası yoksa ya da kanal onun için kapalıysa; adım hemen atlanır, mesaj oluşturulmaz;
• mesaj gönderilemediyse: gönderim hatası veya gönderim kuralları nedeniyle atlama;
• sağlayıcı mesajın teslim edilmediğini bildirdiyse;
• bekleme süresi içinde teslim veya okunma onayı gelmediyse.

Teslimi ve okunmayı her kanalda beklemek mümkün değildir:

Düğümün iki çıkışı vardır: ulaştı: adımlardan birinin mesajı hedefe ulaştı; hata: hiçbir kanal işe yaramadı. Kademeli gönderim sürerken katılımcı düğümde bekler.

Kademeli gönderim aynı mesajı iletir. “Sepet: push → e-posta → SMS” gibi yolculuk şablonları farklı çalışır: orada müşteri sipariş verene kadar farklı mesajlar aralıklarla gönderilir.

API üzerinden kademeli gönderim

template_id yerine steps gönderin; yolculuk düğümündekiyle aynı adımlar:

{
  "identity": {"type": "phone", "value": "+79991234567"},
  "steps": [
    {"integration_id": 3, "template_id": 21, "wait_for": "delivered", "timeout": {"amount": 2, "unit": "minute"}},
    {"integration_id": 4, "template_id": 22, "wait_for": "sent"}
  ],
  "data": {"code": "482913"}
}

wait_for değeri sent, delivered veya opened olabilir; timeout birimleri minute, hour, day, week. 202 yanıtı kademeli gönderimin id değerini içerir, GET /api/v1/messages/cascades/{id} ise durumunu döndürür:

• status: running, reached veya failed;
• geçerli adım step;
• işe yarayan kanal: reached_channel;
• adımların mesajları messages.

Tarife

İşlemsel mesajlar ve API üzerinden gönderim tüm tarifelerde kullanılabilir. Kademeli gönderim “Büyüme” tarifesinden itibaren kullanılabilir, bkz. Tarife ve ödeme. “Başlangıç” tarifesinde düğüm, düzenleyici paletinde kilitle işaretlidir ve API 402 ile yanıt verir. Tarife düşürülürse, zaten çalışan yolculuklarda kademeli gönderimin yalnızca ilk adımı gönderilir.