Add-on actions

Add-on actions provide interactive behavior to widgets. By creating an action, you define what happens when the user selects or updates a widget.

In most cases you can define add-on actions using Action objects provided by the Apps Script Card service. Each Action is associated with a callback function when you create it. You implement the callback function to take desired steps when the user interacts with the widget. You must also link the Action to the widget using an appropriate widget handler function that defines what kind of interaction triggers the Action callback.

Configure a widget with an Action using this general process:

Create the Action object, specifying the callback function that it should execute along with any parameters it requires.
Call the appropriate widget handler function on the widget using the Action object.
Implement the callback function to enact the required behavior.

Widget handler functions

To link a widget to a specific Action or other behavior, you use a widget handler function. The handler function determines what kind of interaction (for example, clicking the widget or editing a text field) triggers the action behavior. The handler function also defines what steps the UI takes, if any, after the action completes.

The following table lists the different handler types for widgets and what widgets they are used with:

Handler function	Triggers action	Applicable widgets	Description
`setOnChangeAction()`	The widget value changes	`DatePicker` `DateTimePicker` `SelectionInput` `Switch` `TextInput` `TimePicker`	Sets an `Action` that executes an Apps Script function when the widget loses focus, such as such as when the user enters text in an input and presses Enter. The handler automatically passes an event object to the function it calls. You can insert additional parameter information in this event object if desired.
`setOnClickAction()`	The user clicks the widget	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Sets an `Action` that executes an Apps Script function when the user clicks the widget. The handler automatically passes an event object to the function it calls. You can insert optional parameter information in this event object.
`setComposeAction()`	The user clicks the widget	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Gmail specific. Sets an `Action` that builds an email draft, then presents that draft to the user in a Gmail UI compose window. You can build the draft as a new message or a reply to the open message in Gmail. When the handler calls the draft-building callback function, it passes an event object to the callback function. See Compose draft messages for more details.
`setOnClickOpenLinkAction()`	The user clicks the widget	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Sets an `Action` to open a URL when the user clicks the widget. Use this handler when you must construct the URL or other actions must take place before the link opens; otherwise it is usually simpler to use `setOpenLink()`. You can only open the URL in a new window. When closed, you can cause the UI to reload the add-on.
`setOpenLink()`	The user clicks the widget	`CardAction` `Image` `ImageButton` `DecoratedText` `TextButton`	Directly opens a URL when the user clicks the widget. Use this handler when you know the URL and only need to open it; otherwise use `setOnClickOpenLinkAction()`. You can open the URL in a new window or in an overlay. When closed, you can cause the UI to reload the add-on.
`setSuggestionsAction()`	The user enters text into an input	`TextInput`	Sets an `Action` that executes an Apps Script function when the user enters text into a text input widget. The handler automatically passes an event object to the function it calls. See Autocomplete suggestions for text inputs for more details.

Callback functions

Callback functions execute when an Action triggers. Because callback function are Apps Script functions, you can have them do almost anything any other script function can do.

A callback function sometimes returns a specific response object. These types of responses indicate additional operations that need to happen after the callback finishes executing, such as displaying a new card or presenting autocomplete suggestions. When your callback function must return a specific response object, you use a builder class in the Card service to construct that object.

The following table shows when your callback functions must return a specific response object for specific actions. These actions are all independent of the specific host application the add-on is extending:

Action attempted	Callback function should return
Navigate between cards	`ActionResponse`
Display a `Notification`	`ActionResponse`
Open a link using `setOnClickOpenLinkAction()`	`ActionResponse`
Display autocomplete suggestions	`SuggestionResponse`
Use a universal action	`UniversalActionResponse`
Other actions	Nothing

In addition to these actions, each host application has its own set of actions that can only be taken in that host. For details, see the following guides:

Action event objects

When your add-on triggers an Action, the UI automatically constructs a JSON event object and passes it as an argument to the Action callback function. This event object contains information about the user's current client-side context, such as the current values of all the interactive widgets in the displayed card.

Action event objects have a specific JSON structure that organizes the information that they contain. The same structure is used when a homepage trigger fires to create a homepage, or when a contextual trigger fires to update the add-on display.

See Event objects for a full explanation of the event object structure.