Siųsti kaskadinius pranešimus

Siųskite pranešimus keliais kanalais naudodami vieną API užklausą. „Cascade“ automatiškai nukreipia jūsų pranešimą per „Telegram Bot“, „Viber Bot“, „Viber Business Messages“, RCS ir SMS.

Galiniai taškai

Standartinė kaskada

POST /api/CascadeMessage/send_message/async

Iš eilės nukreipia pranešimus visais prieinamais kanalais.

Telegram-Viber prioritetas

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

Pirmenybę teikia Telegram ir Viber kanalams, kad pristatymas būtų greitesnis.

Autentifikavimas

Kaskados API palaiko tris autentifikavimo antraštes. Įtraukite bent vieną:

Antraštė	Aprašymas
"X-autorizacijos raktas"	SMSBAT API raktas (rekomenduojamas)
„X-Viber-Auth-Token“	Viber bot kredencialai
„X-Tg-Bot-Key“	Telegramos roboto raktas

Užklausos struktūra

Antraštės

Content-Type: application/json
X-Authorization-Key: your-smsbat-api-key
X-Viber-Auth-Token: your-viber-token
X-Tg-Bot-Key: your-telegram-key

Užklausos įstaiga

Siųsti pranešimų objektų masyvą:

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

Parametrai

Parametras	Tipas	Reikalingas	Aprašymas
"id"	styga	Taip	Jūsų stebėjimo identifikatorius
„nuo Vardo“	styga	Taip	Siuntėjo rodomas vardas
"į telefoną"	styga	Taip	Gavėjo telefono numeris (E.164 formatas)
messageType	styga	Taip	Pranešimo tipas: „transaction“, „promo“, „viber_survey“, „flashcall“
"tekstas"	styga	Taip*	Pranešimo turinys (* reikalingas daugeliui tipų)
ttl	sveikasis skaičius	Ne	Laikas gyventi sekundėmis
suplanuotas išsiųstas	styga	Ne	ISO 8601 data ir laikas numatytam pristatymui

Pranešimų tipai

Operacijų pranešimai

Svarbūs pranešimai, pvz., užsakymų patvirtinimai ir paskyros atnaujinimai:

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

Reklaminiai pranešimai

Rinkodaros kampanijos su raiškiąja medija:

{
  "id": "promo-summer-sale",
  "fromName": "YourBrand",
  "toPhone": "+380XXXXXXXXX",
  "messageType": "promo",
  "text": "Summer Sale! Up to 50% off. Shop now: https://example.com/sale",
  "ttl": 259200
}

Viber apklausa

Interaktyvios apklausos su 2–5 atsakymų variantais:

{
  "id": "survey-satisfaction",
  "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
}

Maksimalus apklausos tekstas: 85 simboliai

Flash skambutis

Telefono patvirtinimas automatiniu skambučiu:

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

Pavyzdžiai

Pagrindinė operacija

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

Suplanuota akcija

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
    }
  ]'

Masiniai pranešimai

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

Atsakymas

Sėkmės atsakas

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

Atsakymo laukai

Laukas	Tipas	Aprašymas
messageId	eilutė (UUID)	Sistemos pranešimo identifikatorius
„trackinId“	styga	Jūsų stebėjimo identifikatorius (iš užklausos)

Naudokite „messageId“ būsenai stebėti ir „trackinId“, kad susietumėte su sistema.

Įgyvendinimo pavyzdžiai

Python

import requests
from datetime import datetime, timedelta

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

    def send_message(self, tracking_id, from_name, to_phone,
                     message_type, text, ttl=None, scheduled=None):
        """Send single cascade message"""
        message = {
            'id': tracking_id,
            'fromName': from_name,
            'toPhone': to_phone,
            'messageType': message_type,
            'text': text
        }

        if ttl:
            message['ttl'] = ttl

        if scheduled:
            message['scheduledSent'] = scheduled.isoformat()

        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]

    def send_bulk(self, messages):
        """Send multiple messages"""
        response = requests.post(
            f'{self.base_url}/api/CascadeMessage/send_message/async',
            headers=self.headers,
            json=messages
        )

        response.raise_for_status()
        return response.json()

# Usage
messenger = CascadeMessenger('your-api-key')

