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