Event objects

This page outlines the structure of Google Workspace add-ons event objects.

Event objects are JSON structures that are automatically constructed and passed as parameters to trigger or callback functions when a user interacts with an add-on. Event objects carry client-side information about the host app and the current context to the add-on's server-side callback function.

Google Workspace add-ons use event objects in the following places:

• Homepage triggers. Every homepageTrigger function you define is automatically passed an event object when the homepage trigger function fires. You can use this object in your homepage trigger function to identify the active host app, the client's platform, the user locale, and other information.

  The event objects created when homepage triggers fire don't contain all the fields included in the other two cases; fields pertaining to widgets and contextual information are omitted.

• Contextual triggers. Each host application provides a different set of contextual triggers that fire when the user enters a specific context. For example:

  • Gmail provides a contextual trigger for when a user opens a message and another when a user composes a message.
  • Google Calendar provides a contextual trigger for when a user opens an event.
  • Google Drive provides a contextual trigger for when a user selects Drive files.

  When a contextual trigger fires, the host application calls the corresponding runFunction listed in the add-on manifest, passing it an event object as a parameter. The event objects created when contextual triggers fire contain all the fields included in homepage trigger event objects, plus fields containing contextual information.

• Widget actions. Event objects are also used to provide widget interactivity, using the same action model that Gmail add-ons use. Google Workspace add-ons use all the same widget handler functions, Action objects, and action responses. However, in Google Workspace add-ons the action event objects include even more information a callback function can act on.

  The event objects created as the result of widget actions contain all the fields included in contextual trigger event objects, plus fields containing widget information.

• Preview link triggers. In Google Docs, Sheets, and Slides, you can configure link previews for third-party services based on specific URL patterns. When users interact with a link that meets the pattern, the linkPreviewTriggers fires and an event object that contains the link is passed to the trigger's callback function. Your add-on can use this event object to construct a smart chip and card that surfaces information about the link within the host application. You can also build widget actions to let users interact with the preview card and its contents.

• Google Chat app triggers (Developer Preview). In Google Chat, your add-on appears to users as a Chat app, and users can interact with it by adding it to spaces, sending messages, using slash commands, and more. To build interactive features, you set up and use various Chat app triggers. Each trigger sends a different event object payload that helps you process or respond to each type of interaction.

Event object structure

The following table describes the top-level structure of Google Workspace add-ons event objects. The event object structure includes a commonEventObject top-level field for host-independent information. Each event object can also have one of the following host-specific top-level fields, determined by the active host app: gmailEventObject, calendarEventObject, or driveEventObject.

For backward compatibility, Google Workspace add-ons event objects also include all the original fields used in Gmail add-on action event objects. These fields are listed in the table below under "Original Gmail add-on fields"; the information in these fields is reproduced in new object structure.

Common event object

The common event object is the portion of the overall event object that carries general, host-independent information to the add-on from the user's client. This information includes details such as the user's locale, host app, and platform.

In addition to homepage and contextual triggers, add-ons construct and pass event objects to action callback functions when the user interacts with widgets. Your add-on's callback function can query the common event object to determine the contents of open widgets in the user's client. For example, your add-on can locate the text a user has entered into a TextInput widget in the eventObject.commentEventObject.formInputs object.

Date-time picker form inputs

Action callback functions can receive current widget values in the commonEventObject.formInputs field. This includes the user's selected date or time values in date or time picker widgets. However, the structure of the information differs depending on whether the widget was configured as a date-time picker, a date-only picker, or a time-only picker. The structural differences are described in the following table:

Calendar event object

The Calendar event object is the portion of the overall event object that carries information about a user's calendar and calendar events. It's only present in an event object if the host application is Google Calendar.

The following table lists the fields present in the calendarEventObject field of an event object. Fields marked as User-generated data are present in the event object if and only if the data is present in the Calendar event and the add-on sets its addOns.calendar.currentEventAccess manifest field to READ or READ_WRITE.

Attendee

Attendee objects carry information about individual attendees to Google Calendar events. This information is present in the event object if and only if the data is present in the Calendar event and the add-on sets its addOns.calendar.currentEventAccess manifest field to READ or READ_WRITE.

Conference data

Conference data objects carry information about conferences that are attached to Google Calendar events. These can be Google conference solutions, such as Google Meet, or third-party conferences. This information is present in the event object if and only if the data is present in the Calendar event and the add-on sets its addOns.calendar.currentEventAccess manifest field to READ or READ_WRITE.

Entry point

Entry point objects carry information about the established means of accessing a given conference, such as by phone or video. This information is present in the event object if and only if the data is present in the Calendar event and the add-on sets its addOns.calendar.currentEventAccess manifest field to READ or READ_WRITE.

Drive event object

The Drive event object is the portion of the overall event object that carries information about a user's Google Drive and its contents. It's only present in an event object if the host application is Google Drive.

Drive item

Drive item objects carry information about specific Drive items, such as files or folders.

Gmail event object

The Gmail event object is the portion of the overall event object that carries information about a user's Gmail messages. It's only present in an event object if the host application is Gmail.

Docs event object

The Docs event object is the portion of the overall event object that carries information about a user's document and its contents. It's only present in an event object if the host application is Google Docs.

"docs" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Sheets event object

The Sheets event object is the portion of the overall event object that carries information about a user's document and its contents. It's only present in an event object if the host application is Google Sheets.

"sheets" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}
        

Slides event object

The Slides event object is the portion of the overall event object that carries information about a user's document and its contents. It's only present in an event object if the host application is Google Slides.

"slides" : {
  "matchedUrl" : {
      "url" : "https://www.example.com/12345"
  }
}