Create a Google Workspace subscription

This page explains how to use the Google Workspace Events API to create a subscription to a Google Workspace resource. A Google Workspace subscription lets your app receive information about Google Workspace events, which represent changes to a Google Workspace resource. To learn about which resources and event types the Google Workspace Events API supports, see the Google Workspace Events API overview.

This page includes the following steps for creating a Google Workspace subscription:

1. Set up your environment.
2. Create and subscribe to a Google Cloud Pub/Sub topic. You use this topic as an endpoint to receive Google Workspace events.
3. Call the Google Workspace Events API's create() method on the Subscription resource.
4. Test your Google Workspace subscription to ensure that your Pub/Sub topic receives events that you've subscribed to.
5. Optionally, configure how to push events to an endpoint for your app, so that your app can process the event and, if necessary, take action.

Prerequisites

Apps Script

• To use the Google Cloud CLI commands in this guide:
  1. Install the Google Cloud CLI.
  2. To initialize the gcloud CLI, run the following code:

    gcloud init
    

• A Google Cloud project with billing enabled. For subscriptions to Chat, you must also enable the Chat API in your Cloud project and configure the App name, Avatar URL, and Description fields. For details, see Build a Google Chat app.
• Requires user authentication with the OAuth consent screen configured for the app. When you configure the consent screen, you must specify a scope to support each event type for the subscription. To configure the consent screen and identify required scopes, see Choose scopes.

• An Apps Script project:
  • Use your Google Cloud project instead of the default one created automatically by Apps Script.
  • For any scopes that you added to configure the OAuth consent screen, you must also add the scopes to the appsscript.json file in your Apps Script project. For example:

  "oauthScopes": [
    "https://www.googleapis.com/auth/chat.messages.readonly"
  ]
      

  • Enable the Google Workspace Events advanced service.

Python

• Python 3.6 or greater
• The pip package management tool
• The latest Google client libraries for Python. To install or update them, run the following command in your command-line interface:

    pip3 install --upgrade google-api-python-client google-auth-oauthlib
    

• To use the Google Cloud CLI commands in this guide:
  1. Install the Google Cloud CLI.
  2. To initialize the gcloud CLI, run the following code:

    gcloud init
    

• A Google Cloud project with billing enabled. For subscriptions to Chat, you must also enable the Chat API in your Cloud project and configure the App name, Avatar URL, and Description fields. For details, see Build a Google Chat app.
• Requires user authentication with the OAuth consent screen configured for the app. When you configure the consent screen, you must specify a scope to support each event type for the subscription. To configure the consent screen and identify required scopes, see Choose scopes.

Set up your environment

The following section explains how to set up your environment before creating a Google Workspace subscription.

Enable the Google Workspace Events API and Google Cloud Pub/Sub API

Before using Google APIs, you need to turn them on in a Google Cloud project. You can turn on one or more APIs in a single Google Cloud project.

Google Cloud console

In the Google Cloud console, open the Google Cloud project for your app and enable the Google Workspace Events API and Pub/Sub API:

Enable the APIs

gcloud

1. In your working directory, sign in to your Google Account:

   gcloud auth login

2. Set your project to the Cloud project for your app:

   gcloud config set project PROJECT_ID

   Replace PROJECT_ID with the project ID for the Cloud project for your app.

3. Enable the Google Workspace Events API and Google Cloud Pub/Sub API:

   gcloud services enable pubsub.googleapis.com workspaceevents.googleapis.com

Create OAuth client ID credentials

Note: You can skip this step if you are using Apps Script.

Choose your application type for specific instructions about how to create an OAuth client ID:

Note: To run the code sample in this guide, choose Desktop app and follow the instructions.

Web application

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > Web application.
4. In the Name field, type a name for the credential. This name is only shown in the Google Cloud console.
5. Add authorized URIs related to your app:
   • Client-side apps (JavaScript)–Under Authorized JavaScript origins, click Add URI. Then, enter a URI to use for browser requests. This identifies the domains from which your application can send API requests to the OAuth 2.0 server.
   • Server-side apps (Java, Python, and more)–Under Authorized redirect URIs, click Add URI. Then, enter an endpoint URI to which the OAuth 2.0 server can send responses.
6. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.

   Note the Client ID. Client secrets aren't used for Web applications.

7. Click OK. The newly created credential appears under OAuth 2.0 Client IDs.

Android

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > Android.
4. In the "Name" field, type a name for the credential. This name is only shown in the Google Cloud console.
5. In the "Package name" field, enter the package name from your AndroidManifest.xml file.
6. In the "SHA-1 certificate fingerprint" field, enter your generated SHA-1 certificate fingerprint.
7. Click Create. The OAuth client created screen appears, showing your new Client ID.
8. Click OK. The newly created credential appears under "OAuth 2.0 Client IDs."

