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.

Configure a widget with an Action using this general process:

  1. Create the Action object, specifying the callback function that should execute along with any parameters it requires.
  2. Call the appropriate widget handler function on the widget using the Action object.
  3. 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 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 SelectionInput
Switch
TextInput
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
KeyValue
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
KeyValue
TextButton
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 the Compose actions guide for more details.
setOnClickOpenLinkAction() The user clicks the widget CardAction
Image
ImageButton
KeyValue
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 open the URL in new window or in an overlay. When closed, you can cause the UI to reload the add-on.
setOpenLink() The user clicks the widget CardAction
Image
ImageButton
KeyValue
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 the Suggestions guide 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:

Action attempted Callback function should return
Navigate between cards ActionResponse
Display a Notification ActionResponse
Open a link using setOnClickOpenLinkAction() ActionResponse
Compose an email draft ComposeActionResponse
Display autocomplete suggestions SuggestionResponse
Use a universal action UniversalActionResponse
Any other action Nothing

Action event objects

When your add-on triggers an Action, the UI automatically constructs an event JSON object and passes it as an argument to the Action callback function. This event object contains the current values of all the interactive widgets in the displayed card, as well as the message ID for the currently opened message in the Gmail UI. Your callback function can use the message ID to access the content of the message via the Gmail service.

The following describes the structure of this event object:

Property Type Description
messageMetadata.accessToken string An access token. You can use this to enable access to user data using temporary Gmail add-on scopes.
messageMetadata.messageId string The message ID of the thread open in the Gmail UI.
clientPlatform string Indicates where the event originates (web, iOS, or Android).
formInput object{string, string} The current values of all form widgets in the card, restricted to one value per widget. The keys are the string IDs associated with the widgets. The event object provides formInput as a convenience for when you need to read data from multiple widgets with expected singular values, such as text inputs and switches. For multi-valued widgets such as checkboxes, you can read each value from formInputs instead.
formInputs object{string, array[string]} The current values of widgets in the card, presented in arrays. The keys are the string IDs associated with the widget. For single-valued widgets, the value is presented in a single-element array. For multi-valued widgets such as checkboxes, all the values are presented in an array.
parameters object{string, string} Any additional parameters you supply to the Action using Action.setParameters().