Messagio API Compatibility

SMSBAT supports a compatibility layer with the Messagio API. This allows you to migrate your existing Viber integrations designed for Messagio directly to SMSBAT without having to rewrite your payload structure or change integration logic.

Connection Settings

To route requests through SMSBAT, update the base URL and authentication credentials in your integration:

Base URL: https://restapi.smsbat.com
Endpoint: POST /api/SendMessage
Request Format: application/x-www-form-urlencoded (Form Data)

Authentication & Credentials

Requests are authenticated using parameters sent directly within the request body form data:

Parameter	Type	Required	Description
`user`	string	Yes	Your SMSBAT account login or user identifier.
`sign`	string	Yes	API secret or signature registered for the sender name.
`from`	string	Yes	Registered sender alpha name.
`sending_method`	string	Yes	Channel type. Use `viber` for regular Viber Business messages or `viber_otp` for Viber OTP templates.
`phone`	string	Yes	Recipient phone number in international format (e.g., `380501234567`).

Viber Message Types

Choose a tab below to view the specific parameters and request payloads for different Viber message structures:

Text MessageText + ButtonImage MessageText + Image + ButtonVideo MessageOTP TemplateCarousel MessageSurvey Message

Sends a simple text message.

Additional Parameters:

Parameter	Type	Required	Description
`txt`	string	Yes	Message text.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hello+from+SMSBAT%21

Sends a text message with an interactive call-to-action button.

Additional Parameters:

Parameter	Type	Required	Description
`txt`	string	Yes	Message text.
`button_text`	string	Yes	Text displayed on the button.
`button_link`	string	Yes	Destination URL when the button is clicked.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Check+our+latest+offers%21&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Sends a public image file.

Additional Parameters:

Parameter	Type	Required	Description
`image_link`	string	Yes	Public HTTPS URL of the image.
`txt`	string	No	Optional caption text to display below the image.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png

Sends a rich card containing text, an image, and a button.

Additional Parameters:

Parameter	Type	Required	Description
`txt`	string	Yes	Caption text.
`image_link`	string	Yes	Public HTTPS URL of the image.
`button_text`	string	Yes	Text displayed on the button.
`button_link`	string	Yes	Destination URL when the button is clicked.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Hot+deals+inside%21&image_link=https%3A%2F%2Fwww.example.com%2Fimage.png&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Sends a video file with an optional text caption and action buttons.

Additional Parameters:

Parameter	Type	Required	Description
`video.url`	string	Yes	Public HTTPS URL of the video file.
`video.thumbnail`	string	Yes	Public HTTPS URL of the video preview image.
`video.size_mb`	integer	Yes	Approximate video file size in Megabytes.
`video.duration_sec`	integer	Yes	Video duration in seconds.
`txt`	string	No	Optional description text.
`button_text`	string	No	Optional button text (can act as a caption or link).
`button_link`	string	No	Optional button link URL.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Watch+this+tutorial%21&video.url=https%3A%2F%2Fwww.example.com%2Fvideo.mp4&video.thumbnail=https%3A%2F%2Fwww.example.com%2Fvideo-thumbnail.png&video.size_mb=1&video.duration_sec=3&button_text=Open&button_link=https%3A%2F%2Fwww.example.com

Sends Viber One-Time Passwords (OTP) using a pre-approved template.

Note

When sending OTP messages, you must set sending_method to viber_otp.

Additional Parameters:

Parameter	Type	Required	Description
`template.id`	string	Yes	Pre-approved Viber OTP template ID.
`template.lang`	string	Yes	Template language code (e.g., `en`, `uk`).
`template.params.pin`	string	Yes	The OTP pin value to inject into the template.
`template.params.business_platform_name`	string	Yes	The business name placeholder in the template.
`template.params.code_validity_time`	string	Yes	PIN validity period in minutes.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber_otp&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&template.id=otp_template_123&template.lang=en&template.params.pin=123456&template.params.business_platform_name=SMSBAT&template.params.code_validity_time=7

Sends an interactive message card containing multiple slides (cards) that the user can swipe through.

Additional Parameters:

