# 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

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

### Adding Image to Button

```json
{
  "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

---

## Related Documents

- **Reference:** [Viber Bot API - Keyboards](https://developers.viber.com/docs/api/rest-bot-api/#keyboards) — official Viber documentation about keyboards
- **Reference:** [Viber Bot API - Rich Media](https://developers.viber.com/docs/api/rest-bot-api/#rich-media) — official Viber documentation about Rich Media
- **Explanation:** [Viber Start Message](/en/scenariodialog/explanation/viber-start-message.md) — features of working with Viber