Tranzaksion xabarlar va kaskadlar

Tranzaksion xabarlar — buyurtma tasdiqlari, kirish kodlari, yetkazib berish haqidagi bildirishnomalar. Xaridor ularni kutadi, shuning uchun ular darhol va alohida navbat orqali yuboriladi: katta kampaniya ularni ushlab qolmaydi. Kaskad bitta xabarni bir nechta kanal orqali navbat bilan yuboradi. Masalan, avval WhatsApp, agar 2 daqiqada yetkazilmasa — SMS.

Bunday xabarni zanjirdan yoki oʻz serveringizdan API orqali yuborish mumkin.

Tranzaksion shablon

Xabar tranzaksion hisoblanishi uchun uning shablonida Tranzaksion xabar belgisini qoʻying. Bunday xabar obuna, chastota cheklovlari va sokin soatlar tekshiruvisiz yuboriladi. OneTrace.ru pochta xizmati orqali xatlar qizdirishsiz va alohida oqim bilan, sarlavhalarda obunani bekor qilish havolasisiz yuboriladi.

Reklamani bunday belgilamang: bu qabul qiluvchilarning huquqlarini buzadi va yuboruvchi obroʻsiga putur yetkazadi.

Hatto tranzaksion xabar ham qabul qiluvchida kanal yopiq boʻlsa yuborilmaydi:

Bunday xabar «kanal qabul qiluvchi uchun bloklangan» sababi bilan «Oʻtkazib yuborildi» holatini oladi. Xaridor qaytadan obuna boʻlganda — masalan, botda «Start» ni bosganda — kanal yana ochiladi. Spam haqidagi shikoyat kanalni yopmaydi: bu manzilga buyurtmalar haqidagi xatlar kelishda davom etadi.

API orqali yuborish

Serveringiz xabarni POST /api/v1/messages soʻrovi bilan yuboradi. «Alohida xabarlar yuborish» ruxsatli maxfiy kalit kerak, qarang: API kalitlari.

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": "Anna"},
    "data": {"order_id": "A-1001", "amount": 4990}
  }'

202 javobida xabarning id si va holati boʻladi. Joriy holatni GET /api/v1/messages/{id} qaytaradi: queued, sent, delivered, failed, skipped va boshqalar, oʻtkazib yuborish yoki xato sababi bilan.

• Takrorlash xavfsiz. Xuddi shu Idempotency-Key sarlavhali soʻrov allaqachon yaratilgan xabarni qaytaradi, ikkinchisi yuborilmaydi. Buyurtma raqami yoki operatsiya id sidan foydalaning.
• Qabul qiluvchiga limit — API orqali soatiga 20 ta xabar. Oshib ketganda Retry-After sarlavhali 429 keladi.
• Oddiy shablonni «Tranzaksion» belgisisiz ham API orqali yuborish mumkin. Bunda xabar yuborishning barcha qoidalari tekshiriladi.

Tayyor PHP kutubxonasida bu $onetrace->messages()->send(Identity::email('anna@example.com'), 12, ['data' => [...]], 'order-A-1001'), Laravel paketida esa — messages()->send(...).

Zanjirdagi kaskad

Zanjirga «Amallar» guruhidan Kaskadli yuborish tugunini qoʻshing. Kanallar navbat bilan maydonida 2 tadan 5 tagacha qadam belgilang. Har bir qadam uchun koʻrsating:

• Kanal uchun Integratsiya va Shablon.
• Kutish — nima muvaffaqiyat hisoblanadi: «yuborildi», «yetkazildi» yoki «oʻqildi».
• Kutish vaqti — «yetkazildi» va «oʻqildi» uchun, standart boʻyicha 15 daqiqa.

Kaskad keyingi qadamga oʻtadi, agar:

• profilda kanal uchun manzil yoki raqam boʻlmasa yoki kanal unda yopiq boʻlsa — qadam darhol oʻtkazib yuboriladi, xabar yaratilmaydi;
• xabar ketmagan boʻlsa: yuborish xatosi yoki xabar yuborish qoidalari boʻyicha oʻtkazib yuborilgan;
• provayder yetkazilmaganini xabar qilgan boʻlsa;
• kutish vaqti ichida yetkazilganlik yoki oʻqilganlik tasdigʻi kelmagan boʻlsa.

Yetkazilishi va oʻqilishini hamma kanallarda ham kutib boʻlmaydi:

Tugunning ikkita chiqishi bor: yetib bordi — qadamlardan birining xabari maqsadga erishdi; xato — birorta ham kanal ishlamadi. Kaskad davom etayotganda ishtirokchi tugunda kutadi.

Kaskadli yuborish bitta va oʻsha xabarni yetkazadi. «Savatcha: push → email → SMS» kabi zanjir shablonlari boshqacha tuzilgan: ularda xaridor buyurtma bermaguncha turli xabarlar pauzalar bilan yuboriladi.

API orqali kaskad

template_id oʻrniga steps ni yuboring — zanjir tugunidagi oʻsha qadamlar:

{
  "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 sent, delivered yoki opened qiymatlarini qabul qiladi, timeout birliklari — minute, hour, day, week. 202 javobida kaskadning id si boʻladi, GET /api/v1/messages/cascades/{id} uning holatini qaytaradi:

• status — running, reached yoki failed;
• joriy qadam step;
• ishlagan kanal — reached_channel;
• qadamlar xabarlari messages.

Tarif

Tranzaksion xabarlar va API orqali yuborish barcha tariflarda mavjud. Kaskad — «Oʻsish» tarifidan boshlab, qarang: Tarif va toʻlov. «Start» tarifida tugun muharrir palitrasida qulf bilan belgilangan, API esa 402 bilan javob beradi. Agar tarif pasaytirilsa, allaqachon ishlayotgan zanjirlarda kaskadning faqat birinchi qadami yuboriladi.