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:

Copy

Copied

{
  "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~	~~This text will have a strikethrough~~

The following image gives an example of a text message:

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
.pdf
.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.

Image 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.

URL 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.

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.

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.

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.

Conversation API POST to MESSAGE_INBOUND webhook for text message:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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:

Copy

Copied

{
  "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"
  }
}