Viber Bot
Viber Bot channel enables communication with users of Viber ecosystem through Conversation API. You need a Viber bot for integrating your Conversation API with Viber.
Note:
If you are unfamiliar with Viber and Viber bots, 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.
If you don't already have a Viber bot, follow the steps below to create a new Viber bot:
- You must have an active Viber account which will be used to administer your new bot. You already have an account if you have Viber app installed and can sign in. Otherwise, go to Viber download page and select to download the Viber app from the app store of your mobile device.
- Follow the steps in Create Viber Bot Page to create your new bot. Once your bot is created its authentication token will appear in the account’s “edit info” screen .
Channel Configuration
The easiest way to configure your Conversation API app to use the Viber Bot channel to use Sinch Customer Dashboard. Just select your app and click SET UP CHANNEL next to the Viber Bot channel. You will be asked to enter the the access token for your Viber bot.
If you haven't already, you must also configure at least one Conversation API webhook which will trigger POST callbacks to the given URL. For more information on how to do this using the Customer Dashboard, see How to add a webhook to a Conversation API app.
Setup Viber Bot integration using the API
To setup the Viber Bot channel using API calls, you must update (or, if you are making a new app, create) your Conversation API app with your Viber Bot credentials. These credentials must be included in the channel_credentials object array, as shown in the example snippet below:
{
"channel_credentials": [
{
"channel": "VIBER",
"static_token": {
"token": "{{VIBER_BOT_TOKEN}}"
}
}
]
}Replace {{VIBER_BOT_TOKEN}} with your Viber bot's access token.
Note
For Viber Bot, you can configure Callback Validation between the Viber Bot API and the Conversation API, which will ensure that the callbacks are valid.
This can be done using the customer dashboard when configuring your Viber Bot channel or by adding "callback_secret": "<string>" to the "channel_credentials" object in the snippet above.
In this case, the callback_secret is the same as your VIBER_BOT_TOKEN.
If you haven't already, you must also configure at least one Conversation API webhook which will trigger POST callbacks to the callback URL. For more information on how to do this programmatically, click here.
Testing the integration
Viber Bot API doesn't allow sending bot messages to Viber users which haven't
subscribed to the bot. To send a message on Viber Bot channel you need the recipient's
Viber user ID. You can get the ID when the user subscribes to your bot (you will get an
OPT_IN Notification), or if you receive a message
from the user. To test your integration open the Viber app and search for the name of your Viber bot and send a message to it. You should receive two callbacks on the registered Conversation API webhooks -
one is conversation_start_notification and the other is the actual message sent from the handset.
Both callbacks contain a field contact_id which is the identifier of the
contact that was automatically created when processing the inbound Viber message.
This contact contains the channel identity for the Viber user and you can use this contact_id to reply to the Viber user.
The Viber Bot channel identities are opaque identifiers which are scoped to an app.
This means that the same Viber user will have two different channel identities for
two different Conversation API apps. Therefore a Conversation API contact can have multiple
Viber Bot identities - the /messages:send endpoint automatically picks the correct
identity which corresponds to the requesting app.
Sending Messages
Some rich messages are natively supported by Viber Bot channel while others must be transcoded. The following sections demonstrate the mapping between the Conversation API generic message format and the way Viber renders the messages on mobile devices.
When sending messages on Viber Bot you can use some channel specific properties, like Viber sender avatar. Check out Channel Specific Properties for more info.
Text Messages
The Viber Bot channel natively supports text messages. You can include a maximum of 7000 characters in the text message. 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 Bot channel natively supports media messages.
In this message you can send the following media types on Viber Bot channel:
- image: .jpeg, .png, non-animated .gif
- video: .mp4 with H264 encoding
- document: any valid document MIME type
The following image gives an example of media messages.
The code to send a media message for this channel doesn't differ from the generic message and can be viewed here.
Choice Messages
The Viber Bot channel natively supports choice messages. The limit for the text field of the text_message object within a choice_message is 7000 characters (the same maximum character count allowed for text messages sent on the Viber Bot channel). 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
The Viber Bot channel natively supports card messages. When using the Viber Bot channel, the maximum number of choices that can be defined in the choices field of a card message is 4. 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 Bot channel natively supports carousel messages. 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 Bot channel natively supports location messages. 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
Viber channel supports various kinds of contact messages - text, media, media card, location and quick replies.
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.
All of these are delivered by Conversation API with POST to MESSAGE_INBOUND webhook:
Example text reply:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"accepted_time": "2020-10-01T12:06:13.806686Z",
"event_time": "2020-10-01T12:06:13.254Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"message": {
"id": "01EKJ0WGFM7TR314K4D9Y31J5S",
"direction": "TO_APP",
"contact_message": {
"text_message": {
"text": "This is text message from Viber user."
}
},
"channel_identity": {
"channel": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"app_id": "01EB37HMH1M6SV18ASNS3G135H"
},
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"metadata": "",
"accept_time": "2020-10-01T12:06:13.794339Z"
}
}Example location contact message:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"accepted_time": "2020-10-01T12:07:35.513615Z",
"event_time": "2020-10-01T12:07:34.935Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"message": {
"id": "01EKJ0Z07XKM6H04VB5Q941QBP",
"direction": "TO_APP",
"contact_message": {
"location_message": {
"title": "",
"coordinates": {
"latitude": 55.73064,
"longitude": 13.160131
},
"label": ""
}
},
"channel_identity": {
"channel": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"app_id": "01EB37HMH1M6SV18ASNS3G135H"
},
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"metadata": "",
"accept_time": "2020-10-01T12:07:35.496355Z"
}
}Example media message:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"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": "01EKJ1534NWK5R02TGWEJN13HA",
"direction": "TO_APP",
"contact_message": {
"media_message": {
"url": "https://dl-media.viber.com/5/media/2/short/any/sig/image/0x0/e9f1/61be89dcb2a9bc54bf5a998000e33b67e78557a1dc267e9ea4625d344e2ee9f1.jpg?Expires=1601557854&Signature=eCGFLNPPvyoltyO5kp-yZRgGuvdtFfOtehapbiTf9KkUAZ7268GT0YnZ8Mj750IgZhRS7Z~6g6cOZ2wbHcZgPjxfzNWS8F4A8ejWPb1v8crGA1hzaHGmuSWoIxlJguqGOjHvTfUxLOvInkqdCIQ4S8IMq-B65lOV~~iw7HScAXTjarSiua4pGOgdbPvSqULyec6omwJH7IE~4xg0TfuNJSAH4JTRwU4ByGPtkbsJ800VpdK1GA~kHV0vRKRSy2wXPcy6j-i17SX3Le06LYZd1aJNpAxGhgcMgRMsY34SS60~dDtwmnr2QNcktPg61cpK1UVhVwiZ09MfO9~6kmTIZQ__&Key-Pair-Id=APKAJ62UNSBCMEIPV4HA"
}
},
"channel_identity": {
"channel": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"app_id": "01EB37HMH1M6SV18ASNS3G135H"
},
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"metadata": "",
"accept_time": "2020-10-01T12:10:55.060170Z"
}
}Example media card message:
{
"app_id": "01EB37HMH1M6SV18ASNS3G135H",
"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": "01EKJ1534NWK5R02TGWEJN13HA",
"direction": "TO_APP",
"contact_message": {
"media_card_message": {
"url": "https://dl-media.viber.com/5/media/2/short/any/sig/image/0x0/e9f1/61be89dcb2a9bc54bf5a998000e33b67e78557a1dc267e9ea4625d344e2ee9f1.jpg?Expires=1601557854&Signature=eCGFLNPPvyoltyO5kp-yZRgGuvdtFfOtehapbiTf9KkUAZ7268GT0YnZ8Mj750IgZhRS7Z~6g6cOZ2wbHcZgPjxfzNWS8F4A8ejWPb1v8crGA1hzaHGmuSWoIxlJguqGOjHvTfUxLOvInkqdCIQ4S8IMq-B65lOV~~iw7HScAXTjarSiua4pGOgdbPvSqULyec6omwJH7IE~4xg0TfuNJSAH4JTRwU4ByGPtkbsJ800VpdK1GA~kHV0vRKRSy2wXPcy6j-i17SX3Le06LYZd1aJNpAxGhgcMgRMsY34SS60~dDtwmnr2QNcktPg61cpK1UVhVwiZ09MfO9~6kmTIZQ__&Key-Pair-Id=APKAJ62UNSBCMEIPV4HA",
"caption": "caption text"
}
},
"channel_identity": {
"channel": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"app_id": "01EB37HMH1M6SV18ASNS3G135H"
},
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"metadata": "",
"accept_time": "2020-10-01T12:10:55.060170Z"
}
}Example quick reply message:
{
"app_id": "01EGQYR8N9S5VF096DQKYF08JD",
"accepted_time": "2020-10-01T12:39:48.469849Z",
"event_time": "2020-10-01T12:39:48.296Z",
"project_id": "ab5536b1-31b0-45e8-aec6-b35f13c41d0b",
"message": {
"id": "01EKJ2SZX9N6F11SJ11G511H6J",
"direction": "TO_APP",
"contact_message": {
"choice_response_message": {
"message_id": "01EKJ2SWHGDMYA0F0F1PQJ09WQ",
"postback_data": "suggested"
}
},
"channel_identity": {
"channel": "VIBER",
"identity": "+blNgtOp1StVmBEfR3xa5g==",
"app_id": "01EGQYR8N9S5VF096DQKYF08JD"
},
"conversation_id": "01EHY7KA6ZC03C1Q5QTRZ60GDA",
"contact_id": "01EHY7KA2BYT8A11E6Y2271NHA",
"metadata": "",
"accept_time": "2020-10-01T12:39:48.457764Z"
}
}Receiving Delivery Receipts
Messages sent on Viber channel can have three statuses: DELIVERED, READ and FAILED.
If the status is FAILED the reason will include more information about the failure.
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": "01EB37HMH1M6SV18ASNS3G135H",
"accepted_time": "2020-10-01T12:10:00.530Z",
"event_time": "2020-10-01T12:10:03.624Z",
"project_id": "c36f3d3d-1513-4edd-ae42-11995557ff61",
"message_delivery_report": {
"message_id": "01EKJ13DYJX54C0N062N0Q1J9F",
"conversation_id": "01EKJ0KSWXMVDF05MG9TQ20S06",
"status": "READ",
"channel_identity": {
"channel": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"app_id": "01EB37HMH1M6SV18ASNS3G135H"
},
"contact_id": "01EKA07N79THJ20WSN6AS30TMW",
"metadata": ""
}
}Receiving User Opt-In/Out
Viber users can at any time opt-in or opt-out of receiving messages by given Viber Bot.
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": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"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": "VIBER",
"identity": "9KC0p+pi4zPGDO99ACDxoQ==",
"status": "OPT_OUT_SUCCEEDED",
"request_id": "01F7N9TEH11X7B15XQ6VBR04G7"
}
}
