Skip to content

VIBER

Sending

To send Viber messages it is required to:

Request parameters

Parameter Data type Description
shortenUrl
(optional)
boolean

If true, the system converts URLs in the message into shorter links. If user follows the link, the system will send a callback with the CLICKED status.

For example, if the parameter is enabled, the link https://www.example-url.com/my-example-param... will be converted to https://clickdo.integrationapi.net/link-hash.

False by default.

Request body

Parameter Data type Description
messages array[Message] Messages array.

Message

Parameter Data type Description
from string

Sender's name used when sending the message.

Only the senders' names which are available for using by the user can be used.

to string Phone number in international format, according to E.164 standard.
text
(optional)
string

The message text, UTF-8 characters.

The standard number of characters is no more than 1000.
The maximum number of characters is 2000.

If the standard number of characters in a Viber message exceeds 1000 characters, the message will be split into segments, which will be delivered successively, preserving the semantic content.

image
(optional)
string URL for the image in JPG, JPEG or PNG formats.
fileType
(optional)
string

The type of file to send.

The maximum file size is 200 MB. The parameter specifies the file type without a dot - for example, docx, pdf, etc.

You can send the following types of files:

○ Documents: .doc , .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info
○ PDF: .pdf, .xps, .pdax, .eps
○ Tables: . xls, .xlsx, .ods, .fods, .csv, .xlsm, .xltx

fileName
(optional)
string The name of the file, including the extension. For example, yourfile.docx.
thumbnail
(optional)
string Link to video preview in image format.
duration
(optional)
integer Video length in seconds.
fileSize
(optional)
integer The size of the uploaded video in megabytes (MB).
caption
(optional)
string Button text, no more than 30 characters in UTF-8 encoding.
action
(optional)
string

URL or deep link to which the user will go after clicking the button.

The parameter is also used to specify the URL of the attached video or file.

validity
(optional)
integer

Lifetime of the message in seconds.

Minimal value: 15
Maximal value: 1209600, 14 days
Default value: 86400, 1 day

priority
(optional)
string

Message priority level.

LOW and MEDIUM - low and medium priority levels that are used for promotional messages.
HIGH - high priority that is used for service traffic.
REALTIME - maximum possible priority. Use it when you respond to an incoming message from the user.

If any other value is used, the message will be rejected.

scheduledTime
(optional)
string

UTC when the message is to be sent.

Format: YYYY-MM-DD hh:mm:ss

callbackUrl
(optional)
string

The URL to which the system will send notifications about message status changes.

Any valid URL with the HTTP or HTTPS scheme.

options
(optional)
object

An object with the data which will be specified in the callback with the message status.

Any "key" array:
{ "key1": "value1", "key2": "value2" }

To start a session with a user, this object must have the allowUseSessions (bool) parameter specified. If the allowUseSessions parameter is set to true, the system will be able to initiate a session if the other conditions are fulfilled.

Attention

All links to files and images must be used with the HTTPS protocol to display content correctly in the chat.

Possible parameters combinations

Although some request parameters are optional, these parameters form the data types that make up the message inside Viber. You should use at least one of these data types in the request according to the list:

  • Text: text
  • Image: image
  • Text with button: text, caption, action
  • Text with image and button: text, image, caption, action
  • Attached file: fileType, fileName, action
  • Video: thumbnail, duration, fileSize, action
  • Video with text: text, thumbnail, duration, fileSize, action
  • Video with text and button: text, thumbnail, duration, fileSize, caption, action (in this case action will mean the URL of the attached video)

Request examples

{
  "messages": [
    {
        "from": "MyCompany",
        "to": "79034567890",
        "text": "Code: 1234",
        "image": "https://cdn.mycompany.com/viber.png",
        "action": "https://mycompany.com/promo?code=1234",
        "caption": "Activate!"
    }
  ]
}
{ 
  "messages": [
    {
        "from": "MyCompany",
        "to": "79034567890",
        "thumbnail": "https://myvideo.com/thumbnail.jpg",
        "duration": 433,
        "fileSize": 32,
        "action": "https://myvideosource.com/video.mp4"
    }
  ]   
}
{ 
  "messages": [
    {
        "from": "MyCompany",
        "to": "79034567890",
        "fileType": "docx",
        "fileName": "myfile.docx",
        "action": "https://myfilesource.com/myfile.docx"
    }
  ]   
}

Response parameters

Parameter Data type Description
code string

Shows the result of message processing.

1. OK - processed successfully.
2. REJECTED - an error has occurred while processing the request.

