VIBER¶

Sending¶

To send Viber messages it is required to:

Agree on sender's name in personal account.
Call POST /viber/messages, sending message parameters in the request body with the authorization data in the header.

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¶

Text with image and button

{
  "messages": [
    {
        "from": "MyCompany",
        "to": "79034567890",
        "text": "Code: 1234",
        "image": "https://cdn.mycompany.com/viber.png",
        "action": "https://mycompany.com/promo?code=1234",
        "caption": "Activate!"
    }
  ]
}

Video

{ 
  "messages": [
    {
        "from": "MyCompany",
        "to": "79034567890",
        "thumbnail": "https://myvideo.com/thumbnail.jpg",
        "duration": 433,
        "fileSize": 32,
        "action": "https://myvideosource.com/video.mp4"
    }
  ]   
}

File

{ 
  "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¶

OK

{
  "result": [
    {
      "code": "OK",
      "messageId": "3702436063699518976"
    }
  ]
}

REJECTED

{
  "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¶

Text message

{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "text": "Incoming message",
  "ts": "1587721283000"
}

File

{
  "incomingMessageId": "3777714415805253122",
  "to": "MyCompany",
  "from": "79101111111",
  "contentUrl": "https://dl-media.viber.com/20/media/42.pdf",
  "contentName": "userfile.pdf",
  "ts": "1587721283000"
}

Video

{
  "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:

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

Note

You can send up to 5 consecutive session type messages without a user response

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

24 hours have passed since the session started.
More than 10 messages were sent to the user in a row.
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¶

DELIVERED

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

REJECTED

[
  {
    "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¶

With dates

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==' \

With task ID and trigger ID

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
        }
      ]
      ...
    }
  }
}

VIBER¶

Sending¶

Request parameters¶

Request body¶

Message¶

Possible parameters combinations¶

Request examples¶

Response parameters¶

Response examples¶

Incoming messages¶

Parameters¶

Examples¶

Sessions¶

Callbacks¶

Possible statuses¶

Callback examples¶

Details¶

Request parameters¶

Parameters combinations¶

Fields for orderField and outFields parameters¶

Request examples¶

Response parameters¶

Response example¶

Message statistics¶

Request parameters¶

Request examples¶

Response parameters¶

MessageStatusObject¶

Response example¶

Fields for `orderField` and `outFields` parameters¶