Skip to content

Viber Messages

SMSBAT API supports multiple types of Viber messages for different use cases, from promotional campaigns to transaction notifications.

Message Types Overview

Type Purpose Rich Media Interactive
viber_promo Marketing campaigns ✅ Images, Videos ✅ Buttons
viber_trans Transactional notifications ✅ PDFs ❌
viber_carousel Product showcases ✅ Images ✅ Multiple buttons
viber_survey Polls and feedback ❌ ✅ Multiple options
viber_otp One-time passwords ❌ ❌

Viber Promo

Promotional messages with rich media support for marketing campaigns.

Supported Content

  • Image only
  • Text only
  • Text + button
  • Image + text + button
  • Video + text
  • Video + text + button
  • Video only

Parameters

Parameter Type Required Description
img string No Image URL
video string No Video file URL
thumbnail string No Video preview image
buttonText string No Call-to-action button label
buttonAction string No Button click URL destination
fileSize integer No Video file size in bytes
duration integer No Video length in seconds

Examples

Text + Image + Button

Text + Image + Button Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Summer Sale! Up to 50% off on selected items.",
  "messageData": {
    "img": "https://example.com/summer-sale.jpg",
    "buttonText": "Shop Now",
    "buttonAction": "https://example.com/sale"
  }
}

Video + Text + Button

Video + Text + Button Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Watch our new product demo!",
  "messageData": {
    "video": "https://example.com/demo.mp4",
    "thumbnail": "https://example.com/thumbnail.jpg",
    "fileSize": 5242880,
    "duration": 30,
    "buttonText": "Learn More",
    "buttonAction": "https://example.com/product"
  }
}

Image Only

Image Only Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "messageData": {
    "img": "https://example.com/banner.jpg"
  }
}

Text Only

Text Only Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Your promo text message"
}

Video Only

Video Only Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "messageData": {
    "video": "https://example.com/demo.mp4",
    "thumbnail": "https://example.com/thumbnail.jpg",
    "fileSize": 5242880,
    "duration": 30
  }
}

Video + Text

Video + Text Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_promo",
  "text": "Watch our new video!",
  "messageData": {
    "video": "https://example.com/demo.mp4",
    "thumbnail": "https://example.com/thumbnail.jpg",
    "fileSize": 5242880,
    "duration": 30
  }
}

Viber Transactional

Transaction notifications for time-sensitive information like order confirmations and receipts.

Supported Content

  • Text only
  • PDF file + text
  • PDF file only

Parameters

Parameter Type Required Description
fileUrl string No PDF document URL
fileName string No Display name for attachment
fileType string No File type (use "pdf")

Examples

Text Only

Text Only Example

{
  "from": "YourStore",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Your order #12345 has been confirmed and will be delivered tomorrow.",
  "ttl": 86400
}

Text + PDF

Text + PDF Example

{
  "from": "YourStore",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "text": "Thank you for your purchase! Please find your invoice attached.",
  "messageData": {
    "fileUrl": "https://example.com/invoice-12345.pdf",
    "fileName": "Invoice_12345.pdf",
    "fileType": "pdf"
  },
  "ttl": 86400
}

PDF Only

PDF Only Example

{
  "from": "YourStore",
  "to": "+380XXXXXXXXX",
  "type": "viber_trans",
  "messageData": {
    "fileUrl": "https://example.com/invoice-12345.pdf",
    "fileName": "Invoice_12345.pdf",
    "fileType": "pdf"
  },
  "ttl": 86400
}

Multi-item browsable showcase for products or content.

Structure

Array of carousel items, each containing:

  • Title
  • Image
  • Primary button (main action)
  • Secondary button (alternative action)

Parameters

Parameter Type Required Description
carousel array Yes Array of carousel items
items array Yes Individual card objects

Example

Viber Carousel Example

{
  "from": "YourStore",
  "to": "+380XXXXXXXXX",
  "type": "viber_carousel",
  "text": "Check out our featured products",
  "messageData": {
    "carousel": {
      "items": [
        {
          "title": "Product A",
          "imageUrl": "https://example.com/product-a.jpg",
          "primaryButton": {
            "text": "Buy Now",
            "url": "https://example.com/product-a"
          },
          "secondaryButton": {
            "text": "Details",
            "url": "https://example.com/product-a/details"
          }
        },
        {
          "title": "Product B",
          "imageUrl": "https://example.com/product-b.jpg",
          "primaryButton": {
            "text": "Buy Now",
            "url": "https://example.com/product-b"
          },
          "secondaryButton": {
            "text": "Details",
            "url": "https://example.com/product-b/details"
          }
        }
      ]
    }
  }
}

Viber Survey

Interactive polls and feedback collection with multiple choice options.

Parameters

Parameter Type Required Description
survey object Yes Survey container
options array Yes Array of 1-5 answer choices

Constraints

  • Maximum 5 response options supported
  • Each option should be concise (recommended: under 30 characters)

Example

Viber Survey Example

{
  "from": "YourBrand",
  "to": "+380XXXXXXXXX",
  "type": "viber_survey",
  "text": "How satisfied are you with our service?",
  "messageData": {
    "survey": {
      "options": [
        "Very Satisfied",
        "Satisfied",
        "Neutral",
        "Dissatisfied",
        "Very Dissatisfied"
      ]
    }
  }
}