messageId
(optional)
string Message ID. To be given with "code": "OK" only.
reasons
(optional)
array An array of the errors that occurred while processing the message. To be given with "code": "REJECTED" only.
reasons.key string Error code.
reasons.ref string Reference to the parameter where the error has occurred.
reasons.defaultMessage string Message with error description.

Response examples

{
  "result": [
    {
      "code": "OK",
      "messageId": "3702436063699518976"
    }
  ]
}
{
  "result": [
    {
      "code": "REJECTED",
      "messageId": null,
      "reasons": [
        {
          "key": "text.image.file.or.video.must.be.not.null",
          "defaultMessage": "#text.image.file.or.video.must.be.not.null; Field text,image,file or video must be not null"
        },
        {
          "key": "illegal.combination",
          "ref": "contentCombinationValid",
          "defaultMessage": "#illegal.combination;"
        }
      ]
    }
  ]
}

Incoming messages

How to enable

To enable incoming messages from users, contact your account manager or technical support. You will also need to provide the URL of a web-server for processing incoming messages.

Parameters

Parameter Data type Description
incomingMessageId long Incoming message ID.
to string Recipient's address.
from string Sender's phone number.
text string Message text.
contentUrl string Link to the file, attached to the message. It is generated inside Viber and valid for 7 days.
contentName string Name of the file, attached to the message.
ts long Time of the receipt of the message (timestamp) in milliseconds.

Examples

{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "text": "Incoming message",
  "ts": "1587721283000"
}
{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "contentUrl": "https://dl-media.viber.com/20/media/42.pdf",
  "contentName": "userfile.pdf",
  "ts": "1587721283000"
}
{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "contentUrl": "https://dl-media.viber.com/18/media/234.mp4",
  "contentName": "uservideo.mp4",
  "ts": "1587721283000"
}

Sessions

Sessions in Viber allow you to communicate with users at a fixed price for a certain time and number of messages.

To open a session, two conditions must be fulfilled:

  1. Messages of the text or image types were sent to the user.
  2. When sending a message, the options object contains the parameter "allowUseSessions" = true.
  3. The user sent an incoming message.

To end a session, one of three conditions must be fulfilled:

  1. 24 hours have passed since the session started.
  2. More than 10 messages were sent to the user in a row.
  3. More than 60 messages were sent to the user within one session.

Callbacks

How to enable

To set up callbacks with message statuses, please contact your account manager or technical support.

Possible statuses

Code Description
ACCEPTED The message was accepted for delivery.
SCHEDULED The message has been scheduled.
ENROUTE The message is in the queue for sending.
SENT The message has been sent to the operator network.
DELIVERED The message has been delivered to the user.
EXPIRED The lifetime of the message has expired.
UNDELIVERABLE Unable to deliver the message.
SEEN The message has been read.
CLICKED The link in the message has been followed.
DELETED The message has been deleted.
REJECTED The message has been rejected by the Viber or Devino.Online.
UNKNOWN An unknown error has occurred.
SUBSCRIBED The user has subscribed.
UNSUBSCRIBED The user has unsubscribed.

Callback examples

[
  {
    "messageId": "3597958273915257088",
    "ts": 1613411223173,
    "status": "DELIVERED",
    "errorCode": 0
  }
]
[
  {
    "messageId": "3597958273915257088",
    "ts": 1613411223173,
    "status": "REJECTED",
    "errorCode": 2012
  }
]

Details

To get the sent messages detailed information, you need to call GET /viber-stat/statistics/detail, sending filter parameters with the authorization data in the header.

Request parameters

Parameter Data type Description
limit integer The number of messages in the search results.
offset integer Search results offset. For example, if the number 5 is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
taskId
(optional)
integer Message campaign ID for which you want to get the details. Used in required combination with the other parameters.
triggerId
(optional)
integer Message campaign trigger ID. Used in required combination with the other parameters.
dateTimeFrom
(optional)
datetime Start date of the message search. Used in required combination with the other parameters. The format is YYYY-MM-DD+hh:mm:ss.
dateTimeTo
(optional)
datetime End date of the message search. Used in required combination with the other parameters. The format is YYYY-MM-DD+hh:mm:ss.
messageIds
(optional)
array[integer] Message IDs for which you want to get the details. Used in required combination with the other parameters.
countryId
(optional)
integer Country ID.
mogId
(optional)
integer Mobile operator group ID.
order
(optional)
string

How to display the request results.

