Kalo te përmbajtja

Llojet e mesazheve

Cascade API mbështet katër lloje mesazhesh, secili i optimizuar për raste të ndryshme përdorimi dhe kanale.

Përmbledhje

Lloji Qëllimi Kanalet Interaktive
'transaksion' Njoftimet kritike Të gjitha Jo
promo Fushata marketingu Të gjitha Po (butonat)
viber_survey Sondazhet dhe komentet Viber, SMS Po (opsione)
flashcall Verifikimi i telefonit Telefonatë Jo

Mesazhet e transaksionit

Njoftimet kritike si konfirmimet e porosive, përditësimet e llogarisë dhe sinjalizimet e sistemit.

Karakteristikat

  • Dorëzimi me prioritet të lartë
  • Nuk ka përmbajtje promovuese
  • E drejtpërdrejtë dhe koncize
  • I ndjeshëm ndaj kohës
  • Drejtuar përmes: Telegram → Viber → RCS → SMS

Rastet e përdorimit

  • Konfirmimet e porosive
  • Njoftimet e pagesës
  • Sinjalizimet e llogarisë
  • Njoftimet e sigurisë
  • Përditësimet e dorëzimit
  • Rivendos fjalëkalimin

Shembull

{
  "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
}

Praktikat më të mira

  • ✅ Mbani mesazhet nën 160 karaktere kur është e mundur
  • ✅ Përfshi detajet përkatëse të transaksionit
  • ✅ Siguroni lidhje përcjellëse
  • ✅ Përdorni gjuhë të qartë dhe profesionale
  • ❌ Mos përfshini përmbajtje marketingu
  • ❌ Mos përdorni emoji tepër

Shembuj sipas rastit të përdorimit

Konfirmimi i porosisë

KODI_BLOCK_1

Njoftim pagese

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

Sinjalizim sigurie

KODI_BLOCK_3

Përditësim i dorëzimit

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

Mesazhe Promo

Fushata marketingu dhe promovuese me media të pasura dhe elemente interaktive.

Karakteristikat

  • Mbështetje e pasur mediatike
  • Butonat interaktiv
  • I fokusuar në thirrje për veprim
  • TTL më e gjatë e pranueshme
  • Drejtuar përmes: Telegram → Viber → RCS → SMS

Rastet e përdorimit

  • Lansimet e produkteve
  • Njoftimet për shitje
  • Ftesat për ngjarje
  • Fushatat e buletinit
  • Oferta speciale
  • Ndërgjegjësimi i markës

Shembull

{
  "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
}

Me variabla

{
  "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"}
  ]
}

Praktikat më të mira

  • ✅ Përfshi thirrje të qartë për veprim
  • ✅ Përdorni një gjuhë tërheqëse
  • ✅ Shtoni parametra gjurmimi në URL
  • ✅ Personalizojeni me variabla
  • ✅ Testoni në kanale të shumta
  • ❌ Mos dërgoni mesazhe të padëshiruara për klientët
  • ❌ Mos përdorni përmbajtje mashtruese
  • ❌ Mos i tejkaloni kufijtë e karaktereve

Shembuj sipas rastit të përdorimit

Nisja e produktit

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

Shitje me Flash

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

Ftesë për ngjarje

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

Karroca e braktisur

{
  "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%"
}

Anketa Viber

Sondazhe dhe sondazhe interaktive për mbledhjen e reagimeve të klientëve.

Karakteristikat

  • 2-5 opsione përgjigjeje
  • Teksti i kufizuar në 85 karaktere
  • Ndërfaqe interaktive në Viber
  • Rikthim në SMS (pa interaktivitet)
  • Formati me një pyetje

Rastet e përdorimit

  • Anketat e kënaqësisë së klientit
  • Komentet e produktit
  • Vlerësimet e cilësisë së shërbimit
  • Hulumtimi i tregut
  • Komentet e ngjarjes
  • Rezultati neto i promovuesit (NPS)

Shembull

{
  "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
}

Kufizimet

  • Tekst: Maksimumi 85 karaktere
  • Opsionet : 2-5 zgjedhje
  • Gjatësia e opsionit: Mbani nën 30 karaktere secili
  • TTL: Rekomandohet 7-30 ditë

Praktikat më të mira

  • ✅Bëni një pyetje të qartë
  • ✅ Ofroni opsione të balancuara
  • ✅ Përdorni gjuhë të thjeshtë
  • ✅ Mbani opsionet koncize
  • ✅ Vendos TTL-në e duhur (7+ ditë)
  • ❌ Mos bëni pyetje të shumta
  • ❌ Mos përdorni zhargon teknik
  • ❌ Mos i anashkaloni përgjigjet

Shembuj sipas rastit të përdorimit

Kënaqësia e klientit (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"
  ]
}

Reagime për produktin

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

Cilësia e shërbimit

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

Komentet e ngjarjes

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

Thirrje flash

Verifikimi i telefonit duke përdorur thirrje të automatizuara në vend të kodeve SMS.

Karakteristikat

  • Verifikimi me kosto efektive
  • Më shpejt se SMS (1-3 sekonda)
  • Nuk ka kod të dukshëm në njoftime
  • Rezistent ndaj sulmeve të shkëmbimit të kartave SIM
  • Vetëm telefonatë (pa Telegram/Viber)

Rastet e përdorimit

  • Regjistrimi i përdoruesit
  • Verifikimi i hyrjes
  • Vërtetimi i numrit të telefonit
  • Autentifikimi me dy faktorë
  • Rikuperimi i llogarisë
  • Konfirmimi i transaksionit

Shembull

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

Si funksionon

  1. Përdoruesi fut numrin e telefonit
  2. API fillon thirrjen flash
  3. Telefonata përfundon pas 1-2 zileve
  4. Aplikacioni kap ID-në e telefonuesit
  5. ID e thirrësit e verifikuar sipas modelit
  6. Përdoruesi është vërtetuar

Praktikat më të mira

  • ✅ Vendos TTL të shkurtër (60-300 sekonda)
  • ✅ Zbatoni zbulimin e ID-së së telefonuesit
  • ✅ Siguroni kthim SMS
  • ✅ Trajtoni kërkesat për leje
  • ✅ Trego udhëzime të qarta
  • ❌ Mos e përdorni për qëllime promovuese
  • ❌ Mos e vendosni TTL të gjatë

Shembull me Fallback

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

Zgjedhja e llojit të duhur

Pema e vendimit

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)

Matrica e Krahasimit

Veçori Transaksioni Promo Anketa Thirrje Flash
Media e pasur ❌ ✅ ❌ ❌
Interaktive ❌ ✅ ✅ ❌
Personalizimi ✅ ✅ ✅ ❌
TTL tipike Orari Ditë Java Minutat
Kostoja E mesme E mesme E mesme E ulët
Shpejtësia e dorëzimit Shpejt Shpejt Shpejt Më e shpejta

Shembull i zbatimit

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'
);

Hapat e ardhshëm