שלח הודעות אשד

שלח הודעות על פני ערוצים מרובים עם בקשת API אחת. Cascade מנתב אוטומטית את ההודעה שלך דרך Telegram Bot, Viber Bot, Viber Business Messages, RCS ו-SMS.

נקודות קצה

אשד סטנדרטי

POST /api/CascadeMessage/send_message/async

מנתב הודעות בכל הערוצים הזמינים ברצף.

עדיפות טלגרם-Viber

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

נותן עדיפות לערוצי טלגרם וויבר לאספקה מהירה יותר.

אימות

Cascade API תומך בשלוש כותרות אימות. כלול לפחות אחד:

כותרת	תיאור
X-Authorization-Key	מפתח API של SMSBAT (מומלץ)
X-Viber-Auth-Token	אישורי בוט Viber
X-Tg-Bot-Key	מפתח בוט טלגרם

מבנה הבקשה

כותרות

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

גוף הבקשה

שלח מערך של אובייקטי הודעה:

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

פרמטרים

פרמטר	הקלד	חובה	תיאור
מזהה	מחרוזת	כן	מזהה המעקב שלך
fromName	מחרוזת	כן	שם תצוגה של השולח
toPhone	מחרוזת	כן	מספר טלפון של הנמען (פורמט E.164)
messageType	מחרוזת	כן	סוג הודעה: עסקה, פרומו, viber_survey, flashcall
טקסט	מחרוזת	כן*	תוכן ההודעה (* נדרש עבור רוב הסוגים)
ttl	מספר שלם	לא	זמן לחיות בשניות
מתזמן נשלח	מחרוזת	לא	ISO 8601 תאריך ושעה למשלוח מתוכנן

סוגי הודעות

הודעות עסקה

התראות קריטיות כמו אישורי הזמנה ועדכוני חשבון:

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

הודעות קידום

קמפיינים שיווקיים עם מדיה עשירה:

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

סקרים אינטראקטיביים עם 2-5 אפשרויות תגובה:

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

טקסט סקר מקסימום: 85 תווים

שיחת הבזק

אימות טלפוני באמצעות שיחה אוטומטית:

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

דוגמאות

עסקה בסיסית

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

קידום מתוזמן

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

הודעות בכמות גדולה

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

תגובה

תגובת הצלחה

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

שדות תגובה

שדה	הקלד	תיאור
messageId	מחרוזת (UUID)	מזהה הודעת מערכת
trackinId	מחרוזת	מזהה המעקב שלך (מבקשה)

השתמש ב-'messageId' למעקב אחר סטטוס וב-'trackinId' לתיאום עם המערכת שלך.

דוגמאות ליישום

פייתון

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

שיטות עבודה מומלצות

מספרי טלפון

השתמש תמיד בפורמט E.164: - ✅ +380XXXXXXXXX - ❌ 380XXXXXXXXX - ❌ 0XXXXXXXXX

מזהי מעקב

• השתמש במזהים ייחודיים עבור כל הודעה
• כלול הקשר במזהה (לדוגמה, order-12345, promo-summer-2025)
• שמור על תעודות זהות מתחת ל-255 תווים
• הימנע מתווים מיוחדים

TTL (זמן לחיות)

ערכי TTL מומלצים:

• OTP/אימות: 300-600 שניות (5-10 דקות)
• עסקאות: 3600-86400 שניות (1-24 שעות)
• קידום מכירות: 86400-259200 שניות (1-3 ימים)
• סקרים: 604800 שניות (7 ימים)

הודעות מתוזמנות

• השתמש באזור זמן UTC עבור scheduledSent
• אין לתזמן יותר מ-30 יום מראש
• חשבו על הבדלי אזורי זמן
• תחילה בדוק עם לוחות זמנים קרובים לעתיד

שליחה בכמות גדולה

• שלח בקבוצות של 100-1000 הודעות
• יישום הגבלת שיעור
• טפל בשגיאות בחן
• נסה שוב הודעות שנכשלו

טיפול בשגיאות

קודי מצב HTTP

קוד	תיאור
200	הצלחה
400	בקשה שגויה - פרמטרים לא חוקיים
401	לא מורשה - מפתח API לא חוקי
429	יותר מדי בקשות
500	שגיאת שרת

תגובת שגיאה

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

נסה שוב לוגיקה

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

השלבים הבאים

• משתני הודעה - השתמש בתוכן דינמי
• סוגי הודעות - חקור סוגי הודעות
• סטטוס משלוח - עקוב אחר משלוח