About Viber Keyboard Styling

Viber allows configuring keyboard button appearance through JSON configuration. This allows creating visually attractive interfaces with colored buttons, images, and custom formatting.

Context and Problem

In many scenarios, you need to create a visually attractive interface for users:

Colored buttons to highlight important actions
Images on buttons for better understanding
Custom formatting to improve UX
Rich Media messages with combination of texts, images, and buttons

Viber keyboard styling solves this task by allowing configuring button appearance through JSON configuration.

Key Concepts

Styling Types

Viber supports different keyboard styling types:

Button background — background color of all buttons in the keyboard
Individual buttons — color, image, and formatting of each button separately
Rich Media — complex messages with combination of texts, images, and buttons

Configuration Parameters

Main parameters for button styling:

Columns — button width in columns (1-6)
Rows — button height in rows (1-2)
BgColor — button background color
Image — URL of image on button
TextVAlign, TextHAlign — text alignment
ActionType, ActionBody — action type and response body

Approach Options

Regular Keyboard vs Rich Media

Regular keyboard:

✅ Pros: Simple setup, quick implementation
❌ Cons: Limited styling capabilities

Rich Media:

✅ Pros: Maximum flexibility, ability to create complex interfaces
❌ Cons: More complex setup, limitation on total height (7 rows)

Why we use both approaches: Regular keyboard suits simple cases, and Rich Media — for complex interfaces with combination of texts, images, and buttons.

Adopted Solutions

Rich Media Limitations

For Rich Media, the total height of all buttons must equal 7 rows, and width — 6 columns. This is a Viber API requirement for correct Rich Media message display.

Placeholder Support

In Rich Media, you can use placeholder {{broadcast-image}} for dynamic image selection based on user language in broadcasts.

Keyboard Response Logic

Clicking a button triggers different responses depending on ActionType value:

reply — sending text from ActionBody
open-url — opening link from ActionBody
none — button without action

Implications for Users and Implementation

For Integrators

When using Viber keyboard styling, it's important to:

Use high-quality images — recommended x2 or x3 size for clarity
Follow Rich Media limitations — total height must equal 7 rows
Configure correct sizes — Columns and Rows for each button
Check display — test on different devices and screen sizes

Common Errors

Error: Rich Media does not display correctly
Problem: Total height does not equal 7 rows
Solution: Check sum of Rows of all buttons — it must equal 7

Error: Images are blurry
Problem: Low-quality images used
Solution: Use images x2 or x3 size from needed

Error: Button does not perform action
Problem: ActionType or ActionBody is not specified
Solution: Specify correct ActionType and ActionBody in JSON configuration

Limitations

Rich Media works only for Viber
Total height of all buttons must equal 7 rows
Maximum width — 6 columns
Images should have high quality (recommended x2 or x3 size)

Usage Examples

Adding Button Background

{
  "BgColor": "#2db9b9",
  "DefaultHeight": null
}

Adding Image to Button

{
  "Columns": null,
  "Rows": null,
  "BgColor": null,
  "BgMediaType": null,
  "BgMedia": null,
  "BgLoop": null,
  "Image": "https://example.com/image.jpg"
}

Rich Media Structure

Rich Media requires total height of 7 rows:

Header: Rows: 1
Image: Rows: 4
Information: Rows: 1
Button: Rows: 1
Total height: 1 + 4 + 1 + 1 = 7

Reference: Viber Bot API - Keyboards — official Viber documentation about keyboards
Reference: Viber Bot API - Rich Media — official Viber documentation about Rich Media
Explanation: Viber Start Message — features of working with Viber