Tipi ta' messaġġi

L-API Cascade tappoġġja erba’ tipi ta’ messaġġi, kull wieħed ottimizzat għal każijiet ta’ użu u kanali differenti.

Ħarsa ġenerali

Tip	Għan	Kanali	Interattiv
”tranżazzjoni”	Notifiki kritiċi	Kollha	Le
”promo”	Kampanji ta’ kummerċjalizzazzjoni	Kollha	Iva (buttuni)
viber_survey	Polls u feedback	Viber, SMS	Iva (għażliet)
flashcall	Verifika tat-telefon	Telefonata	Le

Messaġġi ta’ Transazzjoni

Notifiki kritiċi bħal konfermi tal-ordnijiet, aġġornamenti tal-kontijiet, u twissijiet tas-sistema.

Karatteristiċi

• Twassil bi prijorità għolja
• L-ebda kontenut promozzjonali
• Dirett u konċiż
• Sensittivi għall-ħin
• Immexxi minn: Telegram → Viber → RCS → SMS

Każijiet ta’ Użu

• Konfermi tal-ordnijiet
• Notifiki tal-ħlas
• Twissijiet tal-kont
• Notifiki tas-sigurtà
• Aġġornamenti tal-kunsinna
• Irrisettja l-password

Eżempju

{
  "id": "tx-order-12345",
  "fromName": "YourStore",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "transaction",
  "text": "Order #12345 confirmed. Total: $99.99. Delivery: Jan 25. Track: https://example.com/track/12345",
  "ttl": 86400
}

L-Aħjar Prattiki

• ✅ Żomm messaġġi taħt 160 karattru meta jkun possibbli
• ✅ Inkludi dettalji rilevanti tat-tranżazzjoni
• ✅ Ipprovdi links ta’ traċċar
• ✅ Uża lingwaġġ ċar u professjonali
• ❌ Tinkludix kontenut ta’ kummerċjalizzazzjoni
• ❌ Tużax emojis b’mod eċċessiv

Eżempji skond Każ ta’ Użu

Konferma tal-Ordni

{
  "messageType": "transaction",
  "text": "Order #12345 confirmed. Total: $99.99. Expected delivery: Jan 25."
}

Notifika tal-Ħlas

{
  "messageType": "transaction",
  "text": "Payment of $150.00 to Merchant ABC successful. Transaction ID: TXN789. Balance: $850.00"
}

Twissija tas-Sigurtà

{
  "messageType": "transaction",
  "text": "New login detected from iPhone at 10:30 AM. Location: New York. If this wasn't you, secure your account immediately."
}

Aġġornament tal-Kunsinna

{
  "messageType": "transaction",
  "text": "Your package is out for delivery! Expected arrival: 2-4 PM. Track: https://track.example.com/PKG123"
}

Messaġġi promozzjonali

Kampanji ta’ kummerċjalizzazzjoni u promozzjonali b’midja rikka u elementi interattivi.

Karatteristiċi

• Appoġġ tal-midja sinjuri
• Buttuni interattivi
• Iffukat fuq is-sejħa għall-azzjoni
• TTL itwal aċċettabbli
• Immexxi minn: Telegram → Viber → RCS → SMS

Każijiet ta’ Użu

• Tnedija tal-prodotti
• Avviżi tal-bejgħ
• Stediniet għal avvenimenti
• Kampanji ta’ newsletter
• Offerti speċjali
• Għarfien tad-ditta

Eżempju

{
  "id": "promo-summer-sale",
  "fromName": "YourBrand",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "promo",
  "text": "🌟 Summer Sale! Up to 50% off on selected items. Shop now: https://example.com/sale",
  "ttl": 259200
}

Bil Varjabbli

{
  "messageType": "promo",
  "text": "Hi %name=1%! Exclusive offer: Use code %name=2% for 20% off. Shop: %short_url=1%",
  "variables": [
    {"id": 1, "type": "name", "value": "John"},
    {"id": 2, "type": "name", "value": "VIP20"},
    {"id": 1, "type": "short_url", "value": "https://store.com/sale?utm=sms"}
  ]
}

L-Aħjar Prattiki

• ✅ Inkludi sejħa għall-azzjoni ċara
• ✅ Uża lingwaġġ impenjattiv
• ✅ Żid parametri ta’ traċċar mal-URLs
• ✅ Ippersonalizza b’varjabbli
• ✅ Test fuq kanali multipli
• ❌ Tispamx lill-klijenti
• ❌ Tużax kontenut qarrieqi
• ❌ Taqbiżx il-limiti tal-karattri

