Vai al contenuto

Variabili del messaggio

Utilizza le variabili per personalizzare i messaggi a cascata con contenuti dinamici come nomi, URL e valori personalizzati.

Panoramica

Le variabili consentono:

  • Personalizzazione: inserisci i nomi dei destinatari, i numeri di conto
  • URL dinamici: includi collegamenti univoci per ciascun destinatario
  • Abbreviazione URL: accorcia automaticamente gli URL lunghi
  • Riutilizzabilità del modello: un modello, tanti messaggi personalizzati

Tipi di variabili

Digitare Sintassi Scopo Esempio
nome %nome=id% Variabili di testo Nomi, codici, importi
"url" %url=id% URL completi Link, URL di monitoraggio
url_breve %short_url=id% URL abbreviati Collegamenti compatti

Sintassi della variabile

Le variabili utilizzano il formato: %type=id%

  • type: tipo di variabile (name, url, short_url)
  • id: Identificatore univoco (intero)

Esempi

Hello %name=1%, your code is %name=2%
Visit our website: %url=1%
Quick link: %short_url=1%

Utilizzo delle variabili

Passaggio 1: carica i valori delle variabili

Prima di inviare messaggi, carica i valori delle variabili nell'API:

Punto finale: 

POST https://restapi.smsbat.com/api/items

Richiesta: CODICE_BLOCCO_2

Passaggio 2: invia un messaggio con variabili

Utilizza gli ID variabili caricati nel tuo messaggio:

{
  "id": "msg-001",
  "fromName": "YourStore",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "transaction",
  "text": "Hello %name=1%! Your verification code is %name=2%. Visit: %short_url=4%"
}

Risultato: 

Hello John! Your verification code is 12345. Visit: https://sho.rt/abc123

Esempio completo

Carica variabili

CODICE_BLOCCO_5

Invia messaggio

CODICE_BLOCCO_6

Messaggio consegnato: CODICE_BLOCCO_7

Casi d'uso

Conferma dell'ordine

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "John"},
    {"id": 2, "type": "name", "value": "12345"},
    {"id": 3, "type": "name", "value": "$99.99"},
    {"id": 4, "type": "url", "value": "https://store.com/order/12345"}
  ]
}

// Message
{
  "text": "Hi %name=1%! Order #%name=2% for %name=3% confirmed. Details: %url=4%"
}

// Result
"Hi John! Order #12345 for $99.99 confirmed. Details: https://store.com/order/12345"

Reimpostazione della password

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "Mike"},
    {"id": 2, "type": "short_url", "value": "https://app.example.com/reset?token=abc123def456"}
  ]
}

// Message
{
  "text": "Hi %name=1%, reset your password: %short_url=2% (valid 30 min)"
}

// Result
"Hi Mike, reset your password: https://sho.rt/xyz789 (valid 30 min)"

Campagna promozionale

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "VIP20"},
    {"id": 2, "type": "short_url", "value": "https://store.com/sale?utm_source=sms&utm_campaign=summer"}
  ]
}

// Message
{
  "text": "Summer Sale! Use code %name=1% for 20% off: %short_url=2%"
}

// Result
"Summer Sale! Use code VIP20 for 20% off: https://sho.rt/abc"

Verifica dell'account

// Variables
{
  "variables": [
    {"id": 1, "type": "name", "value": "789456"},
    {"id": 2, "type": "name", "value": "10"}
  ]
}

// Message
{
  "text": "Your verification code: %name=1%. Valid for %name=2% minutes."
}

// Result
"Your verification code: 789456. Valid for 10 minutes."

Esempi di implementazione

Pitone

CODICE_BLOCCO_12

JavaScript (Node.js)

const axios = require('axios');

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

  async uploadVariables(variables) {
    const response = await axios.post(
      `${this.baseUrl}/api/items`,
      { variables },
      { headers: this.headers }
    );

    return response.data;
  }

  async sendWithVariables({ id, fromName, toPhone, messageType, text, variables }) {
    // Upload variables first
    await this.uploadVariables(variables);

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

    return response.data[0];
  }
}

