Class Action
Page Summary
An Action enables interactivity in UI elements by invoking an Apps Script callback function with optional parameters.
Actions are available for Google Workspace add-ons and Google Chat apps.
You can add required widgets, set all widgets as required, and set the name of the callback function for an Action.
Actions also allow setting interaction type (specifically for dialogs in Google Chat), load indicators, and custom parameters.
You can control whether form values persist from the client or are overwritten by server values after an action response.
An action that enables interactivity within UI elements. The action does not happen directly onthe client but rather invokes anApps Script callback functionwith optional parameters.
Available for Google Workspace add-ons and Google Chat apps.
constimage=CardService.newImage().setOnClickAction(CardService.newAction().setFunctionName('handleImageClick').setParameters({imageSrc:'carImage'}),);
Methods
| Method | Return type | Brief description |
|---|---|---|
add | Action | Adds the names of the widgets that this Action needs for a valid submission. |
set | Action | Indicates whether this Action requires inputs from all widgets. |
set | Action | Sets the name of the callback function to be called. |
set | Action | Sets the interaction with a user, only required when opening a dialog. |
set | Action | Sets the loading indicator that displays while the action is in progress. |
set | Action | Allows custom parameters to be passed to the callback function. |
set | Action | Indicates whether form values are determined by the client's values or the server's valuesafter an action response updates the form'sCard. |
Deprecated methods
| Method | Return type | Brief description |
|---|---|---|
| Action |
Detailed documentation
addRequiredWidget(requiredWidget)
Adds the names of the widgets that this Action needs for a valid submission. If the widgets inthis list don't have a value when this Action is invoked, the form submission is aborted.
Available for Google Workspace add-ons and Google Chat apps.
consttextInput=CardService.newTextInput().setFieldName('text_input_1').setTitle('Text input title');// Creates a footer button that requires an input from the above TextInput// Widget.constaction=CardService.newAction().setFunctionName('notificationCallback').addRequiredWidget('text_input_1');constfixedFooter=CardService.newFixedFooter().setPrimaryButton(CardService.newTextButton().setText('help').setOnClickAction(action),);
Parameters
| Name | Type | Description |
|---|---|---|
required | String | The name of the widget required by this Action. |
Return
Action — This object, for chaining.
setAllWidgetsAreRequired(allWidgetsAreRequired)
Indicates whether this Action requires inputs from all widgets.
Available for Google Workspace add-ons and Google Chat apps.
// Creates a button with an action that requires inputs from all widgets.constbutton=CardService.newTextButton().setText('Create notification').setOnClickAction(CardService.newAction().setAllWidgetsAreRequired(true));
Parameters
| Name | Type | Description |
|---|---|---|
all | Boolean | Whether the action requires inputs from all widgets. Defaults tofalse. |
Return
Action — This object, for chaining.
setFunctionName(functionName)
Sets the name of the callback function to be called. Required.
Parameters
| Name | Type | Description |
|---|---|---|
function | String | The name of the function. You can use functions from included libraries, such asLibrary.libFunction1. |
Return
Action — This object, for chaining.
setInteraction(interaction)
Sets the interaction with a user, only required when opening a dialog. If unspecified, the appresponds by executing anAction like opening a link or running a function—as normal.
Only available for Google Chat apps. Not available for Google Workspace add-ons.
constaction=CardService.newAction().setFunctionName('handleDialog').setInteraction(CardService.Interaction.OPEN_DIALOG);
Parameters
| Name | Type | Description |
|---|---|---|
interaction | Interaction | The interaction to specify. |
Return
Action — This object, for chaining.
setLoadIndicator(loadIndicator)
Sets the loading indicator that displays while the action is in progress.
Parameters
| Name | Type | Description |
|---|---|---|
load | Load | The indicator to display. |
Return
Action — This object, for chaining.
setParameters(parameters)
Allows custom parameters to be passed to the callback function. Optional.
Parameters
| Name | Type | Description |
|---|---|---|
parameters | Object | Both keys and values must be strings. |
Return
Action — This object, for chaining.
setPersistValues(persistValues)
Indicates whether form values are determined by the client's values or the server's valuesafter an action response updates the form'sCard. When set totrue, theclient's values persist after the server response. When set tofalse, the server'svalues overwrite the form values. Defaults tofalse.
Persisting the client values helps prevent situations where a form changes unexpectedlyafter a user makes an edit. For example, if a user makes an edit to aText aftersubmitting a form, but before the server responds. If the values are persisted, the edit theuser made remains after the server response updates theCard; otherwise the form valuereturns to the value that the user originally submitted to the form.
Persisting client values can interfere with your script's ability to clear form fields oroverride form values, so avoid turning on persistence for that type of functionality. Withoutpersistence, it's recommended that you use theLoad for events,because this locks the UI and prevents user edits before the server responds. Alternatively,you can useLoad and make sure every element in the form has an onChangeaction.
// Creates a button with an action that persists the client's values as the// on-click action.constbutton=CardService.newTextButton().setText('Create notification').setOnClickAction(CardService.newAction().setPersistValues(true).setFunctionName('functionName'),);
Parameters
| Name | Type | Description |
|---|---|---|
persist | Boolean | Whether to persist values. Defaults tofalse. |
Return
Action — This object, for chaining.
Deprecated methods
setMethodName(functionName)
setMethodName(functionName) Deprecated. Legacy alias forset.
Parameters
| Name | Type | Description |
|---|---|---|
function | String | The name of the function. You can use functions from included libraries, such asLibrary.libFunction1. |
Return
Action — This object, for chaining.
Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.
Last updated 2025-12-03 UTC.