An action that enables interactivity within UI elements. The action does not happen directly on the client but rather invokes an Apps Script callback function with optional parameters.
Available for Google Workspace Add-ons and Google Chat apps.
var image = CardService.newImage()
.setOnClickAction(CardService.newAction()
.setFunctionName("handleImageClick")
.setParameters({imageSrc: 'carImage'}));
Methods
| Method | Return type | Brief description |
|---|---|---|
addRequiredWidget(requiredWidget) | Action | Adds the names of the widgets that this Action needs for a valid submission. |
setAllWidgetsAreRequired(allWidgetsAreRequired) | Action | Indicates whether this Action requires inputs from all widgets. |
setFunctionName(functionName) | Action | Sets the name of the callback function to be called. |
setInteraction(interaction) | Action | Sets the interaction with a user, only required when opening a dialog. |
setLoadIndicator(loadIndicator) | Action | Sets the loading indicator that displays while the action is in progress. |
setParameters(parameters) | Action | Allows custom parameters to be passed to the callback function. |
setPersistValues(persistValues) | Action | Indicates whether form values are determined by the client's values or the server's values
after an action response updates the form's Card. |
Detailed documentation
addRequiredWidget(requiredWidget)
Adds the names of the widgets that this Action needs for a valid submission. If the widgets in this list don't have a value when this Action is invoked, the form submission is aborted.
Only available for Google Chat apps. Not available for Google Workspace Add-ons.
var textInput = CardService.newTextInput()
.setFieldName("text_input_1")
.setTitle("Text input title")
// Creates a footer button that requires an input from the above TextInput Widget.
var action = CardService.newAction()
.setFunctionName("notificationCallback")
.addRequiredWidget("text_input_1");
var fixedFooter =
CardService
.newFixedFooter()
.setPrimaryButton(
CardService
.newTextButton()
.setText("help")
.setOnClickAction(action));
Parameters
| Name | Type | Description |
|---|---|---|
requiredWidget | 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.
Only available for Google Chat apps. Not available for Google Workspace Add-ons.
// Creates a button with an action that requires inputs from all widgets.
const button = CardService.newTextButton()
.setText('Create notification')
.setOnClickAction(
CardService.newAction()
.setAllWidgetsAreRequired(true));
Parameters
| Name | Type | Description |
|---|---|---|
allWidgetsAreRequired | Boolean | Whether the action requires inputs from all widgets. Defaults to
false. |
Return
Action — This object, for chaining.
setFunctionName(functionName)
Sets the name of the callback function to be called. Required.
Parameters
| Name | Type | Description |
|---|---|---|
functionName | String | The name of the function. You can use functions from included libraries,
such as Library.libFunction1. |
Return
Action — This object, for chaining.
setInteraction(interaction)
Sets the interaction with a user, only required when opening a dialog. If unspecified, the app
responds by executing an Action like opening a link or running a function—as normal.
Only available for Google Chat apps. Not available for Google Workspace Add-ons.
const action = 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 |
|---|---|---|
loadIndicator | LoadIndicator | 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 values
after an action response updates the form's Card. When set to true, the
client's values persist after the server response. When set to false, the server's
values overwrite the form values. Defaults to false.
Persisting the client values helps prevent situations where a form changes unexpectedly
after a user makes an edit. For example, if a user makes an edit to a TextInput after
submitting a form, but before the server responds. If the values are persisted, the edit the
user made remains after the server response updates the Card; otherwise the form value
returns 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 or
override form values, so avoid turning on persistence for that type of functionality. Without
persistence, it's recommended that you use the LoadIndicator.SPINNER for events,
because this locks the UI and prevents user edits before the server responds. Alternatively,
you can use LoadIndicator.NONE and make sure every element in the form has an onChange
action.
// Creates a button with an action that persists the client's values as the on-click action.
const button = CardService.newTextButton()
.setText('Create notification')
.setOnClickAction(
CardService.newAction()
.setPersistValues(true)
.setFunctionName('functionName'));
Parameters
| Name | Type | Description |
|---|---|---|
persistValues | Boolean | Whether to persist values. Defaults to false. |
Return
Action — This object, for chaining.