Create a Google Workspace subscription

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 .

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 
   

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 add_box Create topicand do the following:

   1. Enter a name for your topic, such as workspace-events-topic .
   2. Leave Add a default subscriptionselected. 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 Permissionstab.
   2. Click Add Principal.
   3. In the Add principalsfield, add the service account for the Google Workspace application that delivers events to your subscription:
      1. For Chat events, chat-api-push@system.gserviceaccount.com .
      2. For Meet events, meet-api-event-push@system.gserviceaccount.com .
   4. In the Assign rolesmenu, 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 chat-api-push@system.gserviceaccount.com .
     • To receive events from Meet, use meet-api-event-push@system.gserviceaccount.com .

   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.

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 
   

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/Submenu, click Subscriptions.

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

5. Click the Messagestab.

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.