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.

G Suite add-ons use event objects in three 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. G Suite add-ons use all the same widget handler functions, Action objects, and action responses. However, in G Suite 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.

This page outlines the new structure of G Suite add-on event objects.

Event object structure

The following table describes the top-level structure of G Suite add-on 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, G Suite add-on 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.

Event object
eventObject.commonEventObject Common fields object
An object containing information common to all event objects, regardless of the host application.
eventObject.calendar Calendar event object object
Only present if the calling host is Google Calendar. An object containing calendar and event information.
eventObject.drive Drive event object object
Only present if the calling host is Google Drive. An object containing Drive information.
eventObject.gmail Gmail event object object
Only present if the calling host is Gmail. An object containing Gmail information.
Original Gmail add-on fields
eventObject.messageMetadata.accessToken string
Deprecated. An access token. You can use this to enable access to user data using temporary Gmail add-on scopes.

For G Suite add-ons, find this information in the eventObject.gmail.accessToken field.

eventObject.messageMetadata.messageId string
Deprecated. The message ID of the thread open in the Gmail UI.

For G Suite add-ons, find this information in the eventObject.gmail.messageId field.

eventObject.clientPlatform string
Deprecated. Indicates where the event originates (web, iOS, or Android).

For G Suite add-ons, find this information in the eventObject.commonEventObject.platform field.

eventObject.formInput object
Deprecated. A map of 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, and the values are strings. 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.

For G Suite add-ons, find this information in the eventObject.commonEventObject.formInputs field instead; widgets with single values are represented as arrays with a single element.

eventObject.formInputs object
Deprecated. A map of current values of widgets in the card, presented as lists of strings. 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 checkbox groups, all the values are presented in a list.

For G Suite add-ons, find this information in the eventObject.commonEventObject.formInputs field.

eventObject.parameters object
Deprecated. A map of any additional parameters you supply to the Action using Action.setParameters(). The map keys and values are strings.

For G Suite add-ons, find this information in the eventObject.commonEventObject.parameters field.

eventObject.userCountry string
Deprecated and disabled by default. The two-letter code indicating the user's country or region. It can also be a numeric UN M49 country code. See Accessing user locale and timezone for more details.
eventObject.userLocale string
Deprecated and disabled by default. The two-letter ISO 639 code indicating the user's language. See Accessing user locale and timezone for more details.

For G Suite add-ons, find this information in the eventObject.commonEventObject.userLocale field.

eventObject.userTimezone.id string
Deprecated and disabled by default. The time zone identifier of the user's timezone. Examples include: America/New_York, Europe/Vienna, and Asia/Seoul. See Accessing user locale and timezone for more details.

For G Suite add-ons, find this information in the eventObject.commonEventObject.userTimezone.id field.

eventObject.userTimezone.offset string
Deprecated and disabled by default. The time offset from Coordinated Universal Time (UTC) of the user's timezone, measured in milliseconds. See Accessing user locale and timezone for more details.

For G Suite add-ons, find this information in the eventObject.commonEventObject.userTimezone.offset field.

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.

Common event object fields
commonEventObject.platform string
Indicates where the event originates (`WEB`, `IOS`, or `ANDROID`).
commonEventObject.formInputs object
A map containing the current values of the widgets in the displayed card. The map keys are the string IDs assigned with each widget, and each value is another wrapper object with a single "" key. The structure of the map value object is dependent on the widget type:
  • Single-valued widgets (for example, a text box): a list of strings (only one element).

    Example: for a text input widget with employeeName as its ID, access the text input value with: e.commonEventObject.formInputs.employeeName[""].stringInputs.value[0].

  • Multi-valued widgets (for example, checkbox groups): a list of strings.

    Example: for a multi-value widget with participants as its ID, access the value array with: e.commonEventObject.formInputs.participants[""].stringInputs.value.

  • A date-time picker: a DateTimeInput object.

    Example: For a picker with an ID of myDTPicker, access the DateTimeInput object using e.commonEventObject.formInputs.myDTPicker[""].dateTimeInput.

  • A date-only picker: a DateInput object.

    Example: For a picker with an ID of myDatePicker, access the DateInput object using e.commonEventObject.formInputs.myDatePicker[""].dateInput.

  • A time-only picker: a TimeInput object.

    Example: For a picker with an ID of myTimePicker, access the TimeInput object using e.commonEventObject.formInputs.myTimePicker[""].timeInput.

commonEventObject.hostApp string
Indicates the host app the add-on is active in when the event object is generated. Possible values include the following:
  • GMAIL
  • CALENDAR
  • DRIVE
