Expand a method to see parameters and responses.

POST Send message(s) to multiple lists as well as personalised messages in batch mode If you need to send 1 message to a list of numbers, then use the ‘message_type’: ‘bulk’ parameter as… /api/v1/sendBulkViber
Request URL
POST https://app.sms.by/api/v1/sendBulkViber
If you need to send 1 message to a list of numbers, then use the ‘message_type’: ‘bulk’ parameter as in the example below, passing an array of numbers:
'delivery_list': [
    '375291111111',
    '375292222222',
 ]

If you need to send each message to a different phone number, then use ‘message_type’: ‘personal’, passing the message text and phone number each time. For example:
'delivery_list': [
    {
       'phone': '375291111111',
       'text': 'personal message 1'
    },
    {
       'phone': '375292222222',
       'text': 'personal message 2'
    } 
]
To schedule a mailing, you can specify the time of the mailing via the schedule_time parameter, in the format YYYY-MM-DDTHH:mm:ss

The peculiarity of sending a Viber message is the availability of three options: text, image or button.
The filling options are given in the sample api request.

Attention!

The image option can only be used in a mailing with message_type = bulk.
In the button variant, the button_link parameter must not exceed 150 characters.
The image_url parameter in the button and image variants must have a link to an image that is publicly available.

Sample api request
{
  "token": "eyJpdiI6IjJzOFlFcXBmOUZEcGJlYzlzeFJValE9PSIsInZhbHV",
  "callback_url": "http://example-site.com/webhook.php",
  "messages": [
    {
      "alphaname_id": "444",
      "name": "mailing list 1",
      "message_type": "personal",
      "schedule_time": "2024-10-30T22:56:00",
      "content": {
        "type": "button",
        "image_url": "https://example-site.com/images/image.jpg",
        "caption": "Push me"
      },
      "delivery_list": [
        {
          "phone": "375291111111",
          "text": "personal message 1.1",
          "button_link": "https://example-site.com/some_action/1"
        },
        {
          "phone": "375292222222",
          "text": "personal message 1.2",
          "button_link": "https://example-site.com/some_action/2"
        }
      ]
    },
    {
      "alphaname_id": "444",
      "name": "mailing list 2",
      "message_type": "personal",
      "schedule_time": "2024-10-30T22:56:00",
      "content": {
        "type": "text"
      },
      "delivery_list": [
        {
          "phone": "375291111111",
          "text": "personal message 2.1"
        },
        {
          "phone": "375292222222",
          "text": "personal message 2.2"
        }
      ]
    },
    {
      "alphaname_id": "444",
      "name": "mailing list 3",
      "message_type": "bulk",
      "schedule_time": "2024-10-30T22:56:00",
      "content": {
        "type": "button",
        "image_url": "https://example-site.com/images/image.jpg",
        "button_link": "https://example-site.com/some_action",
        "caption": "Button",
        "text": "message text 3"
      },
      "delivery_list": [
        "375291111111",
        "375292222222"
      ]
    },
    {
      "alphaname_id": "444",
      "name": "mailing list 4",
      "message_type": "bulk",
      "schedule_time": "2024-10-30T22:56:00",
      "content": {
        "type": "text",
        "text": "message text 4"
      },
      "delivery_list": [
        "375291111111",
        "375292222222"
      ]
    },
    {
      "alphaname_id": "444",
      "name": "mailing list 5",
      "message_type": "bulk",
      "schedule_time": "2024-10-30T22:56:00",
      "content": {
        "type": "image",
        "image_url": "https://example-site.com/images/image.jpg"
      },
      "delivery_list": [
        "375291111111",
        "375292222222"
      ]
    }
  ]
}

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
callback_url query string No URL to which (if the parameter is set) the response on the method operation in asynchronous mode will be sent
messages query array Yes Message array (Sample object in the request description)

Responses

200 — Completed successfully

{
    "uuid": "cc9c8043-8caf-11ef-b035-9e8f47954dec",
    "success": "OK"
}

400 — Invalid request

404 — Page not found

429 — Request limit exceeded