// Usage
const cascade = new CascadeVariables('your-api-key');

const result = await cascade.sendWithVariables({
  id: 'order-notification',
  fromName: 'YourStore',
  toPhone: '+380XXXXXXXXX',
  messageType: 'transaction',
  text: 'Hi %name=1%! Order %name=2% shipped. Track: %url=3%',
  variables: [
    { id: 1, type: 'name', value: 'John' },
    { id: 2, type: 'name', value: 'ORD-12345' },
    { id: 3, type: 'url', value: 'https://example.com/track/ORD-12345' }
  ]
});

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

PHP

CODICE_BLOCCO_14

Migliori pratiche

ID variabili

  • ✅ Utilizza ID sequenziali (1, 2, 3, ...)
  • ✅ Riutilizza gli ID per messaggi collettivi con le stesse variabili
  • ✅ Mappatura degli ID variabili dei documenti
  • ❌Non utilizzare ID casuali
  • ❌Non saltare i numeri identificativi

Valori variabili

  • ✅ Convalida i valori prima del caricamento
  • ✅ Gestisci correttamente i caratteri speciali
  • ✅Test con casi limite
  • ❌ Non includere HTML nelle variabili dei nomi
  • ❌Non superare limiti di lunghezza ragionevoli

Variabili URL

  • ✅ Utilizza short_url per gli URL lunghi
  • ✅Includi parametri di tracciamento
  • ✅ Utilizza HTTPS
  • ❌ Non utilizzare URL dall'aspetto sospetto
  • ❌ Non includere dati sensibili negli URL

Prestazioni

  • Carica le variabili una volta, invia più messaggi
  • Caricamenti variabili in batch
  • Memorizza nella cache le variabili comunemente utilizzate
  • Pulisci periodicamente le vecchie variabili

Modelli avanzati

Personalizzazione in blocco

CODICE_BLOCCO_15

Sistema di modelli

class MessageTemplate {
  constructor(template) {
    this.template = template;
    this.varIdCounter = 1;
  }

  create(data) {
    const variables = [];
    let text = this.template;

    // Replace placeholders with variable syntax
    Object.entries(data).forEach(([key, value]) => {
      const varId = this.varIdCounter++;
      variables.push({
        id: varId,
        type: this.getVarType(value),
        value: value
      });

      text = text.replace(`{{${key}}}`, `%${this.getVarType(value)}=${varId}%`);
    });

    return { text, variables };
  }

  getVarType(value) {
    if (value.startsWith('http')) return 'url';
    return 'name';
  }
}

// Usage
const template = new MessageTemplate(
  'Hi {{name}}! Order {{orderId}} shipped. Track: {{trackUrl}}'
);

const { text, variables } = template.create({
  name: 'John',
  orderId: 'ORD-123',
  trackUrl: 'https://example.com/track/ORD-123'
});

await sendWithVariables({ text, variables });

Risoluzione dei problemi

Variabili non sostituite

  • Verificare che le variabili siano state caricate prima dell'invio
  • Controlla le corrispondenze dell'ID variabile nel testo e caricalo
  • Assicurarsi che la sintassi corretta: %type=id%
  • Convalida che il tipo di variabile corrisponda al valore

Accorciamento URL non riuscito

  • Verificare che l'URL sia valido e accessibile
  • Verifica che l'URL inizi con http:// o https://
  • Assicurati che l'URL non sia già abbreviato
  • Prova a utilizzare url invece di short_url

Limite variabile superato

  • Contattare l'assistenza per i limiti variabili
  • Riutilizzare gli ID variabili quando possibile
  • Pulisci le vecchie variabili
  • Ottimizza l'utilizzo variabile

Passaggi successivi