Ir para o conteúdo

Tipos de mensagens

A API Cascade oferece suporte a quatro tipos de mensagens, cada um otimizado para diferentes casos de uso e canais.

Visão geral

Tipo Finalidade Canais Interativo
transação Notificações críticas Todos Não
promoção Campanhas de marketing Todos Sim (botões)
viber_survey Enquetes e comentários Viber, SMS Sim (opções)
flashcall Verificação de telefone Chamada telefônica Não

Mensagens de transação

Notificações críticas, como confirmações de pedidos, atualizações de conta e alertas de sistema.

Características

  • Entrega de alta prioridade
  • Sem conteúdo promocional
  • Direto e conciso
  • Sensível ao tempo
  • Roteado através de: Telegram → Viber → RCS → SMS

Casos de uso

  • Confirmações de pedidos
  • Notificações de pagamento
  • Alertas de conta
  • Notificações de segurança
  • Atualizações de entrega
  • Redefinições de senha

Exemplo

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

Melhores Práticas

  • ✅ Mantenha as mensagens com menos de 160 caracteres quando possível
  • ✅ Incluir detalhes relevantes da transação
  • ✅ Fornece links de rastreamento
  • ✅ Use uma linguagem clara e profissional
  • ❌ Não inclua conteúdo de marketing
  • ❌ Não use emojis excessivamente

Exemplos por caso de uso

Confirmação do pedido

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

Notificação de pagamento

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

Alerta de segurança

CODE_BLOCO_3

Atualização de entrega

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

Mensagens promocionais

Campanhas de marketing e promocionais com rich media e elementos interativos.

Características

  • Suporte de mídia rica
  • Botões interativos
  • Foco em call to action
  • TTL mais longo aceitável
  • Roteado através de: Telegram → Viber → RCS → SMS

Casos de uso

  • Lançamentos de produtos
  • Anúncios de vendas
  • Convites para eventos
  • Campanhas de boletins informativos
  • Ofertas especiais
  • Conscientização da marca

Exemplo

CODE_BLOCO_5

Com variáveis

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

Melhores Práticas

  • ✅ Incluir uma frase de chamariz clara
  • ✅ Use uma linguagem envolvente
  • ✅ Adicionar parâmetros de rastreamento a URLs
  • ✅ Personalize com variáveis
  • ✅ Teste em vários canais
  • ❌ Não envie spam para clientes
  • ❌ Não use conteúdo enganoso
  • ❌ Não exceda os limites de caracteres

Exemplos por caso de uso

Lançamento de produto

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

Promoção relâmpago

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

Convite para Evento

CODE_BLOCO_9

Carrinho Abandonado

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

Pesquisa Viber

Enquetes e pesquisas interativas para coletar feedback dos clientes.

Características

  • 2 a 5 opções de resposta
  • Texto limitado a 85 caracteres
  • Interface interativa no Viber
  • Fallback para SMS (sem interatividade)
  • Formato de pergunta única

Casos de uso

  • Pesquisas de satisfação do cliente
  • Feedback do produto
  • Avaliações de qualidade de serviço
  • Pesquisa de mercado
  • Feedback do evento
  • Pontuação líquida do promotor (NPS)

Exemplo

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

Restrições

  • Texto: máximo de 85 caracteres
  • Opções: 2 a 5 opções
  • Comprimento da opção: mantenha menos de 30 caracteres cada
  • TTL: recomendado de 7 a 30 dias

Melhores Práticas

  • ✅ Faça uma pergunta clara
  • ✅ Fornece opções equilibradas
  • ✅ Use uma linguagem simples
  • ✅ Mantenha as opções concisas
  • ✅ Definir TTL apropriado (7+ dias)
  • ❌ Não faça várias perguntas
  • ❌ Não use jargões técnicos
  • ❌ Não enviese as respostas

Exemplos por caso de uso

Satisfação do Cliente (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 do produto

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

Qualidade do Serviço

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

Feedback do evento

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

Chamada Flash

Verificação de telefone usando chamadas automatizadas em vez de códigos SMS.

Características

  • Verificação econômica
  • Mais rápido que SMS (1-3 segundos)
  • Nenhum código visível nas notificações
  • Resistente a ataques de troca de SIM
  • Apenas chamada telefônica (sem Telegram/Viber)

Casos de uso

  • Cadastro de usuário
  • Verificação de login
  • Validação do número de telefone
  • Autenticação de dois fatores
  • Recuperação de conta
  • Confirmação da transação

Exemplo

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

Como funciona

  1. O usuário insere o número de telefone
  2. API inicia chamada flash
  3. A chamada termina após 1-2 toques
  4. App captura identificador de chamadas
  5. Identificador de chamadas verificado em relação ao padrão
  6. Usuário autenticado

Melhores Práticas

  • ✅ Definir TTL curto (60-300 segundos)
  • ✅ Implementar detecção de identificação de chamadas
  • ✅ Fornece substituto de SMS
  • ✅ Lidar com solicitações de permissão
  • ✅ Mostrar instruções claras
  • ❌ Não use para fins promocionais
  • ❌ Não defina TTL longo

Exemplo com substituto

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

Escolhendo o tipo certo

Árvore de decisão

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)

Matriz de Comparação

Recurso Transação Promoção Pesquisa Chamada Flash
Meios interativos ❌ ✅ ❌ ❌
Interativo ❌ ✅ ✅ ❌
Personalização ✅ ✅ ✅ ❌
TTL típico Horas Dias Semana Minutos
Custo Médio Médio Médio Baixo
Velocidade de entrega Rápido Rápido Rápido Mais rápido

Exemplo de implementação

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

Próximas etapas