Eżempji skond Każ ta’ Użu

Tnedija tal-Prodott

{
  "messageType": "promo",
  "text": "🎉 NEW ARRIVAL: iPhone 15 Pro now available! Pre-order today and get free shipping. Visit: https://store.com/iphone15"
}

Bejgħ Flash

{
  "messageType": "promo",
  "text": "⚡ FLASH SALE: 2 hours only! Extra 30% off everything. Use code: FLASH30. Shop now: https://store.com/flash"
}

Stedina għal Avveniment

{
  "messageType": "promo",
  "text": "You're invited! VIP Shopping Event on Jan 25 at 6 PM. Exclusive deals + refreshments. RSVP: https://events.com/vip"
}

Karrettun Abbandunat

{
  "messageType": "promo",
  "text": "Hi %name=1%! You left items in your cart. Complete purchase now and get 10% off with code CART10: %short_url=1%"
}

Stħarriġ Viber

Stħarriġ u stħarriġ interattivi għall-ġbir tal-feedback tal-klijenti.

Karatteristiċi

• 2-5 għażliet ta ‘rispons
• Test limitat għal 85 karattru
• Interactive interactive fuq Viber
• Fallback għall-SMS (mingħajr interattività)
• Format ta’ mistoqsija waħda

Każijiet ta’ Użu

• Stħarriġ dwar is-sodisfazzjon tal-klijenti
• Feedback tal-prodott
• Klassifikazzjonijiet tal-kwalità tas-servizz
• Riċerka tas-suq
• Feedback tal-avveniment
• Score Net Promoter (NPS)

Eżempju

{
  "id": "survey-satisfaction-001",
  "fromName": "YourBrand",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "viber_survey",
  "text": "How satisfied are you with our service?",
  "surveyOptions": [
    "Very Satisfied",
    "Satisfied",
    "Neutral",
    "Dissatisfied",
    "Very Dissatisfied"
  ],
  "ttl": 604800
}

Limitazzjonijiet

• Test: Massimu ta’ 85 karattru
• Għażliet: 2-5 għażliet
• Tul tal-Għażla: Żomm taħt 30 karattru kull wieħed
• TTL: Rakkomandat 7-30 jum

L-Aħjar Prattiki

• ✅ Staqsi mistoqsija waħda ċara
• ✅ Ipprovdi għażliet bilanċjati
• ✅ Uża lingwaġġ sempliċi
• ✅ Żomm l-għażliet konċiżi
• ✅ Issettja TTL xieraq (7+ ijiem)
• ❌ M’għandekx tistaqsi mistoqsijiet multipli
• ❌ Tużax lingwaġġ tekniku
• ❌ Tippreġudikax ir-risponsi

Eżempji skond Każ ta’ Użu

Sodisfazzjon tal-Klijent (NPS)

{
  "messageType": "viber_survey",
  "text": "How likely are you to recommend us to a friend?",
  "surveyOptions": [
    "0 - Not at all",
    "1-6 - Unlikely",
    "7-8 - Likely",
    "9-10 - Very Likely"
  ]
}

Feedback tal-Prodott

{
  "messageType": "viber_survey",
  "text": "How do you rate our new product?",
  "surveyOptions": [
    "⭐️ Excellent",
    "⭐️ Good",
    "⭐️ Average",
    "⭐️ Poor",
    "⭐️ Very Poor"
  ]
}

Kwalità tas-Servizz

{
  "messageType": "viber_survey",
  "text": "Was your support experience helpful?",
  "surveyOptions": [
    "Yes, very helpful",
    "Somewhat helpful",
    "Not helpful"
  ]
}

Feedback tal-Avveniment

{
  "messageType": "viber_survey",
  "text": "Would you attend our events again?",
  "surveyOptions": [
    "Definitely yes",
    "Probably yes",
    "Not sure",
    "Probably not",
    "Definitely not"
  ]
}

Sejħa Flash

Verifika tat-telefon billi tuża sejħiet awtomatizzati minflok kodiċijiet SMS.

Karatteristiċi

• Verifika kosteffettiva
• Aktar malajr minn SMS (1-3 sekondi)
• L-ebda kodiċi viżibbli fin-notifiki
• Reżistenti għal attakki ta ‘skambju ta’ SIM
• Telefonata biss (l-ebda Telegram/Viber)

Każijiet ta’ Użu