commonEventObject.parameters object
Any additional parameters you supply to the Action using Action.setParameters().
commonEventObject.userLocale string
Disabled by default. The two-letter ISO 639 code indicating the user's language. To enable this field, you must set `addOns.common.useLocaleFromApp` to `true` in your add-on's manifest. Your add-on's scope list must also include `https://www.googleapis.com/auth/script.locale`. See Accessing user locale and timezone for more details.
commonEventObject.userTimezone string
Disabled by default. The time zone ID and offset. To enable this field, you must set `addOns.common.useLocaleFromApp` to `true` in your add-on's manifest. Your add-on's scope list must also include `https://www.googleapis.com/auth/script.locale`. See Accessing user locale and time zone for more details.
commonEventObject.userTimezone.id string
The timezone identifier of the user's timezone. Examples include: America/New_York, Europe/Vienna, and Asia/Seoul. To enable this field, you must set `addOns.common.useLocaleFromApp` to `true` in your add-on's manifest. Your add-on's scope list must also include `https://www.googleapis.com/auth/script.locale`. See Accessing user locale and timezone for more details.
commonEventObject.userTimezone.offset string
The time offset from Coordinated Universal Time (UTC) of the user's timezone, measured in milliseconds. See Accessing user locale and timezone for more details.

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:

DateTimeInput object
dateTimeInput.hasDate boolean
true if the input date time includes a date; if false only a time is included.
dateTimeInput.hasTime boolean
true if the input date time includes a time; if false only a date is included.
dateTimeInput.msSinceEpoch string
The time selected by the user, in milliseconds since epoch (00:00:00 UTC on 1 January 1970).
DateInput object
dateInput.msSinceEpoch string
The time selected by the user, in milliseconds since epoch (00:00:00 UTC on 1 January 1970).
TimeInput object
timeInput.hours number
The hour number selected by the user.
timeInput.minutes number
The minute number selected by the user.

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.

Calendar event object
calendar.attendees[] list of attendee objects
User-generated data. A list of the attendees of the calendar event.
calendar.calendarId string
The calendar ID.
calendar.capabilities object
User-generated data. An object describing the capabilities of the add-on to view or update event information.
calendar.capabilities.canAddAttendees boolean
User-generated data. true if the add-on can add new attendees to the event attendee list; false otherwise.
calendar.capabilities.canSeeAttendees boolean
User-generated data. true if the add-on can read the event attendee list; false otherwise.
calendar.capabilities.canSeeConferenceData boolean
User-generated data. true if the add-on can read the event conference data; false otherwise.
calendar.capabilities.canSetConferenceData boolean
User-generated data. true if the add-on can update the event conference data; false otherwise.
calendar.conferenceData Conference data object
User-generated data. An object representing any conference data associated with this event, such as Hangouts Meet conference details.
calendar.id string
The event ID.
calendar.organizer object
An object representing the organizer of the event.
calendar.organizer.email string
The event organizer's email address.
calendar.recurringEventId string
The ID of a recurring event.

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.

Attendee object
attendee.additionalGuests number
The number of additional guests the attendee had indicated they are bringing. Defaults to zero.
attendee.comment string
The attendee's response comment, if any.
attendee.displayName string
The attendee displayed name.
attendee.email string
The attendee email address.
attendee.optional boolean
true if the attendance for this attendee is marked as optional; false otherwise.
attendee.organizer boolean
true if the attendee is an organizer for this event.
attendee.resource boolean
true if the attendee represents a resource, such as room or piece of equipment; false otherwise.
attendee.responseStatus string
The attendee's response status. Possible values include the following:
  • accepted: The attendee has accepted the event invitation.
  • declined: The attendee has declined the event invitation.
  • needsAction: The attendee has not responded to the event invitation.
  • tentative: The attendee has tentatively accepted the event invitation.
attendee.self boolean
true if this attendee represents the calendar in which this event appears; false otherwise.

Conference data

Conference data objects carry information about conferences that are attached to Google Calendar events. These can be Google conference solutions, such as Hangouts 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.

