Viber API Documentation7.2.0

Docs / Tools / Keyboards

Keyboards

The public accounts API allows sending a custom keyboard with each message, 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.

Table of Contents

Attaching a keyboard to a message

Keyboards can be attached to any message type and be sent and displayed together. To attach a keyboard to a message simply add the keyboard’s parameters to the message JSON.
The keyboard JSON object defines different visual and logic attributes. From the background color, number of buttons and so on.

The example below shows a keyboard sent with a single message.

{
"keyboard": {
"DefaultHeight": true,
"BgColor": "#FFFFFF",
"Buttons": [{
"Columns": 6,
"Rows": 1,
"BgColor": "#2db9b9",
"BgMediaType": "gif",
"BgMedia": "http://www.url.by/test.gif",
"BgLoop": true,
"ActionType": "open-url",
"ActionBody": "www.tut.by",
"Image": "www.tut.by/img.jpg",
"Text": "Key text",
"TextVAlign": "middle",
"TextHAlign": "center",
"TextOpacity": 60,
"TextSize": "regular"
}]
}
}

Which in turn will look like this:

General keyboard parameters

Please note: The api level 3 is supported on devices running Viber version 7.6 and above. If you use api level 3 parameters you will have to set the min_api_version parameter on right api level as well.

Name Description Possible values Default value
Buttons required. Array containing all keyboard buttons by order. See buttons parameters below for buttons parameters details    
BgColor optional. Background color of the keyboard Valid color HEX value Default Viber keyboard background
DefaultHeight optional. When true - the keyboard will always be displayed with the same height as the native keyboard.When false - short keyboards will be displayed with the minimal possible height. Maximal height will be native keyboard height true, false false
CustomDefaultHeight optional (api level 3). How much percent of free screen space in chat should be taken by keyboard. The final height will be not less than height of system keyboard 40..70  
HeightScale optional (api level 3). Allow use custom aspect ratio for Carousel content blocks. Scales the height of the default square block (which is defined on client side) to the given value in percents. It means blocks can become not square and it can be used to create rich messages with correct custom aspect ratio. This is applied to all blocks in the Carousel content 20..100 100
ButtonsGroupColumns optional (api level 4). Represents size of block for grouping buttons during layout 1-6 6
ButtonsGroupRows optional (api level 4). Represents size of block for grouping buttons during layout 1-7 7 for Carousel content ; 2 for Keyboard
InputFieldState optional (api level 4). Customize the keyboard input field. regular- display regular size input field. minimized - display input field minimized by default. hidden - hide the input field regular, minimized, hidden regular

Buttons parameters

The following parameters can be defined for each button in the “buttons” array separately. Each button must contain at least one of the following optional parameters: text, BgMedia, image, BgColor.

