Skip to content

SMSBAT RESTful API Guide

Complete guide to the SMSBAT RESTful API – everything you need to know.

Last updated: August 29, 2025

SMSBAT RESTful API allows you to send various message types: Viber-carousel, Viber-survey, Viber-promo (images, video), Viber business chats, OTP messages (Viber OTP, Flash Call), and their fallback variants.

Note: This is the unified HTTP API for outbound messaging. If you need integrations with inbound bots (Viber Bot / Telegram Bot), please refer to the Cascade API.

1. Protocol

  • Protocol: HTTPS
  • Request Body: JSON object containing an array of messages.
  • Methods:
  • GET to fetch data (message status, balance, etc.)
  • POST to create objects (e.g., initiating a broadcast/dispatch)
  • PATCH to modify objects

2. Authorization

We provide several authorization methods for your convenience: - HTTP Basic Authentication (login and password from your dashboard). - Custom HTTP Header X-Authorization-Key containing an API Token. - HTTP Basic Authentication password field holding the API Token (pass @ as the login).

API Token can be generated in the Dashboard under User Profile.

Request Examples

With Basic Auth: 

curl -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist \
  --user user:password

With X-Authorization-Key: 

curl -H "X-Authorization-Key: <token>" \
  -H "Content-Type: application/json" \
  -X POST -d @/path/to/data.json https://api.smsbat.com/bat/messagelist

3. Sending Messages

In the SMSBAT platform, any message dispatch (even a single message) is considered a "Broadcast" (messagelist).

Endpoint - Method: POST - URL: https://api.smsbat.com/bat/messagelist - Headers: Content-Type: application/json

Basic Payload Structure: 

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "text": "Check out our new products!",
      "type": "viber_carousel",
      "ttl": 300,
      "messageData": { ... }
    }
  ]
}

Required Fields for Each Message Object:

  • from: Verified sender alpha-name.
  • to: Recipient phone number (E.164 format).
  • type: Message type enum.
  • text: Main text of the message (optional if the type does not require text).

Supported type Values: - sms - viber_service (or viber_trans) - viber_promo - viber_carousel - viber_survey - viber_otp - viber_session - flashcall_callback - flashcall

Optional Common Fields:

  • customerMessageId: String ID inside your own system (used for tracking callbacks). Must be unique per message.
  • dtSend: ISO8601 Date/Time of scheduled future dispatch.
  • dtExpire: ISO8601 Date/Time of the delivery deadline.
  • ttl: Time-To-Live in seconds. (If dtExpire is not provided, the API calculates defaults mapping from the type).

Default TTLs (Seconds):

  • sms - 86400 (24h)
  • viber_trans / viber_service - 345600
  • viber_promo - 604800
  • viber_session - 604800

4. Fallback Routing (Cascading)

You can specify a fallback queue to ensure message delivery if the primary channel fails or expires.

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380500505051",
      "text": "test message",
      "type": "viber_service",
      "ttl": 60,
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "text": "test sms fallback message2",
          "type": "sms"
        }
      ]
    }
  ]
}
Fallbacks trigger when the provider rejects the main message or when the TTL expires.

5. Overview of Message Types & messageData

Complex message types require additional configurations injected into the messageData property.

5.1 Viber Promo (viber_promo)

Image Only 

"messageData":{
  "img":"https://domain.com/image.png"
}

Text + Button 

"messageData":{
  "buttonText":"Save Now",
  "buttonAction":"https://help.smsbat.com"
}

Image + Text + Button Combines img, buttonText, and buttonAction.

Video Payload: 

"messageData":{
  "video": "https://domain.com/test.mp4",
  "thumbnail": "https://domain.com/carusel.png",
  "fileSize": 12000000,
  "duration": 30
}
(You can also combine Video properties with buttonText and buttonAction).

5.2 Viber Transactional / Service (viber_trans, viber_service)

If you have an approved template containing an attached file: 

"messageData": {
  "fileUrl": "https://domain.com/receipt.pdf",
  "fileName": "Receipt.pdf",
  "fileType": "pdf"
}

Requires a carousel.items array inside messageData.

Limitations: - Items length: between 2 and 5 items - Title: 2 to 38 characters - imageUrl: JPEG/PNG recommended size 215x185

"messageData": {
  "carousel": {
    "items": [
      {
        "title": "50% Off Shoes!",
        "imageUrl": "https://domain.com/image1.png",
        "primaryButton": { "label": "Shop", "actionUrl": "..." },
        "secondaryButton": { "label": "Details", "actionUrl": "..." }
      }
    ]
  }
}

5.4 Viber Survey / List (viber_survey)

Creates an interactive poll within the chat view. 

"messageData": {
  "survey": {
    "options": [
      "Excellent", "Good", "Normal", "Bad", "Terrible"
    ]
  }
}
The text property of the message acts as the survey title (Max 85 chars). You can pass between 2 and 5 options, each max 50 chars.

5.5 Viber OTP (viber_otp)

Uses pre-registered localized Viber templates globally. 

"messageData": {
  "templateId": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
  "templateLang": "uk",
  "templateParams": {
    "pin": "3211",
    "business_platform_name": "SMSBAT",
    "code_validity_time": 7
  }
}
Template parameters (pin, business_platform_name) are strictly case-sensitive. The API supports various ISO code language variants (EN, ES, RU, TR, UK, etc.).

5.6 Flash Call (flashcall)

The last digits of the dialing number (the generated code) must be passed via the text parameter. If text is omitted, the code is randomized and you must extract it from the API's synchronous 200 OK Response body (messages/text).

{
  "from": "FLASHCALL",
  "to": "380500000000",
  "type": "flashcall",
  "text": "340"
}