Invia messaggi a cascata

Invia messaggi su più canali con un'unica richiesta API. Cascade instrada automaticamente il tuo messaggio tramite Telegram Bot, Viber Bot, Viber Business Messages, RCS e SMS.

Endpoint

Cascata standard

POST /api/CascadeMessage/send_message/async

Instrada i messaggi attraverso tutti i canali disponibili in sequenza.

Priorità Telegram-Viber

POST /api/CascadeMessage/send_message/tg-viber/async

Dà priorità ai canali Telegram e Viber per una consegna più rapida.

Autenticazione

L'API Cascade supporta tre intestazioni di autenticazione. Includine almeno uno:

Intestazione	Descrizione
"Chiave di autorizzazione X"	Chiave API SMSBAT (consigliata)
"X-Viber-Auth-Token"	Credenziali del bot Viber
"Chiave X-Tg-Bot"	Tasto bot di Telegram

Richiedi struttura

Intestazioni

CODICE_BLOCCO_2

Richiedi corpo

Invia un array di oggetti messaggio:

[
  {
    "id": "unique-tracking-id",
    "fromName": "YourBrand",
    "toPhone": "+380XXXXXXXXX",
    "messageType": "transaction",
    "text": "Your order #12345 has been confirmed",
    "ttl": 3600,
    "scheduledSent": "2025-01-25T10:00:00Z"
  }
]

Parametri

Parametro	Digitare	Obbligatorio	Descrizione
id	stringa	Sì	Il tuo identificatore di tracciamento
daNome	stringa	Sì	Nome visualizzato del mittente
"al telefono"	stringa	Sì	Numero di telefono del destinatario (formato E.164)
tipomessaggio	stringa	Sì	Tipo di messaggio: transaction, promo, viber_survey, flashcall
"testo"	stringa	Sì*	Contenuto del messaggio (* richiesto per la maggior parte dei tipi)
ttl	intero	No	Tempo di vita in secondi
scheduledSent	stringa	No	Data e ora ISO 8601 per la consegna programmata

Tipi di messaggi

Messaggi di transazione

Notifiche critiche come conferme d'ordine e aggiornamenti dell'account:

{
  "id": "order-12345",
  "fromName": "YourStore",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "transaction",
  "text": "Your order #12345 has been confirmed and will arrive tomorrow.",
  "ttl": 86400
}

Messaggi promozionali

Campagne di marketing con rich media:

CODICE_BLOCCO_5

Sondaggio Viber

Sondaggi interattivi con 2-5 opzioni di risposta:

CODICE_BLOCCO_6

Massimo testo del sondaggio: 85 caratteri

Chiamata flash

Verifica telefonica tramite chiamata automatizzata:

CODICE_BLOCCO_7

Esempi

Transazione di base

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "tx-001",
      "fromName": "YourBank",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "transaction",
      "text": "Payment of $100 was successful. Transaction ID: ABC123"
    }
  ]'

Promozione programmata

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "promo-001",
      "fromName": "YourStore",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "promo",
      "text": "Flash Sale starts in 1 hour! Visit: https://example.com",
      "scheduledSent": "2025-01-25T09:00:00Z",
      "ttl": 3600
    }
  ]'

Messaggi in blocco

curl -X POST https://restapi.smsbat.com/api/CascadeMessage/send_message/async \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '[
    {
      "id": "bulk-001",
      "fromName": "YourBrand",
      "toPhone": "+380111111111",
      "messageType": "transaction",
      "text": "Message 1"
    },
    {
      "id": "bulk-002",
      "fromName": "YourBrand",
      "toPhone": "+380222222222",
      "messageType": "transaction",
      "text": "Message 2"
    },
    {
      "id": "bulk-003",
      "fromName": "YourBrand",
      "toPhone": "+380333333333",
      "messageType": "transaction",
      "text": "Message 3"
    }
  ]'

Risposta

Risposta riuscita

[
  {
    "messageId": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "trackinId": "tx-001"
  },
  {
    "messageId": "8b2f1e9a-4c6d-4e2a-9f8b-1a3d5c7e9f0b",
    "trackinId": "tx-002"
  }
]

Campi di risposta

Campo	Digitare	Descrizione
messaggioId	stringa (UUID)	Identificatore del messaggio di sistema
trackinId	stringa	Il tuo identificatore di tracciamento (dalla richiesta)

Utilizza "messageId" per il monitoraggio dello stato e "trackinId" per la correlazione con il tuo sistema.

Esempi di implementazione

Pitone

CODICE_BLOCCO_12

JavaScript (Node.js)