Possible values:
ASC - in ascending order.
DESC - in descending order.

orderField
(optional)
string Field by which to sort the request results.
outFields
(optional)
array[string] Fields to be shown in request results. Fields that are not specified in this parameter will be excluded.
recipient
(optional)
string Recipient's phone number.
searchText
(optional)
string Retrieve messages containing this keyword.
sourceAddress
(optional)
string Approved sender's name.
status
(optional)
string

The messages status in the request results.

Possible values:
DELIVERED - the message has been delivered to the user.
IN_PROGRESS - the message is in the process of being sent to the operator.
READ - The message has been read.
REDIRECT - the recipient has followed the link in the message.
REJECTED - the message has been rejected by the operator or Devino.Online.
UNDELIVERED - unable to deliver the message.

timeOffset
(optional)
integer Recipient's time zone.
userId
(optional)
integer Campaign sender user ID.

Parameters combinations

To get the correct request results, you should use one of these parameters combinations in accordance with the list:

  • Message campaign ID: taskId
  • Message campaign ID and trigger ID: taskId, triggerId
  • Start and end dates for the message search: dateTimeFrom, dateTimeTo
  • Message campaign ID, trigger ID; start and end dates for the message search: taskId, triggerId, dateTimeFrom, dateTimeTo
  • Message IDs: messageIds

Fields for orderField and outFields parameters

Used in the orderField parameter to sort the search results and in the outFields parameter to filter fields.

Field name Description
ACTION_URL

URL or deep link to which the user went after clicking the button.

The parameter is also used to specify the URL of the attached video or file.

BUTTON_CAPTION Button text.
CALLBACK_DATA An object with the data which are specified in the callback with the message status.
CALLBACK_URL The URL to which the system sends notifications about message status changes.
CLIENT_ACTION_URL URL or deep link sent in the recipient's reply message.
COMPANY_ID Company ID.
COMPANY_NAME Company name.
CONTACT_ID Recipient ID from the contact list.
COUNTRY_ID Country ID.
COUNTRY_NAME Country name.
ERROR_CODE Error code.
EVENT_DATE_TIME Date and time the status of the message was last updated.
IMAGE_URL Image link attached to the message.
MESSAGE_ID Message ID.
MOG_ID Mobile operator group ID.
MOG_NAME Mobile operator group name.
MO_ID Mobile operator ID.
MO_NAME Mobile operator name.
PRICE Message price.
PROVIDER_MESSAGE_ID Operator's message ID.
RECIPIENT Recipient's phone number.
RECIPIENT_ZONE_NAME Recipient's time zone.
ROUTE_ID Route ID the message has been sent.
SENT_DATE_TIME Date and time the message was sent.
SOURCE_ADDRESS Sender's name.
STATUS Message status.
TASK_ID Campaign ID.
TASK_NAME Campaign name.
TASK_TYPE Campaign type.
TEXT Message text.
TRAFFIC

Traffic type.

Possible values:
ADVERTISING - advertising traffic.
AUTHORIZATION - authorization traffic.
INCOMING - incoming traffic.
SERVICE - service traffic.
TRANSACTIONAL - transactional traffic.

TRIGGER_CONTACT_GROUP The name of the contact list to which the campaign was sent.
TRIGGER_SEGMENT The name of the contact list segment to which the campaign was sent.
IS_CONTACT_GROUP_DELETED Whether the contact list from which the message was sent has been deleted.
IS_TRIGGER_SEGMENT_DELETED Whether the contact list, the contact from which the message was sent, has been deleted.
TRIGGER_ID Campaign trigger ID.
USER_ID Sender's user ID.
USER_LOGIN Sender's user login.

Request examples

curl -X GET https://api.devino.online/viber-stat/statistics/detail?startDate=2022-10-06+13:45:30&endDate=2023-02-06+13:45:30&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \
curl -X GET https://api.devino.online/viber-stat/statistics/detail?taskId=8742&triggerId=2312&limit=20&offset=1
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters

Parameter Data type Description
data array[object] An array of objects with detailed information on each message. The parameters are defined by the fields that were set in the original request.
size integer Number of items per page and messages in search results. Set by limit parameter.
offset integer Search results offset. For example, if the number 5 is specified in the parameter, the received array of messages will be displayed only from the 5 in the pull.
number integer

The number of the received page. Defined by the offset parameter.

○ If the offset parameter value is 0 with any limit parameter value, then the page number will be 1.

○ If the offset will be greater than 0 but less than the limit parameter value, the page number will be 2. For example, with "offset": 5 and "limit": 10 the number parameter value will be 2.