Viber OTP

One-time password delivery with pre-defined templates.

Key Features

  • 9 pre-defined templates
  • Parameter validation (TEXT, NUMBER types)
  • Multi-language support (19 languages)
  • Case-sensitive variable names

Supported Languages

Ukrainian, English, Russian, Polish, Romanian, Spanish, German, French, Italian, Portuguese, Dutch, Turkish, Arabic, Hebrew, Hindi, Chinese, Japanese, Korean, Vietnamese

Parameters

Parameter Type Required Description
templateId string (UUID) Yes Template identifier
templateLang string Yes ISO language code
templateParams object Yes Variables matching template

Example

Viber OTP Example

{
  "from": "YourApp",
  "to": "+380XXXXXXXXX",
  "type": "viber_otp",
  "messageData": {
    "templateId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "templateLang": "en",
    "templateParams": {
      "PIN": "123456",
      "TIME": "10"
    }
  },
  "ttl": 600
}

Template example: "Your code: 123456. Valid for 10 minutes. Never share this code."

Supported Templates & Validations

Viber offers predefined and strictly controlled templates. The variables parameters passed must correspond to the correct data types.

Data Types: - NUMBER: Only numerals [0-9], +, -, and .. Symbols like / or whitespace are unsupported. - TEXT: Any language alphabet, symbols (@#$%^&*().,<>;:!\"'+=-()[]{} \n etc). - Regular mapping: A sequence of <letters> cannot exist adjacent to a <number> sequence; they require whitespace separation. Double whitespaces inside templates are generally forbidden. For links, avoid spaces if they exceed limits.

Below are the 9 Standard ISO templates. Replace IDs based on your registration requirements in specific countries. Contact support if adding additional languages.

1. "Code ONLY (Any PIN)"

Requirements: Supports PINs in numerals & English letters, symbols - or .. Template requires formatting to display your brand properly alongside the verification PIN.

2. "Action: Please use this code"

Parameters: {pin} (NUMBER or TEXT) Example format: "Please use this code {pin} for verification."

3. "Brand Registration/Access"

Parameters: {business_platform_name} (TEXT), {pin} (NUMBER or TEXT) Example format: "Your code for {business_platform_name} is {pin}."

4. "Code Validation Timing"

Parameters: {pin} (NUMBER/TEXT), {code_validity_time} (NUMBER) Example format: "Your verification code is {pin}. It is valid for {code_validity_time} minutes."

5. "Brand Access & Code Validation"

Parameters: {business_platform_name} (TEXT), {pin} (NUMBER/TEXT), {code_validity_time} (NUMBER) Example format: "{business_platform_name} verification code is {pin} valid for {code_validity_time} minutes."

(Note: There are up to 9 predefined structural blocks for Viber standard OTP rules based on combinations of the pin, business_platform_name, and code_validity_time usage).

General Requirements

All Viber message types require:

  • from: Alphanumeric sender ID
  • to: Phone number in E.164 format
  • type: Message type identifier
  • ttl: Message expiration time in seconds (recommended)

Fallback to SMS

All Viber message types support SMS fallback utilizing the fallbacks array block. If Viber delivery fails, the message automatically falls back to alternative configured channels.

Viber Promo -> SMS Fallback

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_promo",
      "text": "Your Viber promo message",
      "ttl": 300,
      "messageData": {
        "img": "https://cdn.example.com/image.png",
        "buttonText": "View Offer",
        "buttonAction": "https://example.com"
      },
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "Order #111 is waiting for you in our store",
          "ttl": 5600
        }
      ]
    }
  ]
}

Viber Survey -> SMS Fallback

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_survey",
      "text": "Please share your feedback",
      "ttl": 30,
      "messageData": {
        "survey": {
          "options": [
            "Very Good",
            "Good",
            "Bad"
          ]
        }
      },
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "SMS fallback for the survey"
        }
      ]
    }
  ]
}

Viber Trans -> SMS Fallback

{
  "messages": [
    {
      "from": "ALPHANAME",
      "to": "380936670003",
      "type": "viber_trans",
      "text": "Your account details",
      "ttl": 300,
      "messageData": {},
      "fallbacks": [
        {
          "from": "ALPHANAME",
          "to": "380936670003",
          "type": "sms",
          "text": "SMS fallback for trans message text",
          "ttl": 5600
        }
      ]
    }
  ]
}

Best Practices

Images

  • Use JPG or PNG format
  • Recommended size: 800x600 pixels
  • Keep file size under 1MB
  • Use HTTPS URLs

Videos

  • Use MP4 format
  • Keep file size under 10MB
  • Include thumbnail image
  • Specify duration and fileSize

Buttons

  • Keep button text short (2-3 words)
  • Use clear call-to-action phrases
  • Always use HTTPS URLs
  • Test URLs before sending

TTL (Time-to-Live)

  • Promotional messages: 24-72 hours
  • Transactional messages: 24 hours
  • OTP messages: 5-10 minutes
  • Surveys: 7-30 days

Next Steps