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:
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
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.
<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.
