Action

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](https://developers.google.com/apps-script/add-ons/concepts/actions#callback_functions)
with optional parameters.

Available for Google Workspace add-ons and Google Chat apps.

```javascript
const image = CardService.newImage().setOnClickAction(
    CardService.newAction().setFunctionName('handleImageClick').setParameters({
      imageSrc: 'carImage'
    }),
);
```

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/action#addRequiredWidget(String)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Adds the names of the widgets that this Action needs for a valid submission. |
| `https://developers.google.com/apps-script/reference/card-service/action#setAllWidgetsAreRequired(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Indicates whether this Action requires inputs from all widgets. |
| `https://developers.google.com/apps-script/reference/card-service/action#setFunctionName(String)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Sets the name of the callback function to be called. |
| `https://developers.google.com/apps-script/reference/card-service/action#setInteraction(Interaction)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Sets the interaction with a user, only required when opening a dialog. |
| `https://developers.google.com/apps-script/reference/card-service/action#setLoadIndicator(LoadIndicator)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Sets the loading indicator that displays while the action is in progress. |
| `https://developers.google.com/apps-script/reference/card-service/action#setParameters(Object)` | `https://developers.google.com/apps-script/reference/card-service/action#` | Allows custom parameters to be passed to the callback function. |
| `https://developers.google.com/apps-script/reference/card-service/action#setPersistValues(Boolean)` | `https://developers.google.com/apps-script/reference/card-service/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 `https://developers.google.com/apps-script/reference/card-service/card`. |

### Deprecated methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/card-service/action#setMethodName(String)` | `https://developers.google.com/apps-script/reference/card-service/action#` |   |

## 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.

Available for Google Workspace add-ons and Google Chat apps.

```javascript
const textInput = CardService.newTextInput()
                      .setFieldName('text_input_1')
                      .setTitle('Text input title');

// Creates a footer button that requires an input from the above TextInput
// Widget.
const action = CardService.newAction()
                   .setFunctionName('notificationCallback')
                   .addRequiredWidget('text_input_1');
const 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


`https://developers.google.com/apps-script/reference/card-service/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.

```javascript
// 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


`https://developers.google.com/apps-script/reference/card-service/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


`https://developers.google.com/apps-script/reference/card-service/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.

```javascript
const action = CardService.newAction()
                   .setFunctionName('handleDialog')
                   .setInteraction(CardService.Interaction.OPEN_DIALOG);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `interaction` | `https://developers.google.com/apps-script/reference/card-service/interaction` | The interaction to specify. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/action#` --- This object, for chaining.

*** ** * ** ***

### `setLoadIndicator(loadIndicator)`

Sets the loading indicator that displays while the action is in progress.

#### Parameters

| Name | Type | Description |
|---|---|---|
| `loadIndicator` | `https://developers.google.com/apps-script/reference/card-service/load-indicator` | The indicator to display. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/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


`https://developers.google.com/apps-script/reference/card-service/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 `https://developers.google.com/apps-script/reference/card-service/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 `https://developers.google.com/apps-script/reference/card-service/text-input` 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 `https://developers.google.com/apps-script/reference/card-service/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 `https://developers.google.com/apps-script/reference/card-service/load-indicator#SPINNER` for events,
because this locks the UI and prevents user edits before the server responds. Alternatively,
you can use `https://developers.google.com/apps-script/reference/card-service/load-indicator#NONE` and make sure every element in the form has an onChange
action.

```javascript
// 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


`https://developers.google.com/apps-script/reference/card-service/action#` --- This object, for chaining.

## Deprecated methods

### `setMethodName(functionName)`


**Deprecated.** Legacy alias for `https://developers.google.com/apps-script/reference/card-service/action#setFunctionName(String)`.

<br />

#### Parameters

| Name | Type | Description |
|---|---|---|
| `functionName` | `String` | The name of the function. You can use functions from included libraries, such as `Library.libFunction1`. |

#### Return


`https://developers.google.com/apps-script/reference/card-service/action#` --- This object, for chaining.