Viber Business Messages

Viber Business Messages (VIBERBM) supports 3 types of business account: 1way, 2way and session:

  • 1way is an account which can send one-way messages only - the contact can't enter a reply from the device
  • 2way accounts allow contacts to reply
  • session accounts can't initiate the conversation to the contact. Instead, the conversation must be started by the contact. Session accounts only support text and image messages.

For all types of accounts the phone number is the contact identifier of the recipient of the business messages (channel recipient identity).

Conversation API supports 1way and 2way Viber BM accounts.

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

VIBER Business Messages channel natively supports text messages. The maximum length of the text is 1000 characters. Longer content will be truncated. 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

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.

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:

{
  "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": "VIBERBM",
    "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": "VIBERBM",
    "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_out_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"
   }
}