Name Description Possible values Default value
Columns optional. Button width in columns. See keyboard design for more details 1-6 6
Rows optional. Button height in rows. See keyboard design for more details 1-2 1
BgColor optional. Background color of button Valid color HEX value Default Viber button color
Silent optional. Determine whether the user action is presented in the conversation true/false false
BgMediaType optional. Type of the background media picture, gif. For picture - JPEG and PNG files are supported. Max size: 500 kb picture
BgMedia optional. URL for background media content (picture or gif). Will be placed with aspect to fill logic Valid URL  
BgLoop optional. When true - animated background media (gif) will loop continuously. When false - animated background media will play once and stop true , false true
ActionType optional. Type of action pressing the button will perform. Reply - will send a reply to the PA. open-url - will open the specified URL and send the URL as reply to the PA. See reply logic for more details reply, open-url, location-picker, share-phone, none reply
ActionBody required. Text for reply and none. ActionType or URL for open-url. See reply logic for more details For ActionType reply - text For ActionType open-url - Valid URL.  
Image optional. URL of image to place on top of background (if any). Can be a partially transparent image that will allow showing some of the background. Will be placed with aspect to fill logic Valid URL. JPEG and PNG files are supported. Max size: 500 kb  
Text optional. Text to be displayed on the button. Can contain some HTML tags - see keyboard design for more details Free text. Valid and allowed HTML tags Max 250 characters. If the text is too long to display on the button it will be cropped and ended with “…”  
TextVAlign optional. Vertical alignment of the text top, middle, bottom middle
TextHAlign optional. Horizontal align of the text left, center, right center
TextPaddings optional (api level 4). Custom paddings for the text in points. The value is an array of Integers [top, left, bottom, right] per padding 0..12 [12,12,12,12]
TextOpacity optional. Text opacity 0-100 100
TextSize optional. Text size out of 3 available options small, regular, large regular
OpenURLType optional. Determine the open-url action result, in app or external browser internal, external internal
OpenURLMediaType optional. Determine the url media type. not-media - force browser usage. video - will be opened via media player. gif - client will play the gif in full screen mode. picture - client will open the picture in full screen mode not-media , video , gif , picture not-media
TextBgGradientColor optional. Background gradient to use under text, Works only when TextVAlign is equal to top or bottom Hex value (6 characters)  
TextSize optional. Text size out of 3 available options small, regular, large regular
InternalBrowser optional (api level 3). JSON Object, which includes internal browser configuration for open-url action with internal type See below  
InternalBrowser.ActionButton optional (api level 3). Action button in internal’s browser navigation bar. forward - will open the forward via Viber screen and share current URL or predefined URL. send - sends the currently opened URL as an URL message, or predefined URL if property ActionPredefinedURL is not empty. open-externally - opens external browser with the current URL. none - will not display any button forward, send, open-externally, none forward
InternalBrowser.ActionPredefinedURL optional (api level 3). If ActionButton is send or forward then the value from this property will be used to be sent as message, otherwise ignored String with 1 or more characters  
InternalBrowser.TitleType optional (api level 3). Type of title for internal browser if has no CustomTitle field. default means the content in the page’s <OG:title> element or in <title> tag. domain means the top level domain domain, default default
InternalBrowser.CustomTitle optional (api level 3). Custom text for internal’s browser title, TitleType will be ignored in case this key is presented String up to 15 characters  
InternalBrowser.Mode optional (api level 3). Indicates that browser should be opened in a full screen or in partial size (50% of screen height). Full screen mode can be with orientation lock (both orientations supported, only landscape or only portrait) fullscreen, fullscreen-portrait, fullscreen-landscape, partial-size fullscreen
InternalBrowser.FooterType optional (api level 3). Should the browser’s footer will be displayed (default) or not (hidden) default, hidden default

For example if you would like to open the url in internal browser (min_api_version 3):

{
"keyboard": {
"DefaultHeight": true,
"BgColor": "#FFFFFF",
"Buttons": [{
"Columns": 6,
"Rows": 1,
"BgColor": "#2db9b9",
"BgMediaType": "gif",
"BgMedia": "http://www.url.by/test.gif",
"BgLoop": true,
"ActionType": "open-url",
"OpenURLType": "internal",
"InternalBrowser": {
"Mode": "fullscreen",
"CustomTitle": "Hello World - Custom Title"
},
"ActionBody": "www.tut.by",
"Image": "www.tut.by/img.jpg",
"Text": "Key text",
"TextVAlign": "middle",
"TextHAlign": "center",
"TextOpacity": 60,
"TextSize": "regular"
}]
}
}

Note: The Silent parameter is supported on devices running Viber version 6.7 and above.

Keyboard design

The keyboard is divided into 6 columns. Each button has a width of 1-6 columns. The client will display the buttons according to the order they were sent in, and will fit as many buttons as possible into each row. If the next button to display can’t be fitted into the current row it will be displayed in the row below. For landscape mode, keyboard’s width will be doubled to 24 columns, and buttons will be displayed according to the same logic. Button height can be 1-2 rows.

Note: keyboards can contain up to 24 rows.

Text design

The buttons’ text can contain some HTML tags for design purposes. The allowed tags are listed in the table below.

Tag Description
<b>X</b> Bold text
<i>X</i> Italic text
<u>X</u> Underlined text
<br> Line break
<s>X</s> Strikethrough text (api level 4)
<font size=”N”>X</font> Custom size N for text block inside the tag (api level 4). Minimum size is 12, maximum size is 32 .
<font color=”#7F00FF”>X</font> Specific text color. Must be a HEX value. Double quotes in JSON should be escaped.

Adding special characters or spaces at the beginning of the row can be done using Unicode. For example, setting a button’s text that starts with a space should look like this:

"Text": "\u00A0 Button text"

Keyboard Reply logic

Pressing a keyboard button would trigger a different reply depending on the buttons “actionType” value.

For ActionType reply:

For ActionType open-url:

For ActionType share-phone - api level 3 and above:

For ActionType location-picker - api level 3 and above:

For ActionType none:

Note: The none action type is supported on devices running Viber version 6.7 and above.

Keyboard design guidelines

You can learn more about keyboard design guidelines in the following spec.

Keyboard examples

Check our examples section for different keyboard use cases.