Biến thông báo

Sử dụng các biến để cá nhân hóa các thông báo xếp tầng với nội dung động như tên, URL và giá trị tùy chỉnh.

Tổng quan

Các biến cho phép:

• Cá nhân hóa: Chèn tên người nhận, số tài khoản
• URL động: Bao gồm các liên kết duy nhất cho mỗi người nhận
• Rút ngắn URL: Tự động rút ngắn các URL dài
• Khả năng sử dụng lại mẫu: Một mẫu, nhiều tin nhắn được cá nhân hóa

Các loại biến

Loại	Cú pháp	Mục đích	Ví dụ
tên	%name=id%	Biến văn bản	Tên, mã số, số tiền
url	%url=id%	URL đầy đủ	Liên kết, URL theo dõi
url_ngắn	%short_url=id%	URL rút gọn	Liên kết nhỏ gọn

Cú pháp biến

Các biến sử dụng định dạng: %type=id%

• type: Loại biến (name, url, short_url)
• id: Mã định danh duy nhất (số nguyên)

Ví dụ

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

Sử dụng biến

Bước 1: Tải lên các giá trị biến

Trước khi gửi tin nhắn, hãy tải các giá trị biến lên API:

Điểm cuối:

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

Yêu cầu:

{
  "variables": [
    {
      "id": 1,
      "type": "name",
      "value": "John"
    },
    {
      "id": 2,
      "type": "name",
      "value": "12345"
    },
    {
      "id": 3,
      "type": "url",
      "value": "https://example.com/products"
    },
    {
      "id": 4,
      "type": "short_url",
      "value": "https://example.com/very-long-url-that-needs-shortening"
    }
  ]
}

Bước 2: Gửi tin nhắn có biến

Sử dụng ID biến đã tải lên trong tin nhắn của bạn:

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

Kết quả:

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

Ví dụ hoàn chỉnh

Tải lên các biến

curl -X POST https://restapi.smsbat.com/api/items \
  -H "Content-Type: application/json" \
  -H "X-Authorization-Key: your-api-key" \
  -d '{
    "variables": [
      {
        "id": 1,
        "type": "name",
        "value": "Sarah"
      },
      {
        "id": 2,
        "type": "name",
        "value": "ORD-789"
      },
      {
        "id": 3,
        "type": "url",
        "value": "https://example.com/track/ORD-789"
      }
    ]
  }'

Gửi tin nhắn

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": "order-notification",
      "fromName": "YourStore",
      "toPhone": "+380XXXXXXXXX",
      "messageType": "transaction",
      "text": "Hi %name=1%! Order %name=2% shipped. Track: %url=3%"
    }
  ]'

Tin nhắn đã gửi:

Hi Sarah! Order ORD-789 shipped. Track: https://example.com/track/ORD-789

Trường hợp sử dụng

Xác nhận đơn hàng

// 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"

Đặt lại mật khẩu

// 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)"

Chiến dịch khuyến mại

// 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"

Xác minh tài khoản

// 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."

Ví dụ triển khai

Python

import requests

class CascadeVariables:
    def __init__(self, api_key):
        self.base_url = 'https://restapi.smsbat.com'
        self.headers = {
            'Content-Type': 'application/json',
            'X-Authorization-Key': api_key
        }

    def upload_variables(self, variables):
        """Upload variable values"""
        response = requests.post(
            f'{self.base_url}/api/items',
            headers=self.headers,
            json={'variables': variables}
        )
        response.raise_for_status()
        return response.json()

    def send_with_variables(self, tracking_id, from_name, to_phone,
                           message_type, text, variables):
        """Upload variables and send message"""
        # Upload variables first
        self.upload_variables(variables)

        # Send message
        message = {
            'id': tracking_id,
            'fromName': from_name,
            'toPhone': to_phone,
            'messageType': message_type,
            'text': text
        }

        response = requests.post(
            f'{self.base_url}/api/CascadeMessage/send_message/async',
            headers=self.headers,
            json=[message]
        )

        response.raise_for_status()
        return response.json()[0]

# Usage
cascade = CascadeVariables('your-api-key')

# Define variables
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'}
]

# Send message with variables
result = cascade.send_with_variables(
    tracking_id='order-notification',
    from_name='YourStore',
    to_phone='+380XXXXXXXXX',
    message_type='transaction',
    text='Hi %name=1%! Order %name=2% shipped. Track: %url=3%',
    variables=variables
)

print(f"Message sent: {result['messageId']}")

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

<?php

class CascadeVariables {
    private $baseUrl = 'https://restapi.smsbat.com';
    private $apiKey;

    public function __construct($apiKey) {
        $this->apiKey = $apiKey;
    }