Parameter	Type	Required	Description
`txt`	string	Yes	Title text of the carousel.
`carousel[N].title`	string	Yes	Title of card `N` (starting at 0).
`carousel[N].image_url`	string	Yes	Public HTTPS image URL of card `N`.
`carousel[N].primary_label`	string	Yes	Main button caption of card `N`.
`carousel[N].primary_url`	string	Yes	Main button link URL of card `N`.
`carousel[N].secondary_label`	string	No	Secondary button caption of card `N`.
`carousel[N].secondary_url`	string	No	Secondary button link URL of card `N`.

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Top+picks+for+you&carousel%5B0%5D.title=First+Offer&carousel%5B0%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-1.png&carousel%5B0%5D.primary_label=Open&carousel%5B0%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-1&carousel%5B0%5D.secondary_label=Details&carousel%5B0%5D.secondary_url=https%3A%2F%2Fwww.example.com%2Fitem-1%2Fdetails&carousel%5B1%5D.title=Second+Offer&carousel%5B1%5D.image_url=https%3A%2F%2Fwww.example.com%2Fitem-2.png&carousel%5B1%5D.primary_label=Open&carousel%5B1%5D.primary_url=https%3A%2F%2Fwww.example.com%2Fitem-2

Sends a message containing an interactive poll or survey question.

Additional Parameters:

Parameter	Type	Required	Description
`txt`	string	Yes	Survey question text.
`survey_options[N]`	string	Yes	Survey option text for item `N` (index starting at 0). At least 2 options are required.
`option_type`	integer	Yes	Type of selector: `1` (RadioButtons) or `2` (regular Buttons).

Request Payload Example:

POST /api/SendMessage HTTP/1.1
Host: restapi.smsbat.com
Content-Type: application/x-www-form-urlencoded

sending_method=viber&from=MySender&user=myuser&phone=380501234567&sign=api_secret_signature&txt=Please+rate+our+service&survey_options%5B0%5D=Excellent&survey_options%5B1%5D=Good&survey_options%5B2%5D=Average&option_type=1

Response Format

The Messagio API compatibility endpoint returns responses in XML format with an HTTP 200 OK status code.

Accepted (Success) Response

<response>
  <code>0</code>
  <tech_message>OK</tech_message>
  <msg_id phone="380501234567">MESSAGE_GUID</msg_id>
</response>

Error Responses

If a request parameters validation fails or authentication fails, the response will return a non-zero code.

Missing SignatureUnauthorized

<response>
  <code>-1</code>
  <tech_message>PARAM ERROR (sign)</tech_message>
</response>

<response>
  <code>-2</code>
  <tech_message>ERROR(unauthorized)</tech_message>
</response>

Callbacks

Callback URLs must be implemented and hosted on your platform. SMSBAT sends HTTP callbacks to update your system regarding delivery events, survey responses, and user replies.

1. Delivery Status Callback

Sent when a message transitions status (delivered, read, failed).

Content-Type: application/x-www-form-urlencoded
Method: POST

Request Payload Formats:

Delivered:
```
msg_id=MESSAGE_GUID&status=delivered
```

Seen/Read:

msg_id=MESSAGE_GUID&status=delivered&type=seen

Undelivered / Failed:

msg_id=MESSAGE_GUID&status=undelivered&status_extended=REASON

Fields Description:

msg_id: SMSBAT unique message ID (GUID) returned in the SendMessage response.
status: Delivery outcome (delivered, undelivered, or status unknown).
type: Set to seen when the message has been viewed by the recipient.
status_extended: Specific technical reason for undelivered status (e.g. VIBER_EXPIRED, VIBER_BLOCKED_BY_USER, VIBER_USER_NOT_FOUND, VIBER_NO_DEVICE).

2. Survey Answer Callback

Triggered when a user selects a response option in a Viber Survey message.

Content-Type: application/x-www-form-urlencoded
Method: POST

Request Payload Format:

msg_id=ORIGINAL_SURVEY_MESSAGE_GUID&text=SELECTED_OPTION_TEXT

3. Inbound User Message Callback

Triggered when a user sends a text or media reply back to your Viber Business service.

Content-Type: application/json
Method: POST

Request Payload Format:

{
  "msg_id": "INBOUND_MESSAGE_GUID",
  "text": "Hello, I have a question",
  "media": "https://example.com/user-attachment.png",
  "phone": "380501234567",
  "sender_bm_id": "12345"
}

Fields Description:

msg_id: The unique message ID generated for the inbound reply.
text: Text content sent by the user (can be null if they sent media only).
media: Direct URL to download any media attachments sent by the user (can be null if text only).
phone: Sender's phone number in international format.
sender_bm_id: The Viber Business sender ID.