Viber for Business
Our business messaging API supports sending and receiving Viber for Business messages.
Being able to send Viber messages requires requesting access via the Channels portal. Without onboarding with Viber via the portal, you can not make use of this part of the API. Please be aware that Viber needs to verify the legitimacy of your business and your rationale for usage.
Fact Sheet
| Feature | Support | Remarks |
|---|---|---|
| delivery notification | yes | Occurs when your message is delivered to the Viber platform. Delivery notifications are sent to the status report webhooks. |
| text messages | yes | The maximum length of a message is 1000 characters. Text formatting like bold, italics, monospace and strikethrough text are supported (see below). |
| media | yes | Media URL attributes should end in the proper file extension. Only one media file is allowed per message; when sending multiple files, each file will be sent in its own message. When the linked media doesn't exist/can't be found, the message will not be sent at all. |
| media: images | yes | Maximum file size for an uploaded image is 200 MB. Supported formats: png, jpeg, jpg, gif. |
| media: audio | no | |
| media: video | yes | Maximum file size for an uploaded video file is 200 MB. Maximum duration of the video can be up to 10 minutes. Supported formats: mp4. Server which host the video must include 'Content-Length' in response header. |
| media: document | yes | Maximum file size for an uploaded file is 200 MB. Supported formats: doc(x), xls(x), csv, pdf. |
| suggestion as button | yes | Only 1 button is possible |
| rich card | yes | Only 1 button is possible |
| templates | yes | Predefined OTP templates, configurable with own variables. |
| carousel | yes | Number of items from 2 to 5. Each item can have a image with expected formatspng, jpeg, jpg. Each item have two buttons ( one of them optional) |
| list | yes | Number of items from 2 to 5 |
Sending messages
Viber is one of the few channels which uses telephone numbers as recipients. This allows SMS to be used as a fallback delivery channel if the recipient doesn't have the Viber app installed on their mobile device.
Please note that when defining fallback text, it is affected by the maximum size limitations of SMS as described in the section on SMS multipart messaging.
Text formatting
Viber allows the usage of formatting text following markdown guidelines:
| Format | Markdown | Text to be sent | Message appearance |
|---|---|---|---|
| Bold | One asterisk at each end of the text: * | *This text will be bold* | This text will be bold |
| Italics | One underscore at each end of the text: _ | _This text will be in italics_ | This text will be in italics |
| Monospace | Three backticks at each end of the text: ``` | ```This text will be in monospace``` | This text will be in monospace |
| Strikethrough | One tilde at each end of the text: ~ | ~This text will have a strikethrough~ |
URL requirements
Viber enquires the following requirements that apply to using (image) URLs
- Only use secured HTTPS links
- Make sure that image URLs are not protected by a captcha
- Make sure the image URLs include file extensions (
.mp4,.png,.jpeg) - Links to one of the following apps are not allowed
- Line
- Signal
- Telegram
Text
The example below will send a simple text-only Viber message.
{
"messages": {
"msg": [
{
"from": "Your Sender",
"to": [
{
"number": "Phone number recipient"
}
],
"allowedChannels": [
"Viber"
],
"body": {
"type": "auto",
"content": ""
},
"richContent": {
"conversation": [
{
"text": "Be part of it."
}
]
}
}
]
}
}
Media
The following media types are supported:
| Media type | Supported formats | Mimetype | Supported size maximum |
|---|---|---|---|
| Image | png, jpeg, gif | image/png, image/jpeg, image/gif | 200MB |
| Video | mp4 | video/mp4 | 200MB |
| Document | doc(x), xls(x), csv, txt, pdf | application/msword, application/vnd.ms-excel, text/csv, text/plain, application/pdf | 200MB |
Direct message with text and image
In the example below we send a simple rich content message that contains both text and an image.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaUri": "https://www.cm.com/cdn/cm/cm.png",
"mimeType": "image/png",
"mediaName": "cm.png"
}
}
]
}
}
]
}
}
Direct message with text and video
In the example below we send a simple rich content message that contains both text and a video.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaUri": "your-video-url.mp4",
"mimeType": "video/mp4",
"mediaName": "your-video.mp4"
}
}
]
}
}
]
}
}
Direct message with document
In the example below we send a simple rich content message that contains a document.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"media": {
"mediaUri": "your-document.pdf",
"mimeType": "application/pdf",
"mediaName": "your-document.pdf"
}
}
]
}
}
]
}
}
Suggestion
Suggestions provide a way to present a button in your message the user can press to perform an action. Only 1 button per message is supported.
The following actions are supported by Viber as rich card buttons.
| Action | Remarks |
|---|---|
| OpenURL | Maximum length of label is 30 characters, url required. |
| Dial | Maximum length of label is 30 characters, phone number required. |
The following restrictions apply for a suggestion:
| Field | Required | Remarks |
|---|---|---|
| label | Yes | Maximum length is 30 characters. |
| url | Only for OpenURL | Must be a valid URL |
| phoneNumber | Only for Dial | Must be a valid phone number |
Message with open url action
In the example below, we send a simple rich content message that contains elements that Viber will display as an open URL action.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"suggestions": [
{
"action": "OPENURL",
"label": "Visit CM.com",
"url": "https://www.cm.com/",
"postbackdata": "WEBSITE"
}
]
}
]
}
}
]
}
}
Message with dial action
In the example below, we send a simple rich content message that contains elements that Viber will display as an dial action.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"text": "CM.com - Be part of it.",
"suggestions": [
{
"action": "DIAL",
"label": "Call us",
"dial": {
"phoneNumber": "0031612345678"
},
"postbackdata": "DIAL"
}
]
}
]
}
}
]
}
}
Rich card
Rich cards offer a way for you to offer a richer in-conversation experience than standard text messages by integrating buttons, images and more alongside text in a single message. Rich cards can be used for many purposes, such as displaying product information or asking the message recipient to choose from a pre-determined set of options.
The following restrictions apply for using a rich card:
| Field | Required | Remarks |
|---|---|---|
| header | Yes | Displayed as the title. Maximum length is 30 characters. |
| text | No | Displayed as the subtitle. Maximum length is 900 characters. |
| mediaUri | No | The URL of the image to display. |
| suggestions | No | Suggestions as buttons. Maximum of 1 button per card. |
The following actions are supported by Viber as rich card buttons.
| Action | Remarks |
|---|---|
| OpenURL | Maximum length of label is 30 characters, url required. |
| Dial | Maximum length of label is 30 characters, phone number required. |
In the example below we send a rich content message that contains rich card properties. The rich card is composed of a title, a subtitle, a media image and a suggestion.
{
"messages": {
"msg": [
{
"from": "Your sender",
"to": [
{
"number": "Phone number"
}
],
"allowedChannels": [
"Viber", "SMS"
],
"body": {
"type": "auto",
"content": "SMS fallback Text"
},
"richContent": {
"conversation": [
{
"header": "We are CM.com!",
"text": "Visit our website or start a chat with one of our employee's!",
"media": {
"mediaUri": "https://www.cm.com/cdn/cm/cm.png",
"mimeType": "image/png",
"mediaName": "cm.png"
},
"suggestions": [
{
"action": "OPENURL",
"label": "Visit our website!",
"url": "https://www.cm.com",
"postbackdata": "WEBSITE"
}
]
}
]
}
}
]
}
}
Carousel
Carousel messages offer a way for you to send a single message featuring text and multiple customizable sections (items), each showcasing different products or services along with dedicated media and call-to-action.
The following restrictions apply for using a rich card:
| Field | Required | Remarks |
|---|---|---|
| text | Yes | Message text. Up to 1000 characters. Recommended length is 200 characters. |
| items | Yes | From 2 to 5 items. |
| items title | Yes | Item title text. From 2 to 38 characters. |
| mediaUri | Yes | The URL of the image to display. One per item. |
| suggestions | Yes | Maximum 2 suggestions per item. One of them optional. |
The following actions are supported by Viber as rich card buttons.
| Action | Remarks |
|---|---|
| OpenURL | Maximum length of label is 30 characters, url required. |
| Dial | Maximum length of label is 30 characters, phone number required. |
The following restrictions apply for suggestions
| Field | Required | Remarks |
|---|---|---|
| label | Yes | Maximum length is 10 characters. Optional suggestion maximum 12 characters. |
| url | Only for OpenURL | Must be a valid URL |
In the example below we send a rich content message that contains a carousel with two items. Each item is composed of a title, a media image and a two suggestions.
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"carousel": {
"cards": [
{
"text": "Visit our website or start a chat!",
"media": {
"mediaUri": "your-image.png"
},
"suggestions": [
{
"action": "OpenUrl",
"label": "CM.com",
"url": "https://cm.com"
}
]
},
{
"text": "Channels we support!",
"media": {
"mediaUri": "your-image.png"
},
"suggestions": [
{
"action": "OpenUrl",
"label": "WhatsApp",
"url": "https://www.cm.com/whatsapp/"
},
{
"action": "OpenUrl",
"label": "Viber",
"url": "https://www.cm.com/viber"
}
]
}
]
}
}
]
}
}
]
}
}
List
List messages offer a way to present users with a question and 2-5 answers from which they can select one. Once a user selects an item, it will be highlighted as selected, and the corresponding item text will be sent from the user to you as a reply. After making a selection, the user is able to change it. If the selection is changed, an additional message will be sent on the user's behalf to you.
List messages supports text formatting and emojis. Links are not supported.
| Field | Required | Remarks |
|---|---|---|
| text | Yes | Message text. Up to 85 UTF-8 character. |
| suggestions | Yes | Number of items, between 2 and 5. |
For each suggestion item, the following restrictions apply:
| Field | Required | Remark |
|---|---|---|
| label | Yes | Up to 50 UTF-8 characters per item |
| action | Yes | Always needs to be "Reply" |
In the example below we send a list message that contains two items.
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"text": "What's your favorite channel?"
}
],
"suggestions": [
{
"action": "Reply",
"label": "Viber"
},
{
"action": "Reply",
"label": "WhatsApp"
}
]
}
}
]
}
}
Templates (OTP)
Templates are predefined messages stored on Viber side which allows you to define specific values upon sending the message. Templates are used for sending one time password (OTP) messages.
The following template types are supported by Viber:
| Template | Template ID |
|---|---|
| Basic OTP | 0aac888f-2ee2-4112-9659-1755a951966a |
| Basic OTP valid for 5 min | c2cdc028-a48b-4187-bbaf-3aaa137b6e23 |
| OTP with business/platform | c33cccaf-735f-4d62-8383-a76bf4999e2d |
| Basic OTP with code validity time | bed0942f-e07e-4879-834b-29cc4cf3ec35 |
| OTP with code type & validity time | 60d67b38-b9fb-444a-80e6-754447e010c6 |
| OTP with details on OTP action/platform | 210ee8a9-1ed5-43cd-96e4-65bba311ab40 |
| OTP with business/platform name & validity time | 6c929cef-29b4-4349-bc9d-2a07bdbb6e43 |
| OTP with type of code | 82ba31a3-db42-4e87-82e8-33fa92b9e5ed |
| .OTP with business/platform name & code reason | be56d97b-2a33-4c89-ac5f-f555a2c827d9 |
The following restrictions apply for using (OTP) templates:
| Field | Required | Remarks |
|---|---|---|
| templateId | Yes | One of the given template ids. |
| templateLanguage | Yes | Default: en (English) |
| templateParams | Yes | See examples below for the required params per template type. |
Basic OTP
In the example below we send a basic OTP template:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "0aac888f-2ee2-4112-9659-1755a951966a",
"template_language": "en",
"template_params": {
"pin": "[pin]"
}
}
}
}
]
}
}
]
}
}
Basic OTP valid for 5 minutes
In the example below we send a basic OTP template that's valid for 5 minutes:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "c2cdc028-a48b-4187-bbaf-3aaa137b6e23",
"template_language": "en",
"template_params": {
"pin": "[pin]"
}
}
}
}
]
}
}
]
}
}
OTP with business/platform name
In the example below we send a OTP template with a business/platform name:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "c33cccaf-735f-4d62-8383-a76bf4999e2d",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"business_platform_name": "[business_platform_name]"
}
}
}
}
]
}
}
]
}
}
Basic OTP with code validity time
In the example below we send a basic OTP template with a given validity time:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "bed0942f-e07e-4879-834b-29cc4cf3ec35",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"code_validity_time": 2
}
}
}
}
]
}
}
]
}
}
OTP with code type & validity time
In the example below we send a OTP template with a given validity time and pin type:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "60d67b38-b9fb-444a-80e6-754447e010c6",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"code_validity_time": 2,
"pin_type": "[pin_type]"
}
}
}
}
]
}
}
]
}
}
OTP with business/platform name & validity time
In the example below we send a OTP template with a given validity time and business platform name:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "6c929cef-29b4-4349-bc9d-2a07bdbb6e43",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"business_platform_name": "[business_platform_name]",
"code_validity_time": 2
}
}
}
}
]
}
}
]
}
}
OTP with type of code
In the example below we send a OTP template with a given pin/code type:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "82ba31a3-db42-4e87-82e8-33fa92b9e5ed",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"pin_type": "[pin_type]"
}
}
}
}
]
}
}
]
}
}
OTP with details on OTP action/platform
In the example below we send a OTP template with a given business/platform action:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "210ee8a9-1ed5-43cd-96e4-65bba311ab40",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"business_platform_action_name": "[business_platform_action_name]"
}
}
}
}
]
}
}
]
}
}
OTP with business/platform name & code reason
In the example below we send a OTP template with a given reason and business/platform name:
{
"messages": {
"msg": [
{
"from": "",
"to": [
{
"number": ""
}
],
"body": {
"content": ""
},
"allowedChannels": [
"Viber"
],
"richContent": {
"conversation": [
{
"template": {
"viber": {
"template_id": "be56d97b-2a33-4c89-ac5f-f555a2c827d9",
"template_language": "en",
"template_params": {
"pin": "[pin]",
"business_platform_name": "[business_platform_name]",
"code_reason": "[code_reason]"
}
}
}
}
]
}
}
]
}
}
Updated about 19 hours ago