500 — Server unavailable

POST Getting message statuses from mailing lists created by sendBulkViber method To get information about the mailings created by the sendBulkViber method, you need to use the uuid … /api/v1/statusBulkViber
Request URL
POST https://app.sms.by/api/v1/statusBulkViber
To get information about the mailings created by the sendBulkViber method, you need to use the uuid field from the sendBulkViber method response (this is the UUID of the request). The statusBulkViber method will return extended information about message statuses and errors, if any

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
uuid query string Yes UUID received in the response of the sendBulkSms method

Responses

200 — Completed successfully

[
    {
        "message_id": 1,
        "name": "mailing list 1",
        "alphaname_id": 123,
        "success": [
            {
                "delivery_id": 1001,
                "phone": "375291111111",
                "status": "NEW",
                "status_time": "2024-10-16 22:52:42.497994"
            },
            {
                "delivery_id": 1002,
                "phone": "375292222222",
                "status": "NEW",
                "status_time": "2024-10-16 22:52:43.379779"
            }
        ]
    },
    {
        "message_id": 2,
        "name": "mailing list 2",
        "alphaname_id": 345,
        "success": [
            {
                "delivery_id": 1003,
                "phone": "375293333333",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:44.793377"
            },
            {
                "delivery_id": 1004,
                "phone": "375294444444",
                "status": "DELIVERED",
                "status_time": "2024-10-16 22:52:43.008560"
            }
        ]
    },
    {
        "errors": [
            "mailing list 3: Content url is not valid"
        ]
    },
    {
        "errors": [
            "mailing list 4: Optimal image size 800x800 px"
        ]
    }
]

400 — Invalid request

404 — Page not found

429 — Request limit exceeded

500 — Server unavailable

POST Sending a single Viber message (does not require pre-creation) /api/v2/sendQuickViberMessage
Request URL
POST https://app.sms.by/api/v2/sendQuickViberMessage

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
vibername_id formData integer Yes Viber name ID from the getVibernames method
phone formData string Yes Phone number for Viber message
type_message formData string No Message type: TEXT, IMAGE or BUTTON, default = TEXT
message formData string No Viber message text (required if type_message = TEXT)
image_url formData string No The image being transmitted (required if type_message = IMAGE and image is not passed). Transferring an image via image_url is preferable.
image formData file No The image being transmitted (required if type_message = IMAGE and image_url is not passed)
button formData string No Button name (required if type_message = BUTTON)
button_link formData string No Link for transition (required if type_message = BUTTON)
forwarding_message formData integer No Enable forwarding (1 - enable, 0 - do not enable). If the sent message does not receive the “Delivered” status within the specified time, it will be sent as SMS
forwarding_time formData integer No After how many minutes the forwarding will take place if it is enabled. The default is 60 minutes. Minimum 5 minutes. Maximum 60 minutes
alphaname_id formData integer No ID of the alphaname from which the SMS will be received during forwarding, if it is enabled

Responses

200 — 

{
    "status": "OK",
    "result": {
        "message_id": 8484
    }
}
POST Getting data about a message sent by the sendQuickViberMessage method /api/v2/getViberDeliveryData
Request URL
POST https://app.sms.by/api/v2/getViberDeliveryData

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
message_id formData integer Yes Message ID

Responses

200 — 

{
    "status": "OK",
    "result": {
        "phone": "375293332211",
        "status": "READ",
        "error_code": 0
    }
}
POST Sending a Viber message to the selected mailing list /api/v2/sendViberMessageList
Request URL
POST https://app.sms.by/api/v2/sendViberMessageList

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
name formData string No The name of the mailing list, if the parameter is not passed, the name will be generated automatically
vibername_id formData integer Yes Viber name ID from the getVibernames method
list_id formData integer Yes Mailing list ID from the getSubscriberLists method
type_message formData string No Message type: TEXT, IMAGE or BUTTON, default = TEXT
message formData string No Viber message text (required if type_message = TEXT)
image_url formData string No The image being transmitted (required if type_message = IMAGE and image is not passed). Transferring an image via image_url is preferable.
image formData file No The image being transmitted (required if type_message = IMAGE and image_url is not passed)
button formData string No Button name (required if type_message = BUTTON)
button_link formData string No Link for transition (required if type_message = BUTTON)
d_schedule formData string No Message sending time, indicated in the format 'YYYY-MM-DD HH:MM'

