Viber API Documentation7.3.0

Docs / Tools / Chat Extensions

Chat Extensions

Introduction

A Chat Extension is a Viber bot that allows users to search, interact and share content from within a conversation screen by tapping on the button in the Viber app.

Chat Extensions are available only for IOS and Android devices with Viber version 6.8.7 or higher.

Please note: Chat Extensions are designed to allow selected partners who we work closely with to provide search services for users within chats.

The images, photos, pictures etc. displayed herein are for illustration purposes only.

Glossary

Service

A service is the Chat Extension you are providing. When a user taps on the button, a list of all available services is displayed at the center of the screen.

Hint text

This is a short descriptive text displayed in the input field when the service has been tapped on by a user, guiding the user for their input before entering a text. For example “search for a video”. The hint text is limited to 25 characters including spaces. Hint text is a native field presented by the Viber client and can be localized into any Viber supported language.

Service name

This is the short name of your service displayed under the service’s icon when Chat Extensions is opened by a user. The service name is displayed in any message sent through the service. For example, Sent via <service name>. The service name is limited to 10 characters including spaces.

Service id/uri

This is the account identifier used in all links to the Chat Extension. The id is created from the Chat Extension’s service name, and must be in the Latin alphabet. More about their usage in the deep link section.

Default keyboard

If no query is entered, the keyboard will display default results, for example trending, most recent, last viewed and so on.

Search results

Once a user has sent a search query, navigating between the different services will provide results that are fitted to his search query on the previous service. Results are displayed on the first keyboard sent to the user when the service is chosen.

Inline conversation

An inline conversation with a Chat Extension takes places within the context of a chat between two users or a group conversation.

Create a Chat Extension

  1. Submit a request - chat Extension bots are available only to selected Viber partners ,since we can integrate only a limited number of Chat Extensions in our app. If you’re existing Viber partner and would like to consider developing a chat extension please contact your business account manager at Viber or partners@viber.com

  2. Configure a new bot - Chat Extensions are a type of bot. You will make this bot a Chat Extension by following the steps outlined in the section “Start Development”. To Create the bot itself, please follow these steps:
    1. Go to our admin panel and login using the phone number used with your Viber account.
      • For new partners - contact partners@viber.com
      • For existing partners - user partners dashboard to create a new bot
    2. Select Menu-> Create Bot Account
    3. Fill all required information in the form
    4. Save you authentication token for later use: (looks like 4a11d0412127d47b-25725b610c785d44-f1ed5116412b8e32)
  3. Send us your Chat Extension information - please send your business account manager at Viber, or to partners@viber.com, the following information:
    1. Chat Extension icon image - should be a 720 X 720 pixels PNG format image file.
    2. Display name - shown in the list of available services when users tap the button. Up to 10 characters including spaces.
    3. Hint text - to be displayed inside the search field. Maximum length of 25 characters (including spaces). Please specify whether it is intended to be in multiple languages, and if so please send the translations if you have them.
    4. List of your developers phone numbers - Will be used to add your Chat Extension to your developers Viber accounts for them to test it (numbers can be of any Viber account that you wish to use for testing).

If you’re sending the information directly to partners@viber.com, please include your bot URI and Viber phone number as well.

Note: after updating the icon and hint text of your bot, you can refresh them by changing the language of your device OS, and then change it back.

For users who open the Chat Extension for the first time, this won’t be necessary, and they will see the latest icon and hint text right away.

Important note for bot developers: Viber’s bot platform is open and free for developers to create bots in our ecosystem. Once you’ve created your bot you are welcome to share it with your Viber contacts or promote it outside Viber on your website or social media channels. Please note that Viber is not responsible for promoting your bot.

Start development

Chat Extensions are based on a similar API to the Viber chat bots. We highly recommend that you familiarize yourselves with the Viber Chat bot API prior to developing your chat extension.

Below are the relevant steps and best practices for developing a chat extension using this API.

Note: If you have development and Production versions of your solution running in parallel, you should create separate bots for each, with a seperate webhook URL as well.

Setting a Webhook

When sending a set_webhook request to https://chatapi.viber.com/pa/set_webhook, to indicate that this solution is a Chat Extension, you must include the is_inline parameter.

After setting the webhook, the Chat Extension will receive a callback with the user’s location each time an Android user opens it. Let us know if you wish to disable this behavior (which also disables the location-picker ActionType). The following parameters must be sent in the set_webhook request body:

Name Description Validation
url required. Account webhook URL to receive callbacks & messages from users Webhook URL must use SSL Note: Viber doesn’t support self signed certificates
is_inline Indication of a Chat Extension true for Chat Extension