iOS

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > iOS.
4. In the "Name" field, type a name for the credential. This name is only shown in the Google Cloud console.
5. In the "Bundle ID" field, enter the bundle identifier as listed in the app's Info.plist file.
6. Optional: If your app appears in the Apple App Store, enter the App Store ID.
7. Optional: In the "Team ID" field, enter the unique 10-character string, generated by Apple and assigned to your team.
8. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
9. Click OK. The newly created credential appears under "OAuth 2.0 Client IDs."

Chrome app

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > Chrome app.
4. In the "Name" field, type a name for the credential. This name is only shown in the Google Cloud console.
5. In the "Application ID" field, enter your app's unique 32-character ID string. You can find this ID value in your app's Chrome Web Store URL and in the Chrome Web Store Developer Dashboard.
6. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
7. Click OK. The newly created credential appears under "OAuth 2.0 Client IDs."

Desktop app

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > Desktop app.
4. In the Name field, type a name for the credential. This name is only shown in the Google Cloud console.
5. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
6. Click OK. The newly created credential appears under OAuth 2.0 Client IDs.

TVs & Limited Input devices

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > TVs & Limited Input devices.
4. In the "Name" field, type a name for the credential. This name is only shown in the Google Cloud console.
5. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
6. Click OK. The newly created credential appears under "OAuth 2.0 Client IDs."

Universal Windows Platform (UWP)

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Click Create Credentials > OAuth client ID.
3. Click Application type > Universal Windows Platform (UWP).
4. In the "Name" field, type a name for the credential. This name is only shown in the Google Cloud console.
5. In the "Store ID" field, enter your app's unique, 12-character Microsoft Store ID value. You can find this ID in your app's Microsoft Store URL and in the Partner Center.
6. Click Create. The OAuth client created screen appears, showing your new Client ID and Client secret.
7. Click OK. The newly created credential appears under "OAuth 2.0 Client IDs."

Download the client secret JSON file

Note: You can skip this step if you are using Apps Script.

The client secret file is a JSON representation of the OAuth client ID credentials that your app can reference when providing credentials.

1. In the Google Cloud console, go to Menu > APIs & Services > Credentials.

   Go to Credentials

2. Under OAuth 2.0 Client IDs, click the client ID that you created.

3. Click Download JSON.

4. Save the file as client_secrets.json.

Create and subscribe to a Pub/Sub topic

In this section, you create a Pub/Sub topic and subscription to the topic. Your Pub/Sub topic serves as the notification endpoint where your Google Workspace subscription receives events.

To learn more about creating and managing Pub/Sub topics, see the Pub/Sub documentation .

To create and subscribe to a Pub/Sub topic:

Google Cloud console

1. In the Google Cloud console, go to the Pub/Sub page:

   Go to Google Cloud Pub/Sub

   Make sure that the Cloud project for your app is selected.

2. Click Create topic and do the following:

   1. Enter a name for your topic, such as workspace-events-topic.
   2. Leave Add a default subscription selected. Pub/Sub names this default subscription similar to your topic's name, such as workspace-events-topic-sub.
   3. Optional: Update or configure additional properties for your topic.

3. Click Create. Your full topic name is formatted as projects/PROJECT_ID/topics/TOPIC_ID. You use this full name in a later step.

4. Grant access to publish Pub/Sub messages to your topic:

   1. On your topic's page, go to the side panel and open the Permissions tab.
   2. Click Add Principal.
   3. In the Add principals field, add the service account for the Google Workspace application that delivers events to your subscription:
      1. For Chat events, [e-mail].
      2. For Meet events, [e-mail].
   4. In the Assign roles menu, select Pub/Sub Publisher.
   5. Click Save. It can take a few minutes to update the permissions for your topic.

gcloud

1. In your Cloud project, create a topic by running the following command:

   gcloud pubsub topics create TOPIC_ID

   Replace TOPIC_ID with a unique ID for your topic, such as workspace-events-topic.

   The output displays the full topic name, formatted as projects/PROJECT_ID/topics/TOPIC_ID. Make note of the name, and make sure the value for PROJECT_ID is the Cloud project ID for your app. You use the topic name in the following step, and to create the Google Workspace subscription later.

2. Grant access to publish messages to your topic:

   gcloud pubsub topics add-iam-policy-binding TOPIC_NAME --member='serviceAccount:GOOGLE_WORKSPACE_APPLICATION' --role='roles/pubsub.publisher'

   Replace the following:

   • TOPIC_NAME: The full topic name, which is the output from the previous step. Formatted as projects/PROJECT_ID/topics/TOPIC_ID.

   • GOOGLE_WORKSPACE_APPLICATION: The Google Workspace application that must deliver events to your subscription:

     • To receive events from Chat, use [e-mail].
     • To receive events from Meet, use [e-mail].

   It can take a few minutes to update the permissions for your topic.