# Send single message
result = messenger.send_message(
    tracking_id='order-12345',
    from_name='YourStore',
    to_phone='+380XXXXXXXXX',
    message_type='transaction',
    text='Your order has been confirmed',
    ttl=86400
)

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

# Send scheduled message
scheduled_time = datetime.now() + timedelta(hours=2)
result = messenger.send_message(
    tracking_id='promo-001',
    from_name='YourBrand',
    to_phone='+380XXXXXXXXX',
    message_type='promo',
    text='Sale starts now!',
    scheduled=scheduled_time
)

# Bulk send
messages = [
    {
        'id': f'bulk-{i}',
        'fromName': 'YourBrand',
        'toPhone': f'+38011111111{i}',
        'messageType': 'transaction',
        'text': f'Message {i}'
    }
    for i in range(100)
]

results = messenger.send_bulk(messages)
print(f"Sent {len(results)} messages")

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

<?php

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

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

    public function sendMessage($id, $fromName, $toPhone, $messageType,
                                $text, $ttl = null, $scheduledSent = null) {
        $message = [
            'id' => $id,
            'fromName' => $fromName,
            'toPhone' => $toPhone,
            'messageType' => $messageType,
            'text' => $text
        ];

        if ($ttl !== null) {
            $message['ttl'] = $ttl;
        }

        if ($scheduledSent !== null) {
            $message['scheduledSent'] = $scheduledSent;
        }

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

    public function sendBulk($messages) {
        $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($messages));

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

        return json_decode($response, true);
    }
}

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

// Send single message
$result = $messenger->sendMessage(
    'order-12345',
    'YourStore',
    '+380XXXXXXXXX',
    'transaction',
    'Your order has been confirmed',
    86400
);

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

// Bulk send
$messages = [];
for ($i = 0; $i < 100; $i++) {
    $messages[] = [
        'id' => "bulk-$i",
        'fromName' => 'YourBrand',
        'toPhone' => "+38011111111$i",
        'messageType' => 'transaction',
        'text' => "Message $i"
    ];
}

$results = $messenger->sendBulk($messages);
echo "Sent " . count($results) . " messages\n";

Geriausia praktika

Telefono numeriai

Visada naudokite E.164 formatą: - ✅ +380XXXXXXXXX - ❌ "380XXXXXXXXX". - ❌ „0XXXXXXXXX“.

Stebėjimo ID

• Kiekvienam pranešimui naudokite unikalius ID – Į ID įtraukite kontekstą (pvz., „užsakymas-12345“, „promo-summer-2025“) – Išsaugokite ID iki 255 simbolių
• Venkite specialių simbolių

TTL (gyvenimo laikas)

Rekomenduojamos TTL reikšmės:

– VTP / patvirtinimas: 300–600 sekundžių (5–10 minučių) – Sandakcija: 3600–86400 sekundžių (1–24 val.) – Reklama: 86400–259200 sekundžių (1–3 dienos) - Apklausos: 604800 sekundžių (7 dienos)

Suplanuoti pranešimai

– Naudoti UTC laiko juostą „suplanuotai išsiųstai“. - Neplanuokite daugiau nei 30 dienų iš anksto - Atsižvelgti į laiko juostų skirtumus - Pirmiausia išbandykite artimiausius grafikus

Masinis siuntimas

• Siųsti 100-1000 pranešimų paketais
• Įgyvendinimo normos ribojimas
• Grakščiai elkitės su klaidomis
• Bandykite dar kartą išsiųsti nesėkmingus pranešimus

Klaidų tvarkymas

HTTP būsenos kodai

Kodas	Aprašymas
200	Sėkmės
400	Netinkama užklausa – neteisingi parametrai
401	Neteisėta – netinkamas API raktas
429	Per daug užklausų
500	Serverio klaida

Atsakymas į klaidą

{
  "error": {
    "code": "INVALID_PHONE",
    "message": "Invalid phone number format",
    "field": "toPhone"
  }
}

Bandykite dar kartą logiką

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

Kiti žingsniai

– Pranešimo kintamieji – Naudokite dinaminį turinį – Pranešimų tipai – Naršykite pranešimų tipus – Pristatymo būsena – Stebėti pristatymą