subscriptions

Changed on

Creates a Google Workspace subscription. To learn how to use this method, see Create a Google Workspace subscription. For a subscription on a Chat target resource, you can create a subscription as: - A Chat app subscribing to space events where the app is a member by specifying an authorization scope that begins with chat.app and getting one-time administrator approval. To learn more, see Authorize as a Chat app with administrator approval. - Developer Preview: A Chat app subscribing to all events in a Google Workspace organization by specifying an authorization scope that begins with chat.app.all and obtaining one-time administrator approval. To learn more, see Subscribe to all Google Chat events in a Workspace organization . - A user by specifying an authorization scope that doesn't include app in its name. To learn more, see Authorize as a Chat user.

post/v1/subscriptions

Request

  • Base URL: https://workspaceevents.googleapis.com
  • URL: https://workspaceevents.googleapis.com/v1/subscriptions
  • Auth: one of:
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.all.memberships.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.all.memberships.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.all.messages.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.all.messages.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.all.spaces.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.all.spaces.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.all.users.readstate.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.memberships) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.memberships)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.memberships.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.memberships.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.messages.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.messages.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.spaces) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.spaces)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.app.spaces.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.app.spaces.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.memberships) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.memberships)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.memberships.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.memberships.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.messages) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.messages)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.messages.reactions) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.messages.reactions)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.messages.reactions.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.messages.reactions.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.messages.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.messages.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.spaces) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.spaces)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.spaces.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.spaces.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.users.availability) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.users.availability)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.users.availability.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.users.availability.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.users.readstate) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.users.readstate)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/chat.users.readstate.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/chat.users.readstate.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/drive) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/drive)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/drive.file) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/drive.file)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/drive.metadata) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/drive.metadata)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/drive.metadata.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/drive.metadata.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/drive.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/drive.readonly)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/meetings.space.created) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/meetings.space.created)
    • OAuth 2 (implicit, authorization URL https://accounts.google.com/o/oauth2/auth, scopes: https://www.googleapis.com/auth/meetings.space.readonly) and OAuth 2 (authorization code, authorization URL https://accounts.google.com/o/oauth2/auth, token URL https://accounts.google.com/o/oauth2/token, scopes: https://www.googleapis.com/auth/meetings.space.readonly)

Query parameters

validateOnlyboolean

Optional. If set to true, validates and previews the request, but doesn't create the subscription.

Request body

authoritystring

Output only. The user who authorized the creation of the subscription. When a user authorizes the subscription, this field and the user_authority field have the same value and the format is: Format: users/{user} For Google Workspace users, the {user} value is the user.id field from the Directory API. When a Chat app authorizes the subscription, only service_account_authority field populates and this field is empty.

createTimestring google-datetime

Output only. The time when the subscription is created.

etagstring

Optional. This checksum is computed by the server based on the value of other fields, and might be sent on update requests to ensure the client has an up-to-date value before proceeding.

eventTypesstring[]

Required. Unordered list. Input for creating a subscription. Otherwise, output only. One or more types of events to receive about the target resource. Formatted according to the CloudEvents specification. The supported event types depend on the target resource of your subscription. For details, see Supported Google Workspace events. By default, you also receive events about the lifecycle of your subscription. You don't need to specify lifecycle events for this field. If you specify an event type that doesn't exist for the target resource, the request returns an HTTP 400 Bad Request status code.

expireTimestring google-datetime

Non-empty default. The timestamp in UTC when the subscription expires. Always displayed on output, regardless of what was used on input.

namestring

Identifier. Resource name of the subscription. Format: subscriptions/{subscription}

reconcilingboolean

Output only. If true, the subscription is in the process of being updated.

serviceAccountAuthoritystring

Output only. The service account that was used to authorize the creation of the subscription. This service account must be owned by the same Google Cloud project where you created this subscription. Format: projects/{project_id}/serviceAccounts/{service_account_id}

state'STATE_UNSPECIFIED' | 'ACTIVE' | 'SUSPENDED' | 'DELETED'

Output only. The state of the subscription. Determines whether the subscription can receive events and deliver them to the notification endpoint.

suspensionReason'ERROR_TYPE_UNSPECIFIED' | 'USER_SCOPE_REVOKED' | 'APP_SCOPE_REVOKED' | 'RESOURCE_DELETED' | 'USER_AUTHORIZATION_FAILURE' | 'APP_AUTHORIZATION_FAILURE' | 'ENDPOINT_PERMISSION_DENIED' | 'ENDPOINT_NOT_FOUND' | 'ENDPOINT_RESOURCE_EXHAUSTED' | 'OTHER'

Output only. The error that suspended the subscription. To reactivate the subscription, resolve the error and call the ReactivateSubscription method.

targetResourcestring

Required. Immutable. The Google Workspace resource that's monitored for events, formatted as the full resource name. To learn about target resources and the events that they support, see Supported Google Workspace events. A user can only authorize your app to create one subscription for a given target resource. If your app tries to create another subscription with the same user credentials, the request returns an ALREADY_EXISTS error.

ttlstring google-duration

Input only. The time-to-live (TTL) or duration for the subscription. If unspecified or set to 0, uses the maximum possible duration.

uidstring

Output only. System-assigned unique identifier for the subscription.

updateTimestring google-datetime

Output only. The last time that the subscription is updated.

userAuthoritystring

Output only. The user who authorized the creation of the subscription. The user must be able to view the target_resource. For Google Workspace users, the {user} value is the user.id field from the Directory API. Format: users/{user}

Response

Successful response

Changes

  • 2a42e25e351cRevision changes
    • breaking

      removed the request body

    • breaking

      removed the media type */* for the response with the status

    • info

      the security scope https://www.googleapis.com/auth/chat.app.all.memberships.readonly was added to the endpoint's security scheme Oauth2

    • info

      the security scope https://www.googleapis.com/auth/chat.app.all.memberships.readonly was added to the endpoint's security scheme Oauth2c

    • info

      the security scope https://www.googleapis.com/auth/meetings.space.readonly was removed from the endpoint's security scheme Oauth2

    • info

      the security scope https://www.googleapis.com/auth/meetings.space.readonly was removed from the endpoint's security scheme Oauth2c

  • 1a4f4a1882ceRevision changes
    • info

      the security scope https://www.googleapis.com/auth/chat.app.all.memberships.readonly was added to the endpoint's security scheme Oauth2

    • info

      the security scope https://www.googleapis.com/auth/chat.app.all.memberships.readonly was added to the endpoint's security scheme Oauth2c

    • info

      the security scope https://www.googleapis.com/auth/meetings.space.readonly was removed from the endpoint's security scheme Oauth2

    • info

      the security scope https://www.googleapis.com/auth/meetings.space.readonly was removed from the endpoint's security scheme Oauth2c