Responses

200 — 

{
    "status": "OK",
    "result": {
        "message_id": 4905,
        "count_subscribers": 4
    }
}
POST Confirm Viber mailing. Money will be debited from your balance. /api/v2/confirmViberMessage
Request URL
POST https://app.sms.by/api/v2/confirmViberMessage

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message_id formData integer Yes Viber mailing list ID

Responses

200 — 

{
    "status": "OK"
}
POST Get a list of your Viber mailings /api/v2/getViberMessages
Request URL
POST https://app.sms.by/api/v2/getViberMessages

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
limit_offset formData integer No Sample offset, default 0
limit_rows formData integer No Number of elements in the selection, default 100

Responses

200 — 

{
    "status": "OK",
    "result": [
        {
            "message_id": 8483,
            "message_type": "TEXT",
            "message": "Test message",
            "button_caption": "",
            "button_link": "",
            "image_file": "",
            "status": "SENT",
            "d_create": "2024-02-01 10:10:35",
            "d_schedule": "2024-02-01 10:10:35",
            "cost": "0.04900 EUR"
        },
        {
            "message_id": 8495,
            "message_type": "BUTTON",
            "message": "",
            "button_caption": "Go to site",
            "button_link": "https:\/\/site.by",
            "image_file": "",
            "status": "SENT",
            "d_create": "2024-02-02 09:30:00",
            "d_schedule": "2024-02-03 10:00:00",
            "cost": "0.04900 EUR"
        }
    ]
}
POST Get Viber mailing data /api/v2/getViberMessageData
Request URL
POST https://app.sms.by/api/v2/getViberMessageData

Parameters

Parameter Location Type Required Description
token query string Yes Your API key
message_id formData integer Yes Viber mailing list ID

Responses

200 — 

{
    "status": "OK",
    "result": {
        "message_id": 8483,
        "message_type": "TEXT",
        "message": "Test message",
        "button_caption": "",
        "button_link": "",
        "image_file": "",
        "status": "SENT",
        "d_create": "2024-02-01 10:10:35",
        "d_schedule": "2024-02-01 10:10:35",
        "cost": "0.04900 EUR"
    }
}
POST Getting a list of phones by Viber mailing list ID /api/v2/getViberDeliveryList
Request URL
POST https://app.sms.by/api/v2/getViberDeliveryList

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
message_id formData integer Yes Viber mailing list ID

Responses

200 — 

{
    "status": "OK",
    "result": [
        {
            "delivery_id": 100,
            "phone": "375293332211",
            "status": "DELIVERED",
            "error_code": 0
        },
        {
            "delivery_id": 101,
            "phone": "375293332212",
            "status": "READ",
            "error_code": 0
        }
    ]
}
POST Viewing incoming messages for Viber mailing /api/v2/getNewIncomingMessages
Request URL
POST https://app.sms.by/api/v2/getNewIncomingMessages

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
message_id formData integer Yes Viber mailing list ID

Responses

200 — 

{
    "status": "OK",
    "result": [
        {
            "id": "1234",
            "phone": "375293332211",
            "message": "Reply to received message",
            "d_receiver": "2022-09-01 10:39:45"
        },
        {
            "id": "1236",
            "phone": "375293332212",
            "message": "Yes",
            "d_receiver": "2022-09-01 11:29:50"
        }
    ]
}
POST Mark the listed incoming messages as read /api/v2/readResponseStatus
Request URL
POST https://app.sms.by/api/v2/readResponseStatus

Parameters

Parameter Location Type Required Description
token formData string Yes Your API key
incoming_messages formData string Yes Comma separated IDs of incoming messages to mark as read

Responses

200 — 

{
    "status": "OK",
    "result": "Number of flagged messages: 3"
}