Triggers¶

Triggers are observable events within the application that automatically invoke one or more functions. 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.

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.

{
    "@": "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.

{
    "@": "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.

{
    "@": "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.

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

Added in 25.3

Key Press¶

Fires when a keyboard, media, or gamepad key is pressed. Use it for hardware buttons, keyboard shortcuts, headset buttons, remote controls, and other HID input that should invoke a function.

Type: keyPress

Field	Type	Description
`event`	Object	Key press to match. See Keyboard events, Media events, and Gamepad events.
`target`	Object	Screen or application area where the key press should be handled. See Targets.

Keyboard Events¶

Keyboard events use @ set to keyboard and either a named key or numeric platform code. Named keys are listed in Keyboard Keys. Optional modifiers are listed in Keyboard Modifiers.

{
    "@": "keyboard",
    "key": "ENTER",
    "modifiers": [
        "CTRL"
    ]
}

{
    "@": "keyboard",
    "code": 160
}

Media Events¶

Media events use @ set to media and a key from Media Keys.

{
    "@": "media",
    "key": "HEADSETHOOK"
}

Gamepad Events¶

Gamepad events use @ set to gamepad and a key from Gamepad Keys.

{
    "@": "gamepad",
    "key": "BUTTON_A"
}

Targets¶

Target	Fields	Description
`global`	—	Matches regardless of the current screen.
`settings`	—	Matches while settings are active.
`callScreen`	—	Matches while the call screen is active.
`homeScreen`	Optional `tab` string	Matches while the home screen is active. If `tab` is present, only that home-screen tab matches.

Example¶

{
    "@": "keyPress",
    "event": {
        "@": "media",
        "key": "HEADSETHOOK"
    },
    "target": {
        "@": "homeScreen",
        "tab": "keypad"
    }
}

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.

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

Added in 25.3