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:

  1. Use high-quality images — recommended x2 or x3 size for clarity
  2. Follow Rich Media limitations — total height must equal 7 rows
  3. Configure correct sizes — Columns and Rows for each button
  4. 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