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.
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.
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.
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.
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.
If no query is entered, the keyboard will display default results, for example trending, most recent, last viewed and so on.
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.
An inline conversation with a Chat Extension takes places within the context of a chat between two users or a group conversation.
Submit a request - Chat Extensions 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
button. Up to 10 characters including spaces.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 on your device 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.
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.
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 |
set_webhook example{
"url": "https://my.host.com",
"is_inline" : true
}set_webhook exampleconst bot = new ViberBot({
authToken: YOUR_AUTH_TOKEN_HERE,
name: "EchoBot",
avatar: "https://viber.com/avatar.jpg" /* It is recommended to be 720x720, and no more than 100kb. */
});
bot.setWebhook('https://my.host.com', true);set_webhook examplefrom viberbot import Api
from viberbot.api.bot_configuration import BotConfiguration
bot_configuration = BotConfiguration(
name='PythonSampleChatExtension',
avatar='https://viber.com/avatar.jpg',
auth_token='YOUR_AUTH_TOKEN_HERE'
)
viber = Api(bot_configuration)
viber.set_webhook('https://my.host.com', is_inline=True)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.
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:
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:
"ReplyType": "query".keyboard. Please read the following article to learn more about keyboards.chat_id and receiver.
The correct values for these parameters can be found in the following way:
"reply_type": "query" was received by your bot.chat_id parameter value, and the receiver parameter value is the value of the requerst’s id parameter.message event callback that was received by the Chat Extension that had "reply_type": "query".Examples of keyboard messages with the above parameters:
{
"auth_token": "XXXX",
"chat_id": "XXXX",
"receiver":"XXXX",
"min_api_version": 2,
"tracking_data": "YOUR_TRACKING_DATA",
"keyboard":{
"Type":"keyboard",
"DefaultHeight":true,
"Buttons":[
{
"ActionType":"reply",
"ActionBody":"reply to me",
"Text":"Key text",
"TextSize":"regular"
}
]
}
}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, [optionalTrackingData or null], null, null, [minApiVersion, integer above 2]);
bot.on(BotEvents.MESSAGE_RECEIVED, (message, response) => {
response.send(your_keyboard);
});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')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=<URI>
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=<URI>&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.
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.
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.
You can use the send_message API to send messages to the chat between 2 users, by not including the receiver parameter and including the chat_id parameter in the request. You can find the value of the chat_id parameter in the message callback recieved after the user interacts with keyboards in the chat extension, or types search strings in the chat extension.
You will only be able to send messages into the chat a short time after one of the user in the chat interacted with the chat extension (opened it, searched anything, tapped on any buttons).
To take users back to the chat to see the message that was sent to it, you can implement a keyboard button that minimizes the chat extension by including the button parameter ”ReplyType”:”message”, and let users tap it in order to send the message to the chat and be taken back to the chat immediately.
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"
}
]
}
}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"
}
]
}
}Flags are back-end settings that can modify the functionality of your Chat Extension.
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.
{
"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:
For further information on how to publish your chat extension for Viber users, please contact us at partners@viber.com