Conference data object
conferenceData.conferenceId string
The ID of the conference. This ID is meant to allow applications to keep track of conferences; you shouldn't display this ID to users.
conferenceData.conferenceSolution object
An object representing the conference solution, such as Hangouts or Hangouts Meet.
conferenceData.conferenceSolution.iconUri string
The URI for the user-visible icon representing this conference solution.
conferenceData.conferenceSolution.key object
The key which uniquely identifies the conference solution for this event.
conferenceData.conferenceSolution.key.type string
The conference solution type. Possible values include the following:
  • eventHangout for Hangouts for consumers (http://hangouts.google.com).
  • eventNamedHangout for classic Hangouts for G Suite users (http://hangouts.google.com).
  • hangoutsMeet for Hangouts Meet (http://meet.google.com).
conferenceData.conferenceSolution.name string
The user-visible name of this conference solution (not localized).
conferenceData.entryPoints[] list of entry point objects
The list of conference entry points, such as URLs or phone numbers.
conferenceData.notes string
Additional notes (such as instructions from the domain administrator or legal notices) about the conference to display to the user. Can contain HTML. The maximum length is 2048 characters.
conferenceData.parameters object
An object containing a map of defined parameter data for use by the add-on.
conferenceData.parameters.addOnParameters object
A map of parameter string keys and values. These keys and values are defined by the add-on developer to attach information to a specific conference for the add-on's use.

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.

Entry point object
entryPoint.accessCode string
The access code used to access the conference. The maximum length is 128 characters. Conference providers typically only use a subset of {accessCode, meetingCode, passcode, password, pin} to provide access to conferences. Match and only ever display the fields the conference provider uses.
entryPoint.entryPointFeatures list
Features of the entry point. Currently these features only apply to phone entry points:
  • toll: The entry point is a toll phone call.
  • toll_free: The entry point is a toll-free phone call.
entryPoint.entryPointType string
The type of entry point. Possible values are the following:
  • more: Additional conference joining instructions, such as alternate phone numbers. A conference can only have one more entry point; if present at least one other type of entry point is also required.
  • phone: Join the conference via a phone number. A conference can have zero or more phone entry points. Google Calendar only displays the first two phone entry points, after formatting and sorting alphabetically.
  • sip: Join the conference over SIP. A conference can have at most one sip entry point.
  • video: Join the conference over HTTP. A conference can have at most one video entry point.
entryPoint.label string
The user-visible label for the entry point URI (not localized).
entryPoint.meetingCode string
The meeting code used to access the conference. The maximum length is 128 characters. Conference providers typically only use a subset of {accessCode, meetingCode, passcode, password, pin} to provide access to conferences. Match and only ever display the fields the conference provider uses.
entryPoint.passcode string
The passcode used to access the conference. The maximum length is 128 characters. Conference providers typically only use a subset of {accessCode, meetingCode, passcode, password, pin} to provide access to conferences. Match and only ever display the fields the conference provider uses.
entryPoint.password string
The password used to access the conference. The maximum length is 128 characters. Conference providers typically only use a subset of {accessCode, meetingCode, passcode, password, pin} to provide access to conferences. Match and only ever display the fields the conference provider uses.
entryPoint.pin string
The PIN used to access the conference. The maximum length is 128 characters. Conference providers typically only use a subset of {accessCode, meetingCode, passcode, password, pin} to provide access to conferences. Match and only ever display the fields the conference provider uses.
entryPoint.regionCode string
Region code of the phone number. Needed by users if the URI doesn't include a country code. Values are based on the public CLDR list of region codes.
entryPoint.uri string
The URI of the entry point. The maximum length is 1300 characters. The formatting depends on the entry point type:
  • more: A http: or https: schema is required.
  • phone: A tel: schema is required. The URI should include the entire dial sequence (for example, "tel:+12345678900,,,12345678;1234").
  • sip: A sip: or sips: schema is required. For example "sip:12345678@myprovider.com".
  • video: A http: or https: schema is required.

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 event object
drive.activeCursorItem Drive item object
The Drive item currently active.
drive.selectedItems[] list of Drive item objects
A list of items (files or folders) selected in Drive.

Drive item

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

Drive item object
item.addonHasFileScopePermission boolean
If true, the add-on has requested and received https://www.googleapis.com/auth/drive.file scope authorization for this item; otherwise this field is false.
item.id string
The ID of the selected item.
item.iconUrl string
The URL of the icon that represents the selected item.
item.mimeType string
The MIME type of the selected item.
item.title string
The title of the selected item.

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.

Gmail event object
gmail.accessToken string
The Gmail-specific access token. You can use this token with the GmailApp.setCurrentMessageAccessToken(accessToken) method to grant your add-on temporary access to a user's currently open Gmail message or let your add-on compose new drafts.
gmail.bccRecipients[] list of strings
Disabled by default. The list of "BCC:" recipient email addresses currently included in a draft the add-on is composing. To enable this field, you must set the `addOns.gmail.composeTrigger.draftAccess` field in your manifest to `METADATA`.
gmail.ccRecipients[] list of strings
Disabled by default. The list of "CC:" recipient email addresses currently included in a draft the add-on is composing. To enable this field, you must set the `addOns.gmail.composeTrigger.draftAccess` field in your manifest to `METADATA`.
gmail.messageId string
The ID of the currently open Gmail message.
gmail.threadId string
The currently open Gmail thread ID.
gmail.toRecipients[] list of strings
Disabled by default. The list of "To:" recipient email addresses currently included in a draft the add-on is composing. To enable this field, you must set the `addOns.gmail.composeTrigger.draftAccess` field in your manifest to `METADATA`.