    public function uploadVariables($variables) {
        $ch = curl_init($this->baseUrl . '/api/items');

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-Authorization-Key: ' . $this->apiKey
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS,
                   json_encode(['variables' => $variables]));

        $response = curl_exec($ch);
        curl_close($ch);

        return json_decode($response, true);
    }

    public function sendWithVariables($id, $fromName, $toPhone,
                                     $messageType, $text, $variables) {
        // Upload variables
        $this->uploadVariables($variables);

        // Send message
        $message = [
            'id' => $id,
            'fromName' => $fromName,
            'toPhone' => $toPhone,
            'messageType' => $messageType,
            'text' => $text
        ];

        $ch = curl_init(
            $this->baseUrl . '/api/CascadeMessage/send_message/async'
        );

        curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
        curl_setopt($ch, CURLOPT_POST, true);
        curl_setopt($ch, CURLOPT_HTTPHEADER, [
            'Content-Type: application/json',
            'X-Authorization-Key: ' . $this->apiKey
        ]);
        curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode([$message]));

        $response = curl_exec($ch);
        curl_close($ch);

        $result = json_decode($response, true);
        return $result[0];
    }
}

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

$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']
];

$result = $cascade->sendWithVariables(
    'order-notification',
    'YourStore',
    '+380XXXXXXXXX',
    'transaction',
    'Hi %name=1%! Order %name=2% shipped. Track: %url=3%',
    $variables
);

echo "Message sent: " . $result['messageId'] . "\n";

Các phương pháp hay nhất

ID biến

• ✅ Sử dụng ID tuần tự (1, 2, 3, ...)
• ✅ Tái sử dụng ID cho các tin nhắn hàng loạt có cùng biến
• ✅ Ánh xạ ID biến tài liệu
• ❌ Không sử dụng ID ngẫu nhiên
• ❌ Đừng bỏ qua số CMND

Giá trị biến

• ✅ Xác thực giá trị trước khi tải lên
• ✅ Xử lý đúng ký tự đặc biệt
• ✅ Thử nghiệm với các trường hợp cạnh
• ❌ Không đưa HTML vào biến tên
• ❌ Không vượt quá giới hạn độ dài hợp lý

Biến URL

• ✅ Sử dụng short_url cho URL dài
• ✅ Bao gồm các thông số theo dõi
• ✅ Sử dụng HTTPS
• ❌ Không sử dụng các URL có vẻ đáng ngờ
• ❌ Không đưa dữ liệu nhạy cảm vào URL

Hiệu suất

• Tải biến một lần, gửi nhiều tin nhắn
• Tải lên biến hàng loạt
• Cache các biến thường được sử dụng
• Dọn dẹp các biến cũ định kỳ

Mẫu nâng cao

Cá nhân hóa hàng loạt

async function sendBulkPersonalized(recipients) {
  const messages = [];
  const variables = [];
  let varId = 1;

  recipients.forEach((recipient, index) => {
    // Variables for this recipient
    const nameVarId = varId++;
    const orderVarId = varId++;
    const urlVarId = varId++;

    variables.push(
      { id: nameVarId, type: 'name', value: recipient.name },
      { id: orderVarId, type: 'name', value: recipient.orderId },
      { id: urlVarId, type: 'url', value: recipient.trackingUrl }
    );

    messages.push({
      id: `order-${recipient.orderId}`,
      fromName: 'YourStore',
      toPhone: recipient.phone,
      messageType: 'transaction',
      text: `Hi %name=${nameVarId}%! Order %name=${orderVarId}% shipped. Track: %url=${urlVarId}%`
    });
  });

  // Upload all variables
  await uploadVariables(variables);

  // Send all messages
  return await sendBulk(messages);
}

Hệ thống mẫu

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

Khắc phục sự cố

Biến không được thay thế

• Xác minh các biến đã được tải lên trước khi gửi
• Kiểm tra sự trùng khớp ID biến trong văn bản và tải lên
• Đảm bảo đúng cú pháp: %type=id%
• Xác thực loại biến phù hợp với giá trị

Rút ngắn URL không thành công

• Kiểm tra URL hợp lệ và có thể truy cập được
• Xác minh URL bắt đầu bằng http:// hoặc https://
• Đảm bảo URL chưa bị rút ngắn
• Hãy thử sử dụng url thay vì short_url

Đã vượt quá giới hạn biến

• Liên hệ hỗ trợ về giới hạn thay đổi
• Tái sử dụng ID biến khi có thể
• Dọn dẹp các biến cũ
• Tối ưu hóa việc sử dụng biến

Các bước tiếp theo

• Gửi tin nhắn - Gửi tin nhắn theo tầng
• Loại tin nhắn - Khám phá các loại tin nhắn
• API SMSBAT - Tìm hiểu về API SMSBAT