○ If the offset will be greater than limit, the page number will be determined by integer division of offset by limit plus 1 (offset / limit + 1). For example, with "offset": 1000 and "limit": 50, the number parameter value will be 21 (1000 / 50 + 1 = 21).

pageExists boolean Whether the displayed page exists.
total integer The total number of messages for which the details can be received.
pages integer The total number of pages for which the details can be received. Determined by integer division of the total parameter by limit (total / limit).
more boolean Indicator: whether there are pages after the current one specified in the number parameter.

Response example

{
  "result": {
    "offset": 1000,
    "number": 21,
    "size": 50,
    "pageExists": true,
    "data": [
      {
        "messageId": "234567865432456787634",
        "sentDateTime": "2022-12-14 05:55:32",
        "sourceAddress": "sendersName",
        "recipient": "79001112233",
        "status": "DELIVERED",
        "eventDateTime": "2022-12-14 05:54:52",
        "companyId": 234,
        "companyName": "MyCompany",
        "userId": 88,
        "userLogin": "79991112233",
        "countryId": 12,
        "countryName": "Russia",
        "mogId": 0,
        "mogName": "MOG",
        "moName": "MO",
        "moId": 234,
        "price": "1.0000",
        "text": "Hello",
        "errorCode": 0,
        "traffic": "ADVERTISING",
        "isContactGroupDeleted": "No",
        "recipientTimeZoneOffset": "180"
      },
      ...
    ],
    "more": true,
    "pages": 100,
    "total": 1000
  }
}

Message statistics

To get the general statistics on message statuses, you need to call GET /viber-stat/statistics/of-group, sending filter parameters with the authorization data in the header.

Request parameters

Parameter Data type Description
groupBy string

Results grouping:
NONE - no grouping
YEAR - by year
MONTH - by month
WEEK - by week
DAY - by day
HOUR - by hour

startDate datetime Start of the date range. The format is YYYY-MM-DDThh%3Amm%3Ass.
endDate datetime End of the date range. The format is YYYY-MM-DDThh%3Amm%3Ass.
taskId
(optional)
integer Campaign ID for which the statistics is needed.
triggerId
(optional)
integer Campaign trigger ID for which the statistics is needed.
timeOffset
(optional)
integer Recipient's time zone. The format is offset in minutes, for example, 180 for Moscow (GMT+3).

Request examples

curl -X GET https://api.devino.online/viber-stat/statistics/of-group?startDate=2022-10-06T13%3A45%3A30&endDate=2023-02-06T13%3A45%3A30&groupBy=MONTH
 -H 'Authorization: Key QWxhZGRpbjpvcGVuIHNlc2FtZQ==' \

Response parameters

Parameter Data type Description
messages array[MessageStatusObject] The number of messages for the selected period, grouped by status.
segments array[MessageStatusObject] The number of message segments for the selected period, grouped by status.

MessageStatusObject

The object contains information about the number of messages with statuses:

Code Description
accepted The message has been accepted.
scheduled The message is scheduled to be sent.
enrouted The message is in the process of being sent to the operator.
sent The message has been sent to the operator network.
deleted The message has been deleted.
delivered The message has been delivered to the user.
expired The lifetime of the message has expired.
seen The message has been read by the user.
clicked The recipient has followed the link in the message.
rejected The message has been rejected by the operator or Devino.Online.
undeliverable Unable to deliver the message.
unknown An unknown error has occurred.

Each status includes the parameters:

Parameter Data type Description
date string Statistics collection date depending on the value of the groupBy parameter.
amount integer The number of messages.

Response example

{
  "result": {
    "messages": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 100
        }
      ],
      "sent": [
        {
          "date": "2022-12-01 00:00:00",
          "amount": 2
        }
      ],
      "deleted": [],
      "delivered": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 67
        },
        {
          "date": "2022-10-01 00:00:00",
          "amount": 1
        },
        {
          "date": "2022-12-01 00:00:00",
          "amount": 72
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 3
        }
      ],
      "enrouted": [],
      "expired": [],
      "seen": [],
      "clicked": [],
      "rejected": [],
      "scheduled": [],
      "undeliverable": [],
      "unknown": []
    },
    "segments": {
      "accepted": [
        {
          "date": "2023-01-01 00:00:00",
          "amount": 2
        },
        {
          "date": "2023-02-01 00:00:00",
          "amount": 4
        }
      ]
      ...
    }
  }
}