# 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](https://community.sinch.com/t5/Viber/tkb-p/Viber) 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: 1. 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](https://www.viber.com/en/download/) and select to download the Viber app from the app store of your mobile device. 2. Follow the steps in [Create Viber Bot Page](https://partners.viber.com/account/create-bot-account) to create your new bot. Once your bot is created its authentication token will appear in the account’s “edit info” [screen](https://partners.viber.com/). ## Channel Configuration The easiest way to configure your Conversation API **app** to use the Viber Bot channel to use [Sinch Build Dashboard](https://dashboard.sinch.com/convapi/overview). 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 Sinch Build Dashboard, see [How to add a webhook to a Conversation API app](https://community.sinch.com/t5/Conversation-API/How-to-add-a-webhook-to-a-Conversation-API-app/ta-p/8100). ### Setup Viber Bot integration using the API To setup the Viber Bot channel using API calls, you must [update](/docs/conversation/api-reference/conversation/app/app_updateapp) (or, if you are making a new **app**, [create](/docs/conversation/api-reference/conversation/app/app_createapp)) 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: ```json { "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 Sinch Build Dashboard when configuring your Viber Bot channel or by adding `"callback_secret": ""` 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](/docs/conversation/callbacks). ## 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](#opt-in)), or if you [receive a message](#receiving-messages) 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**](/docs/conversation/channel-support/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: ![Text Message](/assets/viber_text_message.8563c96b5cd4d587486c5570b090e731cce4e9d6ecf83c33c24bac5a1961541e.19b3a1df.png) The code to send a text message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/text-message). ### 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. ![Media Message](/assets/viber_media_message.ae152221fe44635cba83658f7ebcceef99706af3ffbfaedd3a37027a099ddc47.19b3a1df.png) The code to send a media message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/media-message). ### 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: ![Choice Message](/assets/viber_choice_message.523aeb85e02749715b2e687cdec448166e6cbce4956161ff5b07cb3ce98a162a.19b3a1df.png) The code to send a choice message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/choice-message). ### 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: ![Card Message](/assets/viber_card_message.1e1c3349efe0ede80b9f0dd0169fb79d93a18ad3bcc940945835f123d34f4e50.19b3a1df.png) The code to send a card message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/card-message). ### Carousel Messages Viber Bot channel natively supports carousel messages. The following image gives an example of a carousel message. ![Carousel Message](/assets/viber_carousel_message.4a5483c7ec380147766175b3339d4d46176b00dcf05b643071edab7606c6dbc0.19b3a1df.png) The code to send a carousel message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/carousel-message). ### Location Messages Viber Bot channel natively supports location messages. The following image gives an example of a location message. ![Location Message](/assets/viber_location_message.3342998fa2db4a85b3b9ff10087a1d83462d6142c7c00356d3498d6389b08bcd.19b3a1df.png) The code to send a location message for this channel doesn't differ from the generic message and can be viewed [here](/docs/conversation/message-types/location-message). ## 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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "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: ```json { "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" } } ```