Chat Extensions are search oriented bots that allow users to interact and share content all from within a chat screen. Users access Chat Extensions by tapping on the search icon in their conversation.
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.
This version of Chat Extensions is formally called Chat Extensions version 2, and is available from Viber version 6.8.7 and newer. Chat Extensions is available on iOS and Android devices.
A Chat Extensions search will lead to two different user flows, depending on the type of service you provide.
Based on a search query, the user will receive an interactive grid. If the user doesn’t submit a search query they are shown a set of default results, based on service preferences (top trending, new, and so on). Tapping on one of the keyboard items will provide more information or several options for actions in the form of a second keyboard. This format is suitable for songs, videos or images for example. Users can share their findings as a Carousel content (rich message).
Example flow – Music chat extension
Based on a search query, the user will receive an interactive grid. Tapping on an option will redirect the user to an internal browser with their findings. This interface is most suitable for more complex searches and actions for example deep navigation and custom searches (e.g. booking tickets, eCommerce and so on). This option is the most flexible of the interface options.
Note: You may provide a combination of interfaces - i.e. a navigational keyboard can lead to a web interface at the end of the navigation funnel, all with the option to share in the chat.
Example internal browser flow – Sports tickets chat extension:
A service is the Chat Extension you are providing. When a user taps on the Chat Extensions icon, a list of all available services is displayed at the bottom 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.
Please consider this list before you start connecting your Chat Extension.
Before you start attaching your Chat Extension You must have:
Testing is on the Production environment. In order to create your service and have access to it you must provide Viber with:
PNG.If you already have a Public Account you will not need to open a new account for your Chat Extension. When submitting your request for a Chat Extension, provide the details of your existing Public Account.
Once you have been granted the Chat Extension, this API provides the code you need in order to differentiate between requests arriving from the Public Account interface and requests originating from the Chat Extension interface.
Chat Extensions are based on a similar API to the Viber Chat bots. This document assumes you are familiar with this API. However, in order to indicate that this solution is a Chat Extension, you must set the is_inline parameter as true to the “set webhook” method. See below for more information about how to set the is_inline paramter on different API libraries.
| Name | Description | Validation |
|---|---|---|
| url | Chat Extension 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 examplebot.setWebhook('https://my.host.com', true);set_webhook exampleviber.set_webhook('https://my.host.com', true)The send_message API allows the Chat Extension to send responses to users who have submitted a search query.
The API supports a variety of message types: text, picture, video, file, location, sticker, contact, carousel content and URL. Specific post data examples and required parameters for each message type are given below.
There are three variations to send messages. Variations 2 and 3 are relevant for Chat Extensions.
receiver only - for use with Public Accounts only. (Requires subscription to the Public Account).chat_id only - message sent to all participants in the inline conversation, requires reply_type message.chat_id and receiver - message is sent to the sender of the message in the specific conversation, requires reply_type query (Keyboard only).The Chat API allows users to submit search queries to the Chat Extension. Excluding file type, all message types are supported for sending from Chat Extension to user and from users to Chat Extensions. These include: text, picture, video, contact, URL and location. The callback data, which contains the search query, will be accessiable via
Messages will arrive via the message event. Read more about it on the specific API guide (REST, Node.JS, Python).
Viber offers message status updates for each message sent, allowing the Chat Extension to be notified when the message was delivered to the user’s device (delivered status) and when the conversation containing the message was opened (seen status).
If the message recipient is using their Viber account on multiple devices, each of the devices will return a delivered and a seen status. This means that several callbacks can be received for a single message.
Chat Extensions receive delivered/seen callbacks as follows:
reply_type = messagereply_type = queryIf Viber is unable to deliver the message to the client it will try to deliver it for up to 14 days. If the message wasn’t delivered within the 14 days it will not be delivered and no delivered or seen callbacks will be received for it.
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.
The Viber API allows sending a custom keyboard using the send_message API, to supply the user with a set of predefined replies or actions. The keyboard can be attached to any message type or sent on it’s on. Once received, the keyboard will appear to the user instead of the device’s native keyboard.
The keyboards are fully customizable and can be created and designed specifically for the PA’s needs.
The client will always display the last keyboard that was sent to it.
Read the following article to learn more about keyboards.