Viber API Documentation7.3.0

Docs / Tools / DeepLinks

Deeplinks

Bot can have deeplinks to direct users to different parts of the bot.

Deeplinks require specifying the URI of your bot. It can be found in the your bot’s Admin Panel or in the response to the get-account-info API request.

There are three types of deeplink available.

Tapping this type of link will open a conversation with the bot and trigger a conversation started event.

The scheme for this link is:

viber://pa?chatURI=<URI>

Tapping this link will open the bot on the info screen. This deeplink is supported on Android and iOS, and is not supported on Desktop.

The scheme for this link is:

viber://pa/info?uri=<URI>

Additional parameters

The bot is able to accept two additional parameters in the deeplink:

Context

The value of this parameter will be forwarded to the bot under the context parameter in the conversation started callback (see conversation started for additional details). The context will be transferred as a string and has no length limit (up to URL length limit).

Text

The value of this parameter will appear in the text input field when the 1-on-1 chat with the bot is opened by pressing the deeplink. The user will be able to send the text as it is, edit it, or delete it.

A deeplink with context parameter will look as follows:

viber://pa?chatURI=<URI>&context=<Your Context>&text=<Your Text>

Note: Some browsers might have a problem identifying the deeplink. To make sure the link works try sending it as a Viber message and pressing it from within Viber.

Chatbot QR scanner

Introduction

Bot subscribers can scan a QR code using Viber’s native QR scanner and share the scanned data with the bot. This means subscribers don’t need to be redirected to an external browser, allowing for a secure and seamless user journey with fewer steps required to complete the process.

The feature takes advantage of Viber’s existing native QR scanner functionality via a URL scheme and allows for the data to be shared with the bot, which can be utilized for numerous use cases:

URL scheme

The URL scheme is:

viber://pa/qr?chatURI=<URI>

There are two possible entry point to the flow that you can provide users with:

When the user agrees to share the scanned data with the bot, it will trigger a conversation_started event. Note that this is not equal to a subscribed event. The conversation_started event will be fired even if the user is already subscribed to the bot. It’s up to you to decide when you’d like to respond to the conversation_started event and when not, based on the user’s status (subscribed or not).

Limitations

Android: Viber 17.1.0.6 and above.
iOS: Viber 17.2 and above.
Desktop: Not supported.

If a user clicks your deeplink on their computer, they will receive the following message (provided they have Viber for Desktop installed):

User journey

1. The user clicks on an external link (outside of Viber) or on a button in a conversation with the bot.
2. The flow is triggered and Viber’s native QR scanner is activated.
3. Once a QR code is recognized and scanned, the user will see a prompt: “Send QR data to: chatURI ? ”.

We recommend setting the silent flag to true. Otherwise, when the user scans the QR code, a message will be sent to the bot consisting of the URL scheme.

Callback example

When the user sends the scanned data to the bot, the callback will look as follows:

{
  "event": "message",
  "timestamp": 1654676100708,
  "chat_hostname": "SN-CALLBACK-03_",
  "message_token": 5715235489597870374,
  "sender": {
    "id": "jc9HsWTZ2Yf2NkRZ8KcNug==",
    "name": "Michael Brown",
    "avatar": "https://avatar.example.com",
    "language": "en",
    "country": "IL",
    "api_version": 10
  },
  "message": {
    "text": "QR data:\n\nYour electricity bill has been paid. Account no. 10901213, amount paid $39.75",
    "type": "text",
    "tracking_data": "tracking data"
  },
  "silent": false
}

The message type in the callback will be text, even if the scanned QR code represents a file. For example, if the QR code leads to a PDF file, the text parameter will include the file’s URL address and the type parameter will be “text.”

IMPORTANT: You will need to set your bot to recognize the “QR Data:” prefix in order to trigger the appropriate response.

Use case examples

In-chat button (rich media message)

{
   "receiver":"K917PBuvPZmhKfb8Vw3b2Q==",
   "type":"rich_media",
   "min_api_version":7,
   "rich_media":{
      "Type":"rich_media",
      "ButtonsGroupColumns":6,
      "ButtonsGroupRows":1,
      "BgColor":"#1ce783",
      "Buttons":[
         {
            "Columns":6,
            "Rows":1,
            "Silent":"false",
            "ActionType":"open-url",
            "ActionBody":"viber://pa/qr?chatURI=examplebot",
            "Text":"<font color=#ffffff>Scan QR Code Now</font>",
            "TextSize":"large",
            "TextVAlign":"middle",
            "TextHAlign":"middle",
            "Image":"https://i.imgur.com/TePDXXu.png"
         }
      ]
   }
}

Keyboard button

{
   "receiver":"B/dQ7y+3akqZtBBp6Hiy/g==",
   "min_api_version":7,
   "type":"text",
   "text":"To pay your bill, please tap on the button below.",
   "keyboard":{
      "Type":"keyboard",
      "DefaultHeight":false,
      "Buttons":[
         {
            "ActionType":"open-url",
            "ActionBody":"viber://pa/qr?chatURI=examplebot",
            "Text":"<b>Scan QR Code Now</b>",
            "TextSize":"large",
            "TextVAlign":"middle",
            "TextHAlign":"center",
            "BgColor":"#1ce783",
            "Silent":"true"
         }
      ]
   }
}

Data

Please keep in mind that as the bot developer, the code’s functionality is your responsibility, so it will be up to you to generate QR codes that you can parse correctly. Viber is merely providing an easy way for subscribers to scan QR codes and share the data with bots. We highly recommend that you test each code before implementing it, to make sure that it works. We recommend that you keep record of the messages you receive from users, as there is no API to fetch this data again.

Additionally, it’s your responsibility to ensure that your bot is set up to handle unexpected data, such as when a subscriber scans a QR that isn’t related to your bot.