Viber Business Messages
The Viber Business Messages (VIBERBM) channel of the Conversation API supports 2way business accounts, which can send messages and allow contacts to reply. For these accounts, the phone number is the contact identifier of the recipient of the business messages (channel recipient identity).
Note:
If you are unfamiliar with Viber, we encourage you to visit the Viber Knowledge Base on the Sinch Community site. There, you'll find articles that answer common questions and provide context for the information detailed below.
Channel Configuration
You need a Viber Business service plan in order to integrate with VIBERBM
channel. Your account manager can help you with the creation and configuration
of VIBERBM service plan for your Conversation API app. You can request this
through the Sinch Dashboard.
Just select your app and click on "SET UP CHANNEL" beside the Viber Business Messages channel.
You will receive a Viber Business service ID which you can then use in the
Sinch Dashboard to finish the
Viber Business Messages integration for your Conversation API app.
Alternatively you can use the management API to configure your app with
channel_credentials
for VIBERBM channel. The example snippet below
shows the credentials configuration for VIBERBM channel:
{
"channel_credentials": [
{
"channel": "VIBERBM",
"static_bearer": {
"claimed_identity": "{{VIBERBM_SERVICE_ID}}"
}
}
]
}
You need to replace {{VIBERBM_SERVICE_ID}}
with your VIBERBM service ID.
Don't forget to create at least one Conversation API webhook which will trigger POST callbacks to the given URL. You can do that from the Sinch Dashboard or programmatically using the management API.
Sending Messages
Some rich messages are natively supported by VIBERBM channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way VIBERBM renders the messages on mobile devices.
Text Messages
The Viber Business Messages channel natively supports text messages. The maximum length of a text message is 1000 characters. Longer content will be truncated. Texts can be formatted with markdown.
Format | Markdown | String to be sent | Appearance on message |
---|---|---|---|
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~ |
The following image gives an example of a text message:
The code to send a text message for this channel doesn't differ from the generic message and can be viewed here.
Media Messages
Viber Business Messages supports media messages natively.
Supported image types:
- .jpg
- .jpeg
- .png
Supported document types:
- .doc
- .docx
- .rtf
- .dot
- .dotx
- .odt
- .odf
- .fodt
- .txt
- .info
- .xps
- .pdax
- .eps
- .xls
- .xlsx
- .ods
- .fods
- .csv
- .xlsm
- .xltx
Documents and media sent using media messages must be less than 200MB in size.
When sending a video media message, the following additional requirements apply:
-
The
thumbnail_url
must be set. See the media message schema for more information. - The thumbnail URL can be a maximum of 1000 characters.
-
The HTTP server that provides the video needs to set
Content-Length
in the HEAD response. - The video duration must be less than 600 seconds.
The following image gives an example of a media message.
The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.
Choice Messages
Viber Business Messages channel provides native support for single choice (URL, Call, or Location) choice messages. The title of the choice has a maximum length of 30 characters, longer content will be truncated. The following image gives an example of a choice message.
The code to send a choice message for this channel doesn't differ from the generic message and can be viewed here.
Card Messages
Viber Business Messages supports natively Card messages with one URL, Call, or Location choice. The media message in the Card should point to an image. The title of the choice in the Card message has a maximum length of 30 characters, longer content will be truncated.
The following image gives an example of a card message.
The code to send a card message for this channel doesn't differ from the generic message and can be viewed here.
Carousel Messages
Viber Business Messagers doesn't support natively Carousel messages and so they're transcoded and sent as text messages by Conversation API. The following image gives an example of a carousel message.
The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed here.
Location Messages
Viber Business Messages channel doesn't natively support location messages and so they're transcoded and sent as text messages by Conversation API. The following image gives an example of a location message.
The code to send a location message for this channel doesn't differ from the generic message and can be viewed here.
Receiving Messages
VIBERBM supports contact initiated messages and choice responses.
Note:
Please note that the media URLs included in the contact messages are valid for 7 days. After that the media is deleted from Conversation API storage.
Conversation API POST to MESSAGE_INBOUND
webhook for text message:
{
"app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
"accepted_time": "2020-04-24T08:02:50.184581Z",
"message": {
"id": "01E6NKBV63YG6K01ENEW7S1N80",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "Hi from contact"
}
},
"channel_identity": {
"channel": "VIBERBM",
"identity": "46712312312",
"app_id": ""
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "",
"accept_time": "2020-04-24T08:02:50.179021Z"
}
}
Conversation API POST to MESSAGE_INBOUND
webhook for choice response message:
{
"app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
"accepted_time": "2020-04-24T08:02:50.184581Z",
"message": {
"id": "01E6NKBV63YG6K01ENEW7S1N80",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01EKJ2SWHGDMYA0F0F1PQJ09WQ",
"postback_data": "postback"
}
},
"channel_identity": {
"channel": "VIBERBM",
"identity": "46712312312",
"app_id": ""
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "",
"accept_time": "2020-04-24T08:02:50.179021Z"
}
}
Conversation API POST to MESSAGE_INBOUND
webhook for media response message:
{
"app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
"accepted_time": "2020-10-01T12:10:55.073703Z",
"event_time": "2020-10-01T12:10:53.991Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"message": {
"id": "01E6NKBV63YG6K01ENEW7S1N80",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://1vxc0v12qhrm1e72gq1mmxkf-wpengine.netdna-ssl.com/wp-content/uploads/2019/05/Sinch-logo-Events.png"
}
},
"channel_identity": {
"channel": "VIBERBM",
"identity": "46712312312",
"app_id": ""
},
"conversation_id": "01E6K4A8PGZ6MV0GD3C7M901MZ",
"contact_id": "01E6K4A8N3NANZ05VM0FS80EHD",
"metadata": "",
"accept_time": "2020-04-24T08:02:50.179021Z"
}
}
Receiving Delivery Receipts
Messages sent on VIBERBM channel have three statuses: DELIVERED, READ and FAILED.
Below is an example for DELIVERED receipt - READ and FAILED differ by the
status
and reason
only.
Conversation API POST to MESSAGE_DELIVERY
webhook:
{
"app_id": "01E3S8B6YCMRNR0GGM94H80ACX",
"accepted_time": "2020-04-23T09:55:04.766Z",
"message_delivery_report": {
"message_id": "01E6K7CMXY3KHH0AGCTY6D04F2",
"conversation_id": "01E6JY5HMCADX31SANQ0YE0CH6",
"status": "DELIVERED",
"channel": "VIBERBM",
"reason": "",
"metadata": ""
}
}
Receiving User Opt-In/Out
Viber users can at any time opt-in or opt-out of receiving messages by given VIBERBM account.
Opt-In
Conversation API POST to OPT_IN
webhook:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"accepted_time": "2021-06-08T07:54:03.165316Z",
"event_time": "2021-06-08T07:54:02.112Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"opt_in_notification": {
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"channel": "VIBERBM",
"identity": "123456789",
"status": "OPT_IN_SUCCEEDED",
"request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
}
}
Opt-Out
Conversation API POST to OPT_OUT
webhook:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"accepted_time": "2021-06-08T07:54:03.165316Z",
"event_time": "2021-06-08T07:54:02.112Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"opt_out_notification": {
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"channel": "VIBERBM",
"identity": "123456789",
"status": "OPT_OUT_SUCCEEDED",
"request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
}
}