Odeslat kaskádové zprávy

Odesílejte zprávy přes více kanálů pomocí jediného požadavku API. Cascade automaticky směruje vaši zprávu přes Telegram Bot, Viber Bot, Viber Business Messages, RCS a SMS.

Koncové body

Standardní kaskáda

POST /api/CascadeMessage/send_message/async

Směruje zprávy postupně všemi dostupnými kanály.

Telegram-Viber Priority

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

Upřednostňuje kanály Telegram a Viber pro rychlejší doručení.

Autentizace

Cascade API podporuje tři autentizační hlavičky. Uveďte alespoň jeden:

Záhlaví	Popis
X-Authorization-Key	SMSBAT API klíč (doporučeno)
X-Viber-Auth-Token	Přihlašovací údaje bota Viber
"X-Tg-Bot-Key"	Telegram bot klíč

Struktura požadavku

Záhlaví

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

Tělo požadavku

Odeslat pole objektů zpráv:

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

Parametry

Parametr	Typ	Povinné	Popis
'id'	řetězec	Ano	Váš sledovací identifikátor
od jména	řetězec	Ano	Zobrazované jméno odesílatele
"do telefonu"	řetězec	Ano	Telefonní číslo příjemce (formát E.164)
messageType	řetězec	Ano	Typ zprávy: transaction, promo, viber_survey, flashcall
"text"	řetězec	Ano*	Obsah zprávy (* povinné pro většinu typů)
ttl	celé číslo	Ne	Doba žití v sekundách
plánovánoSent	řetězec	Ne	ISO 8601 datum a čas pro plánovanou dodávku

Typy zpráv

Transakční zprávy

Kritická oznámení, jako jsou potvrzení objednávek a aktualizace účtu:

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

Propagační zprávy

Marketingové kampaně s multimédii:

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

Průzkum Viber

Interaktivní průzkumy s 2–5 možnostmi odpovědi:

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

Maximální délka textu průzkumu: 85 znaků

Bleskový hovor

Telefonické ověření prostřednictvím automatického volání:

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

Příklady

Základní transakce

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

Plánovaná promo akce

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

Hromadné zprávy

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

Odpověď

Úspěšná odpověď

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

Pole odpovědí

Pole	Typ	Popis
ID zprávy	řetězec (UUID)	Identifikátor systémové zprávy
trackinId	řetězec	Váš sledovací identifikátor (z požadavku)

Použijte messageId pro sledování stavu a trackinId pro korelaci s vaším systémem.

Příklady implementace

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

Nejlepší postupy

Telefonní čísla

Vždy používejte formát E.164: - ✅ +380XXXXXXXXX - ❌ 380XXXXXXXXX - ❌ 0XXXXXXXXX

ID sledování

• Pro každou zprávu použijte jedinečné ID – Zahrnout do ID kontext (např. order-12345, promo-summer-2025)
• Udržujte ID kratší než 255 znaků
• Vyhněte se speciálním znakům

TTL (Time-to-Live)

Doporučené hodnoty TTL:

• OTP/ověření: 300–600 sekund (5–10 minut)
• Transakční: 3600–86400 sekund (1–24 hodin) – Propagační: 86 400–259 200 sekund (1–3 dny)
• Průzkumy: 604 800 sekund (7 dní)

Naplánované zprávy

• Použijte časové pásmo UTC pro „scheduledSent“.
• Neplánujte více než 30 dní předem
• Zohledněte rozdíly v časových pásmech
• Nejprve otestujte s plány blízké budoucnosti

Hromadné odesílání

• Odesílejte v dávkách 100-1000 zpráv
• Implementujte omezení rychlosti
• Zvládejte chyby elegantně
• Opakujte neúspěšné zprávy

Zpracování chyb

Stavové kódy HTTP

Kód	Popis
200	Úspěch
400	Špatný požadavek - neplatné parametry
401	Neoprávněný – neplatný klíč API
429	Příliš mnoho požadavků
500	Chyba serveru

Odpověď na chybu

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

Opakujte logiku

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

Další kroky

– Proměnné zprávy – Používejte dynamický obsah – Typy zpráv – Prozkoumejte typy zpráv - Stav doručení - Sledovat doručení