3. Create a Pub/Sub subscription for the topic:

    gcloud pubsub subscriptions create SUBSCRIPTION_NAME --topic=TOPIC_NAME

   Replace the following:

   • SUBSCRIPTION_NAME: A name for your subscription, such as workspace-events-subscription.
   • TOPIC_NAME: The name of your topic that you created in the previous step.

Subscribe to a Google Workspace resource

In this section, you subscribe to the Google Workspace resource that you want to monitor for events.

Choose and identify the target resource

In a Google Workspace subscription, the target resource is the Google Workspace resource that you monitor for events. The target resource is represented in the subscription's targetResource field, formatted using the full resource name. For example, for a subscription that monitors a Google Chat space (spaces/AAAABBBBBBB), the value of the targetResource is //chat.googleapis.com/spaces/AAAABBBBBBB.

Before you create the subscription, use the following sections to learn how to identify and format the target resource.

Identify a target resource for Chat

Target resource	Format	Limitations
Space	//chat.googleapis.com/spaces/SPACE where SPACE is the ID in the resource name of the Chat API space resource. You can obtain the ID from the space's URL or using the spaces.list() method.	The Chat user that authorizes the subscription must be a member of the space through their Google Workspace or Google Account.
All spaces for a user	//chat.googleapis.com/spaces/-	The subscription only receives events for the spaces where the user is a member through their Google Workspace or Google Account.
User	//cloudidentity.googleapis.com/users/USER where USER is the ID in the resource name of the Chat API user resource. For details, see Identify and specify Google Chat users.	The subscription only receives events about the user that authorized the subscription. A user can't authorize a subscription on behalf of other users.

Identify a target resource for Meet

Target resource	Format	Limitations (if applicable)
Meeting space	//meet.googleapis.com/spaces/SPACE where SPACE is the ID in the resource name of the Meet REST API space resource. For details, see How Meet identifies a meeting space.
User	//cloudidentity.googleapis.com/users/USER where USER is the ID in the signedinUser.user field of the Meet REST API participant resource. For details, see Work with participants.	The subscription receives events about meeting spaces where the user is one of the following: The owner of the meeting space. The organizer of the Google Calendar event associated with the meeting space.

Create a Google Workspace subscription

To create a subscription, you use the Google Workspace Events API's subscriptions.create() method to create a Subscription resource. You specify the following fields:

• targetResource: A Google Workspace that you identified in the previous section, formatted using its full resource name.
• eventTypes: An array of one or more event types you want to receive about the resource. For example, if your app only needs to know about new messages posted to a Chat space, your app can just subscribe to events about created messages.
• notificationEndpoint: A notification endpoint where your Google Workspace subscription delivers events. You use the Pub/Sub topic that you created in the previous section.
• payloadOptions: Options to specify how much resource data to include in the event payload. This configuration affects the expiration time for your subscription. To learn more, see Event data.

To create a Google Workspace subscription:

Apps Script

1. In your Apps Script project, create a new script file named createSubscription and add the following code:

   function createSubscription() {
     // The Google Workspace resource to monitor for events.
     const targetResource = 'TARGET_RESOURCE';
   
     // The types of events to receive.
     const eventTypes = [EVENT_TYPES];
   
     // The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
     const pubsubTopic = 'TOPIC_NAME';
   
     // Whether to include resource data or not.
     const resourceData = RESOURCE_DATA;
   
     // Call the Workspace Events API using the advanced service.
     const response = WorkspaceEvents.Subscriptions.create({
       targetResource: targetResource,
       eventTypes: eventTypes,
       notificationEndpoint: {
         pubsubTopic: pubsubTopic,
       },
       payloadOptions: {
         includeResource: resourceData
       }
     });
     console.log(response);
   }
   

   Replace the following:

   • TARGET_RESOURCE: The Google Workspace resource that you're subscribing to, formatted as its full resource name. For example, to subscribe to a Google Chat space with the space ID AAAABBBB, use //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: One or more event types that you want to subscribe to in the target resource. Format as an array of strings such as 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: The full name of the Pub/Sub topic that you created in your Cloud project. Formatted as projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA: A boolean that specifies whether the subscription includes resource data in the payload:

     • True: Includes all resource data. To limit which fields are included, add the fieldMask field and specify at least one field for the changed resource. Only subscriptions to Chat resources support including resource data.
     • False: Excludes resource data.

2. To create the Google Workspace subscription, run the function createSubscription in your Apps Script project.

Python