• Reġistrazzjoni tal-utent
• Verifika tal-login
• Validazzjoni tan-numru tat-telefon
• Awtentikazzjoni b’żewġ fatturi
• Irkupru tal-kont
• Konferma tat-tranżazzjoni

Eżempju

{
  "id": "verify-user-12345",
  "fromName": "YourApp",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "flashcall",
  "ttl": 300
}

Kif Taħdem

1. L-utent idaħħal in-numru tat-telefon
2. API tibda sejħa flash
3. Is-sejħa tintemm wara 1-2 ċrieki
4. App jaqbad l-ID tas-sejjieħ
5. Caller ID verifikata kontra l-mudell
6. Utent awtentikat

L-Aħjar Prattiki

• ✅ Issettja TTL qasir (60-300 sekonda)
• ✅ Implimenta l-iskoperta tal-ID tas-sejjieħ
• ✅ Ipprovdi SMS fallback
• ✅ Immaniġġja talbiet għal permess
• ✅ Uri istruzzjonijiet ċari
• ❌ Tużax għal skopijiet promozzjonali
• ❌ Issettjax TTL twil

Eżempju b’Fallback

{
  "id": "verify-001",
  "fromName": "YourApp",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "flashcall",
  "ttl": 300,
  "fallback": {
    "messageType": "transaction",
    "text": "Your verification code: 123456"
  }
}

L-għażla tat-Tip it-Tajjeb

Siġra tad-Deċiżjoni

Is it time-critical or transactional?
├─ Yes → transaction
└─ No
   └─ Is it promotional?
      ├─ Yes → promo
      └─ No
         └─ Is it a survey?
            ├─ Yes → viber_survey
            └─ No → Is it for verification?
               ├─ Yes → flashcall
               └─ No → transaction (default)

Matriċi ta’ Paragun

Karatteristika	Transazzjoni	Promo	Stħarriġ	Sejħa Flash
Rich Media	❌	✅	❌	❌
Interattiv	❌	✅	✅	❌
Personalizzazzjoni	✅	✅	✅	❌
TTL tipiku	Sigħat	Jiem	Ġimgħa	Minuti
Spiża	Medju	Medju	Medju	Baxxa
Veloċità ta’ Kunsinna	Fast	Fast	Fast	L-iktar mgħaġġla

Eżempju ta’ Implimentazzjoni

class CascadeMessageBuilder {
  constructor(apiKey) {
    this.apiKey = apiKey;
  }

  buildTransaction(id, fromName, toPhone, text, ttl = 86400) {
    return {
      id,
      fromName,
      toPhone,
      messageType: 'transaction',
      text,
      ttl
    };
  }

  buildPromo(id, fromName, toPhone, text, ttl = 259200) {
    return {
      id,
      fromName,
      toPhone,
      messageType: 'promo',
      text,
      ttl
    };
  }

  buildSurvey(id, fromName, toPhone, text, options, ttl = 604800) {
    if (text.length > 85) {
      throw new Error('Survey text must be under 85 characters');
    }

    if (options.length < 2 || options.length > 5) {
      throw new Error('Survey must have 2-5 options');
    }

    return {
      id,
      fromName,
      toPhone,
      messageType: 'viber_survey',
      text,
      surveyOptions: options,
      ttl
    };
  }

  buildFlashCall(id, fromName, toPhone, ttl = 300) {
    return {
      id,
      fromName,
      toPhone,
      messageType: 'flashcall',
      ttl
    };
  }

  async send(message) {
    // Implementation to send message
  }
}

// Usage
const builder = new CascadeMessageBuilder('your-api-key');

// Transaction
const transaction = builder.buildTransaction(
  'order-123',
  'Store',
  '+380XXXXXXXXX',
  'Order confirmed'
);

// Promo
const promo = builder.buildPromo(
  'promo-001',
  'Brand',
  '+380XXXXXXXXX',
  'Sale now on!'
);

// Survey
const survey = builder.buildSurvey(
  'survey-001',
  'Brand',
  '+380XXXXXXXXX',
  'Rate our service?',
  ['Excellent', 'Good', 'Average', 'Poor']
);

// Flash Call
const flashCall = builder.buildFlashCall(
  'verify-001',
  'App',
  '+380XXXXXXXXX'
);

Il-passi li jmiss

• Ibgħat Messaġġi - Ibda tibgħat messaġġi kaskata
• Varjabbli tal-Messaġġi - Ippersonalizza l-messaġġi
• SMSBAT API - Esplora l-karatteristiċi ta’ SMSBAT