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 For example, if the parameter is enabled, the link
|
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. 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, You can send the following types of files: ○ Documents: .doc , .docx, .rtf, .dot, .dotx, .odt ,odf, .fodt, .txt, .info |
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 |
priority (optional) |
string | Message priority level.
|
scheduledTime (optional) |
string | UTC when the message is to be sent. Format: |
callbackUrl (optional) |
string | The URL to which the system will send notifications about message status changes. Any valid URL with the |
options (optional) |
object | An object with the data which will be specified in the callback with the message status. Any To start a session with a user, this object must have the |
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 caseaction
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. |
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:
- 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¶
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "DELIVERED",
"errorCode": 0
}
]
[
{
"messageId": "3597958273915257088",
"ts": 1613411223173,
"status": "REJECTED",
"errorCode": 2012
}
]