REST API set_webhook example

{  
   "url": "https://my.host.com",  
   "is_inline" : true
}

Node.JS API set_webhook example

const bot = new ViberBot({
	authToken: YOUR_AUTH_TOKEN_HERE,
	name: "EchoBot",
	avatar: "http://viber.com/avatar.jpg" // It is recommended to be 720x720, and no more than 100kb.

});

bot.setWebhook('https://my.host.com', true);

Python API set_webhook example

from viberbot import Api
from viberbot.api.bot_configuration import BotConfiguration

bot_configuration = BotConfiguration(
	name='PythonSampleChatExtension',
	avatar='http://viber.com/avatar.jpg',
	auth_token='YOUR_AUTH_TOKEN_HERE'
)
viber = Api(bot_configuration)

viber.set_webhook('https://my.host.com', is_inline=True)

Receive search queries from users

Users’ search queries will be received by the Chat Extension as ‘text’ type messages, with the users’ search query being the text of the message.

The message event will be fired when messages arrive. Read more about it on the specific API guide (REST, Node.JS, Python).

Excluding file type, all message types are supported for sending from users to Chat Extensions. These include: text, picture, video, contact, URL and location.

Send keyboards

Chat Extensions are able to send and display keyboard messages. The keyboards are fully customizable and can be created and designed specifically for the Chat Extension’s needs. Please read the following article to learn more about keyboards.

Keyboards you send will appear in the Chat Extension’s results area (under the search field) if the following requirements are met:

  1. The parameter reply_type of the last message event callback that was received by the Chat Extension had the value query. Messages with this reply_type value can be sent in the following ways:
    • When users submit search queries in the Chat Extension
    • When users tap keyboard buttons that have the parameter ReplyType": "query.
  2. No keyboards were sent after receiving the last message event callback that was received by the Chat Extension.
  3. Message type is keyboard. Please read the following article to learn more about keyboards.
  4. Message body must include the parameters chat_id and receiver. The correct values for these parameters can be found in the following way:
    1. On your mobile, open the Chat Extension, search anything.
    2. Confirm the message with "reply_type": "query" was received by your bot.
    3. In the above request, find the chat_id parameter value, and the receiver parameter value is the value of the requerst’s id parameter.

Examples of keyboard messages with the above parameters:

REST API keyboard message example

{
   "auth_token": "XXXX",
   "chat_id": "XXXX",
   "receiver":"XXXX",
   "min_api_version": 2,
   "tracking_data": "YOUR_TRACKING_DATA",
   "type":"keyboard",
   "keyboard":{
      "Type":"keyboard",
      "DefaultHeight":true,
      "Buttons":[
         {
            "ActionType":"reply",
            "ActionBody":"reply to me",
            "Text":"Key text",
            "TextSize":"regular"
         }
      ]
   }
}

Node.JS API keyboard message example

const SAMPLE_KEYBOARD = {
    "receiver":"XXXX",
    "chat_id": "XXXX",
	"Type": "keyboard",
	"Revision": 1,
	"Buttons":[
         {
            "ActionType":"reply",
            "ActionBody":"reply to me",
            "Text":"Key text",
            "TextSize":"regular"
         }
      ]

};

const your_keyboard= new KeyboardMessage(SAMPLE_KEYBOARD);

bot.on(BotEvents.MESSAGE_RECEIVED, (message, response) => {
	response.send(your_keyboard);
});

Python API keyboard message example

VIBER_GENERAL_KEYBOARD = {
	"Type": "keyboard",
	"Buttons":[
         {
            "ActionType":"reply",
            "ActionBody":"reply to me",
            "Text":"Key text",
            "TextSize":"regular"
         }
      ]
}
message=KeyboardMessage(tracking_data='your_tracking_data',
			keyboard=VIBER_GENERAL_KEYBOARD)

viber.send_messages(to=receiver, messages=[
	message
],chat_id='XXXX')

Message receipts callbacks

Viber offers message status updates for each message sent, allowing the Chat Extension to be notified when the inline message was delivered to the user’s device (delivered status). The seen callback isn’t sent for keyboard type messages.

Chat Extensions can be accessed by deep links from both within a conversation and from outside Viber. These deep links direct users to specific locations in Chat Extensions.

There are three scenarios within deep links.

Scenario 1: viber://chatex

In this scenario, a user is directed to open the Chat Extensions screen.

From inside a chat they are shown the default screen (either the last selected Chat Extension, or in the case of a first time user, the first Chat Extension in the list).

From outside Viber the forward screen is displayed and the user can choose the contact or group for a conversation. Once in this chat the user is shown the default Chat Extensions screen.

