# Buttons

Buttons are configurable UI components displayed on the call screen or keypad based on [conditions](conditions.md). When pressed, buttons invoke associated [functions](function-reference.md).

## JSON Schema

Button definitions are part of the main Functions Framework schema, available [here](https://schemas.acrobits.net/core/functions/input.json).

## Button Configuration

Each button is a JSON object with the following fields:

| Field | Required | Description |
|-------|----------|-------------|
| `id` | Yes | Unique identifier — at least 2 characters, lowercase letters, numbers, and underscores only. |
| `definition` | Yes | Object defining interactions, location, and style (see below). |
| `condition` | No | [Condition](conditions.md) determining button visibility or activity state. If omitted, the button is always visible. |

---

## Definition Properties

### interactions

Defines which function is triggered by each gesture. Functions are referenced by their `id`.

| Gesture | Description |
|---------|-------------|
| `press` | Standard tap/click. |
| `longPress` | Long press gesture. |

```json
"interactions": {
    "press": { "id": "openBrowser" },
    "longPress": { "id": "startRecording" }
}
```

### location

Specifies where the button appears in the UI.

| Property | Values | Description |
|----------|--------|-------------|
| `keypad` | `voiceMail`, `call`, `gsmCall` | Show on the specified keypad slot. |
| `callScreen` | `custom1` – `custom6` | Show on the specified call screen slot. |

```json
"location": {
    "@": "keypad",
    "slot": "call"
}
```

```json
"location": {
    "@": "callScreen",
    "slot": "custom1"
}
```

### style

Defines the visual appearance of the button.

**labels** — Text displayed on the button:

| Property | Description |
|----------|-------------|
| `normal` | Required. Default label. |
| `active` | Optional. Label when the button is in an active state. |

```json
"labels": {
    "normal": { "raw": "Echo test" }
}
```

**icons** — Icons for each button state:

| Property | Description |
|----------|-------------|
| `normal` | Required. Default icon. |
| `hover` | Optional. Icon on hover. |
| `pressed` | Optional. Icon when pressed. |
| `active` | Optional. Icon when active. |
| `disabled` | Optional. Icon when disabled. |

Each value is an asset reference — either a URL or platform-specific theme asset names.

Icon from URL:

```json
"icons": {
    "normal": {
        "url": "https://example.com/icon.png"
    }
}
```

Icons from portal theme:

```json
"icons": {
    "normal": {
        "android": "call_functions_button_custom_0",
        "ios": "call_functions_button_custom_0",
        "desktop": "desktopth_call_functions_button_custom_0"
    },
    "hover": {
        "android": "call_functions_button_custom_0",
        "ios": "call_functions_button_custom_0",
        "desktop": "desktopth_call_functions_button_custom_0_hover"
    },
    "pressed": {
        "android": "call_functions_button_custom_0",
        "ios": "call_functions_button_custom_0",
        "desktop": "desktopth_call_functions_button_custom_0_hover"
    }
}
```

**tooltip** — Tooltip text shown on hover. Required.

```json
"tooltip": {
    "raw": "Echo test"
}
```

---

## Complete Example

A button visible when a call is established, placed on the keypad call slot, that invokes the `echo_test` function on press:

```json
{
    "buttons": [
        {
            "id": "call_button",
            "definition": {
                "interactions": {
                    "press": { "id": "echo_test" }
                },
                "location": {
                    "@": "keypad",
                    "slot": "call"
                },
                "style": {
                    "labels": { "normal": { "en": "Call" } },
                    "icons": { "normal": { "uri": "icon_call.png" } },
                    "tooltip": { "en": "Make a Call" }
                }
            },
            "condition": {
                "@": "callState",
                "state": "established"
            }
        }
    ]
}
```