# Triggers

Triggers are observable events within the application that automatically invoke one or more [functions](function-reference.md). Each trigger listens for a specific event — such as a call state transition, a hold state change, or a provisioning update. When the event occurs, the associated function is executed.

## JSON Schema

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

---

## Call State

Fires when an active call transitions to the specified state.

**Type:** `callState`

| Field | Type | Description |
|-------|------|-------------|
| `state` | String | The call state to react to (see Call FSM for possible values). |

**Example use cases:** Display caller info in a browser tab when ringing. Start server-side recording when a call is established. Log call transitions for debugging.

```json
{
    "@": "callState",
    "state": "incomingAnswered"
}
```

---

## Hold

Fires when the hold state of an active call changes.

**Type:** `hold`

| Field | Type | Default | Description |
|-------|------|---------|-------------|
| `whenHeld` | Boolean | — | `true` — triggers only when the call is put on hold. `false` — triggers only when the call is taken off hold. If omitted, triggers on every hold state change. |

```json
{
    "@": "hold",
    "whenHeld": false
}
```

---

## Transfer

Fires when a call transfer is started, completes, or fails.

**Type:** `transfer`

| Field | Type | Description |
|-------|------|-------------|
| `state` | `Started`, `Successful`, `Failed` | Which transfer state should trigger the function. |

```json
{
    "@": "transfer",
    "state": "Successful"
}
```

---

## Reprovision

Fires when the reprovisioning process reaches a specified state.

**Type:** `reprovision`

| Field | Type | Description |
|-------|------|-------------|
| `eventType` | `AfterCompleted` | The provisioning event to react to. |

```json
{
    "@": "reprovision",
    "eventType": "AfterCompleted"
}
```

!!! note "Added in 25.3"

---

## Group Event

Fires when a call group changes — for example, when a group is created or removed, or when calls are added to or removed from a group. Useful for tracking multi-call scenarios.

**Type:** `groupEvent`

| Field | Type | Description |
|-------|------|-------------|
| `event` | `groupCreated`, `callAdded`, `callRemoved`, `groupRemoved` | The group event to react to. |

```json
{
    "@": "groupEvent",
    "event": "groupCreated"
}
```

!!! note "Added in 25.3"