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.

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