1. In your working directory, create a file named create_subscription.py and add the following code:

   """Create subscription."""
   
   from google_auth_oauthlib.flow import InstalledAppFlow
   from googleapiclient.discovery import build
   
   # Specify required scopes.
   SCOPES = [SCOPES]
   
   # Authenticate with Google Workspace and get user authentication.
   flow = InstalledAppFlow.from_client_secrets_file('client_secrets.json', SCOPES)
   CREDENTIALS = flow.run_local_server()
   
   # The Google Workspace resource to monitor for events.
   TARGET_RESOURCE = 'TARGET_RESOURCE'
   
   # The types of events to receive.
   EVENT_TYPES = [EVENT_TYPES]
   
   # The endpoint to deliver events to, such as a Google Cloud Pub/Sub topic.
   TOPIC = 'TOPIC_NAME'
   
   # Call the Workspace Events API using the service endpoint.
   service = build(
       'workspaceevents',
       'v1',
       credentials=CREDENTIALS,
   )
   
   BODY = {
       'target_resource': TARGET_RESOURCE,
       'event_types': EVENT_TYPES,
       'notification_endpoint': {'pubsub_topic': TOPIC},
       'payload_options': {'include_resource': RESOURCE_DATA},
   }
   response = service.subscriptions().create(body=BODY).execute()
   print(response)
   

   Replace the following:

   • SCOPES: One or more OAuth scopes that support each event type for the subscription. Formatted as an array of strings. To list multiple scopes, separate by commas. For example, 'https://www.googleapis.com/auth/chat.spaces.readonly', 'https://www.googleapis.com/auth/chat.memberships.readonly'.
   • TARGET_RESOURCE: The Google Workspace resource that you're subscribing to, formatted as its full resource name. For example, to subscribe to a Google Chat space with the space ID AAAABBBB, use //chat.googleapis.com/spaces/AAAABBBB.
   • EVENT_TYPES: One or more event types that you want to subscribe to in the target resource. Format as an array of strings such as 'google.workspace.chat.message.v1.created'.
   • TOPIC_NAME: The full name of the Pub/Sub topic that you created in your Cloud project. Formatted as projects/PROJECT_ID/topics/TOPIC_ID.

   • RESOURCE_DATA: A boolean that specifies whether the subscription includes resource data in the payload:

     • True: Includes all resource data. To limit which fields are included, add the fieldMask field and specify at least one field for the changed resource. Only subscriptions to Chat resources support including resource data.
     • False: Excludes resource data.

2. To create the Google Workspace subscription, run the following in your terminal:

   python3 create_subscription.py

The Google Workspace Events API returns a completed long-running operation that contains the instance of the Subscription resource that you created.

Test your Google Workspace subscription

To test that you're receiving Google Workspace events, you can trigger an event and pull messages to the Pub/Sub subscription.

To test your Google Workspace subscription:

Google Cloud console

1. Trigger one or more types of events in the target resource of your Google Workspace subscription. For example, if you've subscribed to new messages in a Chat space, post a message to the space.

2. In the Google Cloud console, go to the Pub/Sub page:

   Go to Pub/Sub

   Make sure that the Cloud project for your app is selected.

3. In the Pub/Sub menu, click Subscriptions.

4. In the table, find the Pub/Sub subscription for your topic and click the subscription name.

5. Click the Messages tab.

6. Click Pull. It can take up to a few minutes for an event to generate a Pub/Sub message.

gcloud

1. Trigger one or more types of events in the target resource of your Google Workspace subscription. For example, if you've subscribed to new messages in a Chat space, post a message in the space.

2. Run the following command:

   gcloud pubsub subscriptions pull PUBSUB_SUBSCRIPTION_NAME --format=json --limit=MESSAGE_COUNT --auto-ack

   Replace the following:

   • PUBSUB_SUBSCRIPTION_NAME: The full name of your Pub/Sub subscription, formatted as projects/SUBSCRIPTION_ID/subscriptions/SUBSCRIPTION_ID.
   • MESSAGE_COUNT: The maximum number of Pub/Sub messages you want to pull.

   It can take up to a few minutes for an event to generate a Pub/Sub message.

For each Google Workspace event that you triggered, a message is delivered to your Pub/Sub subscription that contains the event. For details, see Receiving events as Google Cloud Pub/Sub messages.

Configure how your app receives events

The Pub/Sub subscription that you created is pull-based. After you've tested that your Pub/Sub subscription, you can update the delivery type to change how your app receives events. For example, you can configure the Pub/Sub subscription to a push delivery type, so that your app can receive events directly to an app endpoint.

To learn about configuring a Pub/Sub subscription, see the Pub/Sub documentation.

Note: You can't set an Apps Script project as a push delivery endpoint in Pub/Sub. To push Pub/Sub messages to an Apps Script project, you must publish the script as a web app.

Related topics

• Tutorial: Observe meeting events with Python and the Google Meet REST API
• Get a subscription
• List subscriptions
• Update or renew a subscription
• Resolve errors and reactivate a subscription
• Delete a subscription