Get details about a user's space read state

This guide explains how to use the getSpaceReadState method on the SpaceReadState resource of the Google Chat API to get details about a user's read state within a space. To get the read state of a message in a message thread, see Get details about a user's thread read state.

The SpaceReadState resource is a singleton resource that represents details about a specified user's last read message in a Google Chat space.

Prerequisites

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
```
A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
Authorization configured for the Chat app. Getting details about a user's read state within a space requires user authentication with the chat.users.readstate or chat.users.readstate.readonly authorization scope.

Node.js

Node.js & npm
The latest Google client libraries for Node.js. To install them, run the following command in your command-line interface:
```
npm install @google-cloud/local-auth @googleapis/chat
```
A Google Cloud project with the Google Chat API enabled and configured. For steps, see Build a Google Chat app.
Authorization configured for the Chat app. Getting details about a user's read state within a space requires user authentication with the chat.users.readstate or chat.users.readstate.readonly authorization scope.

Apps Script

A Google Workspace account with access to Google Chat.
A published Chat app. To build a Chat app, follow this quickstart.
Authorization configured for the Chat app. Getting details about a user's read state within a space requires user authentication with the chat.users.readstate or chat.users.readstate.readonly authorization scope.

Get the calling user's space read state

To get details about a user's read state within a space, include the following in your request:

Specify the chat.users.readstate or chat.users.readstate.readonly authorization scope.
Call the getSpaceReadState method on the SpaceReadState resource.
Pass the name of the space read state to get, which includes a user ID or alias and a space ID. Getting space read state only supports getting the read state of the calling user, which can be specified by setting one of the following:
- The me alias. For example, users/me/spaces/SPACE/spaceReadState.
- The calling user's Workspace email address. For example, users/user@example.com/spaces/SPACE/spaceReadState.
- The calling user's user ID. For example, users/USER/spaces/SPACE/spaceReadState.

The following example gets the calling user's space read state:

Python

In your working directory, create a file named chat_spaceReadState_get.py.

Include the following code in chat_spaceReadState_get.py:

from google_auth_oauthlib.flow import InstalledAppFlow
from googleapiclient.discovery import build

# Define your app's authorization scopes.
# When modifying these scopes, delete the file token.json, if it exists.
SCOPES = ["https://www.googleapis.com/auth/chat.users.readstate.readonly"]

def main():
    '''
    Authenticates with Chat API via user credentials,
    then gets the space read state for the calling user.
    '''

    # Authenticate with Google Workspace
    # and get user authorization.
    flow = InstalledAppFlow.from_client_secrets_file(
                      'client_secrets.json', SCOPES)
    creds = flow.run_local_server()

    # Build a service endpoint for Chat API.
    chat = build('chat', 'v1', credentials=creds)

    # Use the service endpoint to call Chat API.
    result = chat.users().spaces().getSpaceReadState(

        # The space read state to get.
        #
        # Replace USER with the calling user's ID, Workspace email,
        # or the alias me.
        #
        # Replace SPACE with a space name.
        # Obtain the space name from the spaces resource of Chat API,
        # or from a space's URL.
        name='users/me/spaces/SPACE/spaceReadState'

      ).execute()

    # Prints the API's response.
    print(result)

if __name__ == '__main__':
    main()

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
In your working directory, build and run the sample:
```
python3 chat_spaceReadState_get.py
```

Node.js

In your working directory, create a file named chat_spaceReadState_get.js.

Include the following code in chat_spaceReadState_get:

const chat = require('@googleapis/chat');
const {authenticate} = require('@google-cloud/local-auth');

/**
* Authenticates with Chat API via user credentials,
* then gets the space read state for the calling user.
* @return {!Promise<!Object>}
*/
async function getSpaceReadState() {

  /**
  * Authenticate with Google Workspace
  * and get user authorization.
  */
  const scopes = [
    'https://www.googleapis.com/auth/chat.users.readstate.readonly',
  ];

  const authClient =
      await authenticate({scopes, keyfilePath: 'client_secrets.json'});

  /**
  * Build a service endpoint for Chat API.
  */
  const chatClient = await chat.chat({version: 'v1', auth: authClient});

  /**
  * Use the service endpoint to call Chat API.
  */
  return await chatClient.users.spaces.getSpaceReadState({

    /**
    * The space read state to get.
    *
    * Replace USER with the calling user's ID, Workspace email,
    * or the alias me.
    *
    * Replace SPACE with a space name.
    * Obtain the space name from the spaces resource of Chat API,
    * or from a space's URL.
    */
    name: 'users/me/spaces/SPACE/spaceReadState'
  });
}

/**
* Use the service endpoint to call Chat API.
*/
getSpaceReadState().then(console.log);

In the code, replace the following:
- SPACE: a space name, which you can obtain from the spaces.list method in the Chat API, or from a space's URL.
In your working directory, build and run the sample:
```
node chat_spaceReadState_get.js
```

Apps Script

This example calls the Chat API using the Advanced Chat Service.

Add the chat.users.readstate.readonly authorization scope to the Apps Script project's appsscript.json file:
```
"oauthScopes": [
  "https://www.googleapis.com/auth/chat.users.readstate.readonly"
]
```

Add a function like this one to the Apps Script project's code:

/**
* Authenticates with Chat API via user credentials,
* then gets the space read state for the calling user.
* @param {string} spaceReadStateName The resource name of the space read state.
*/
function getSpaceReadState(spaceReadStateName) {
  try {
    Chat.Users.Spaces.getSpaceReadState(spaceReadStateName);
  } catch (err) {
    // TODO (developer) - Handle exception
    console.log('Failed to get read state with error %s', err.message);
  }
}

The Google Chat API gets the specified space read state and returns an instance of SpaceReadState resource.

Get details about a user's space read state

Prerequisites

Python

Node.js

Apps Script

Get the calling user's space read state

Python

Node.js

Apps Script

Related topics