Scenario 2: viber://chatex?service=<service_id>

In this scenario the user is directed to a particular service within Chat Extensions.

From inside a chat they are directed to the Chat Extension and shown the Chat Extension’s default results.

From outside Viber the forward screen in displayed and the user can choose the contact or group conversation. Once in this chat, the user is directed to the Chat Extension and shown the default results for this Chat Extension.

Scenario 3: viber://chatex?service=<service_id>&search=<search_term>

In this scenario, a user is directed to a particular Chat Extension with a specified search term.

From inside a chat they are directed to the Chat Extension and the results shown will relate to the search query.

From outside Viber the forward screen in displayed and the user can choose the contact or group conversation. Once in this chat, the user is directed to the Chat Extension and the results shown will relate to the search query.

Best practices & How-to’s

Send a default results keyboard

Configure your Chat Extension to send a keyboard on a message event, and if the message reply_type is query and the text parameter is not included in the message object.

Send a search results keyboard

Configure your Chat Extension to send a keyboard on a message event, and if the message reply_type is query and the text parameter is included in the message object. The text parameter’s value is the user’s search query.

Detect from which keyboard a message was sent

You can specify the user’s current keyboard in the tracking_data parameter of the keyboard message.

This way, when the user taps a button on a keyboard or rich media that has the tracking_data parameter, the value of tracking_data will be sent with the message to the Chat Extension and allow you to identify the specific button or message the user interacted with.

Example of a keyboard message with the tracking_data parameter:

{
   "auth_token": "XXXX",
   "chat_id": "XXXX",
   "receiver":"XXXX",
   "min_api_version": 2,
   "tracking_data": “YOUR_TRACKING_DATA”,
   "type":"keyboard",
   "keyboard":{
      "Type":"keyboard",
      "DefaultHeight":true,
      "Buttons":[
         {
            "ActionType":"reply",
            "ActionBody":"reply to me",
            "Text":"Key text",
            "TextSize":"regular",
            "ReplyType": "query"
         }
      ]
   }
}

Implement a ‘next page’ in the chat extension

To display a keyboard in the Chat Extension in response to a button tap in another keyboard, you should specify "ReplyType": "query" on the button in the first keyboard.

This allows the response from your bot to be displayed in the Chat Extension.

Example of a keyboard message with a button that has the “ReplyType”:”query” parameter:

{
    "auth_token": "XXXX",
    "receiver": "XXXX",
    "chat_id": "XXXX",
    "min_api_version": 2,
    "tracking_data": "current_page=main_menu",
    "keyboard": {
        "Buttons": [
            {
                "Columns": 3,
                "Rows": 1,
                "ActionType": "reply",
                "ActionBody": "next_page",
                "Text": "Next Page",
                "Silent": true,
                "ReplyType": “query”
            }
        ]
    }

}

Setting flags

Flags are back-end settings that can modify the functionality of your Chat Extension.

Available flags

RA - Modified Recent logic. Enables recent logic after keyboard activity (default is only after message is sent). By default, a Chat Extension service is added to the “Recents” bar if a user sends a message using that Chat Extension. If this is flag is active, the Chat Extension service will be added to Recents bar right after an interaction with a sent keyboard, and not only when a user sends a message from the Chat Extension.

DS - Disables search. Removes Search button from Chat Extension keyboard. You will still receive a message event callback with "reply_type": "query" when a user taps on the service icon, and can respond to it with a keyboard.

DI - Disables input. Disables input field in Chat Extension keyboard. You will still receive a message event callback with "reply_type": "query" when a user taps on the service icon, and can respond to it with a keyboard.

How to set flags

  1. Use your bot’s authentication token, that you created in step 2 of the above section “Create a Chat Extension”.
  2. Send the following request to https://chatapi.viber.com/pa/set_account_info:
{
"auth_token": "YOUR_AUTH_TOKEN",
"chat_flags":["DI","DS","RA"]
}

The above request will apply all 3 flags (DS DI RA). If you wish to set only some of them, simply include only the ones you need in the chat_flags parameter, or set it to [] to remove all flags.

Notes:

  1. After sending the above request, it will take approximately 5 minutes for the flags to be updated.
  2. To view the effect of the flags, you will need to do one of the following:
    1. Change your device’s language or date.
    2. Ask us to add the Chat Extension’s URI to another device, and then see the changes on that device.
    3. Create an entirely new bot, add the flags to it and ask us to add the new bot’s URI to your number. Then you’ll be able to see the flags’ effect on this new Chat Extension.

Publish your Chat Extension

For further information on how to publish your chat extension for Viber users, please contact us at partners@viber.com