Viber API Documentation7.2.0

Docs / Chat Extensions Technical Documentation

Chat Extensions - Technical Documentation

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.

Table of Contents

Supported Versions and Platforms

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.

Example user flows

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 rich message.

Example flow – Music chat extension

  1. The user taps on the Chat Extensions icon from inside a chat with a contact.
  2. The user is shown a set of default results.
  3. The user types in a search query, and submits it by tapping on the search button on the keyboard.
  4. The user taps on the image in the results keyboard that interests them.
  5. The user is shown the item they have chosen with options (in this case share).
  6. The user has chosen share, and it is now displayed in their chat.
  7. The user taps on the shared content and is redirected to a screen to listen to the song.

Web view interface

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:

  1. The user opens a chat with friends.
  2. The user taps on the Chat Extensions icon and chooses a service from the options at the bottom of the screen. The user then chooses the sport they want to see from the keyboard options.
  3. The user types in a search query (the team they want to see).
  4. The user is given a keyboard of options to choose from.
  5. The user chooses to share the items they have seen on the internal browser.
  6. This information is shared in the chat.
  7. The user taps on the shared information and is directed to an internal browser to buy tickets.

Some more chat extension use cases

Search for restaurants

Search for tickets

Search for travel options

Search for videos chat

Glossary

Service

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.

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.

Pre-development Requirements

Please consider this list before you start connecting your Chat Extension.

Before you start attaching your Chat Extension You must have:

  1. An Active Viber account on a platform which supports Public Accounts/ bots (iOS/Android). This account will automatically be set as the account administrator during the account creation process.
  2. Active Public Account/ bot - Create an account here.
  3. Account authentication token - unique account identifier used to validate your account in all API requests. Once your account is created your authentication token will appear in the account’s “edit info” screen (for admins only). Each request posted to Viber by the account will need to contain the token.
  4. Setup account webhook – this needs to be done once during the account setup process to define your webhook and the type of responses you would like to receive.

Testing is on the Production environment. In order to create your service and have access to it you must provide Viber with:

Chat Extension applications who already have a Public Account

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.

API Integration

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

REST API set_webhook example

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

Node.JS API set_webhook example

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

Python API set_webhook example

viber.set_webhook('https://my.host.com', true)

Send Message

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.

Send message modes

There are three variations to send messages. Variations 2 and 3 are relevant for Chat Extensions.

  1. receiver only - for use with Public Accounts only. (Requires subscription to the Public Account).
  2. chat_id only - message sent to all participants in the inline conversation, requires reply_type message.
  3. chat_id and receiver - message is sent to the sender of the message in the specific conversation, requires reply_type query (Keyboard only).

Receive message from user

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).

Message receipts callbacks

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:

If 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.

Keyboards

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.