const axios = require('axios');

class CascadeMessenger {
  constructor(apiKey) {
    this.baseUrl = 'https://restapi.smsbat.com';
    this.headers = {
      'Content-Type': 'application/json',
      'X-Authorization-Key': apiKey
    };
  }

  async sendMessage({ id, fromName, toPhone, messageType, text, ttl, scheduledSent }) {
    const message = {
      id,
      fromName,
      toPhone,
      messageType,
      text
    };

    if (ttl) message.ttl = ttl;
    if (scheduledSent) message.scheduledSent = scheduledSent;

    const response = await axios.post(
      `${this.baseUrl}/api/CascadeMessage/send_message/async`,
      [message],
      { headers: this.headers }
    );

    return response.data[0];
  }

  async sendBulk(messages) {
    const response = await axios.post(
      `${this.baseUrl}/api/CascadeMessage/send_message/async`,
      messages,
      { headers: this.headers }
    );

    return response.data;
  }

  async sendTelegramViber({ id, fromName, toPhone, messageType, text }) {
    const response = await axios.post(
      `${this.baseUrl}/api/CascadeMessage/send_message/tg-viber/async`,
      [{
        id,
        fromName,
        toPhone,
        messageType,
        text
      }],
      { headers: this.headers }
    );

    return response.data[0];
  }
}

// Usage
const messenger = new CascadeMessenger('your-api-key');

// Send single message
const result = await messenger.sendMessage({
  id: 'order-12345',
  fromName: 'YourStore',
  toPhone: '+380XXXXXXXXX',
  messageType: 'transaction',
  text: 'Your order has been confirmed',
  ttl: 86400
});

console.log('Message ID:', result.messageId);

// Send scheduled message
const scheduledTime = new Date(Date.now() + 2 * 60 * 60 * 1000);
await messenger.sendMessage({
  id: 'promo-001',
  fromName: 'YourBrand',
  toPhone: '+380XXXXXXXXX',
  messageType: 'promo',
  text: 'Sale starts now!',
  scheduledSent: scheduledTime.toISOString()
});

// Bulk send
const messages = Array.from({ length: 100 }, (_, i) => ({
  id: `bulk-${i}`,
  fromName: 'YourBrand',
  toPhone: `+38011111111${i}`,
  messageType: 'transaction',
  text: `Message ${i}`
}));

const results = await messenger.sendBulk(messages);
console.log(`Sent ${results.length} messages`);

PHP

CODICE_BLOCCO_14

Migliori pratiche

Numeri di telefono

Utilizza sempre il formato E.164: - ✅ +380XXXXXXXXX - ❌ 380XXXXXXXXX - ❌ 0XXXXXXXXX

ID di monitoraggio

• Utilizza ID univoci per ciascun messaggio
• Includi il contesto nell'ID (ad esempio, order-12345, promo-summer-2025)
• Mantieni gli ID inferiori a 255 caratteri
• Evitare caratteri speciali

TTL (Time-to-Live)

Valori TTL consigliati:

• OTP/Verifica: 300-600 secondi (5-10 minuti)
• Transazionale: 3600-86400 secondi (1-24 ore)
• Promozionale: 86400-259200 secondi (1-3 giorni)
• Sondaggi: 604800 secondi (7 giorni)

Messaggi pianificati

• Utilizza il fuso orario UTC per "scheduledSent".
• Non programmare con più di 30 giorni di anticipo
• Tenere conto delle differenze di fuso orario
• Prova prima con i programmi del prossimo futuro

Invio in blocco

• Invia in batch di 100-1000 messaggi
• Implementare la limitazione della velocità
• Gestire gli errori con garbo
• Riprova i messaggi non riusciti

Gestione degli errori

Codici di stato HTTP

Codice	Descrizione
200	Successo
400	Richiesta errata: parametri non validi
401	Non autorizzato: chiave API non valida
429	Troppe richieste
500	Errore del server

Risposta all'errore

CODICE_BLOCCO_15

Riprova logica

async function sendWithRetry(message, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await messenger.sendMessage(message);
    } catch (error) {
      if (error.response?.status === 400) {
        // Don't retry validation errors
        throw error;
      }

      if (i === maxRetries - 1) throw error;

      // Exponential backoff
      await new Promise(resolve =>
        setTimeout(resolve, Math.pow(2, i) * 1000)
      );
    }
  }
}

Passaggi successivi

• Variabili del messaggio - Utilizza contenuto dinamico
• Tipi di messaggio - Esplora i tipi di messaggio
• Stato di consegna - Tieni traccia della consegna