Update a user's thread read state

This guide explains how to use the update method on the ThreadReadState resource of the Google Chat API to mark message threads as read or unread.

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

Prerequisites

Node.js

Python

Update the calling user's thread read state

To update a user's read state within a message thread, include the following in your request:

  • Specify the chat.users.readstate authorization scope.
  • Call the UpdateThreadReadState method.
  • Pass updateMask with the value lastReadTime.
  • Pass threadReadState as an instance of ThreadReadState with the following:
    • The name field set to the thread read state to update, which includes a user ID or alias, a space ID, and a thread ID. Updating thread read state only supports updating 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/threads/THREAD/threadReadState.
      • The calling user's Workspace email address. For example, users/user@example.com/spaces/SPACE/threads/THREAD/threadReadState.
      • The calling user's user ID. For example, users/USER/spaces/SPACE/threads/THREAD/threadReadState.
    • The lastReadTime field set to the timestamp that marks the calling user's last read position in the thread, such as the timestamp of the last read message or the current time:
      • Mark as unread: Set lastReadTime to a timestamp earlier than the creation time of the latest message in the thread. In Chat, the thread appears as unread from that timestamp onward, updating unread badges, bolding the thread, and surfacing it in Home.
      • Mark as read: Set lastReadTime to a timestamp equal to or later than the creation time of the latest message in the thread. If you specify a future timestamp, the API coerces lastReadTime to the current request time.
      • Minimum timestamp: The lastReadTime field must be on or after the Unix epoch (1970-01-01T00:00:00Z). Setting a negative timestamp (before 1970-01-01T00:00:00Z) returns an INVALID_ARGUMENT (400) error.

The following example updates the calling user's thread read state:

Node.js

/**
 * This sample shows how to update the calling user's thread read state.
 *
 * It relies on the @google-apps/chat npm package.
 */
// Read the documentation for more details:
// https://developers.google.com/workspace/chat/api/reference/rest/v1/users.spaces.threads/updateThreadReadState

const {ChatServiceClient} = require('@google-apps/chat');
const {auth} = require('google-auth-library');

async function main() {
  // Create a client
  const chatClient = new ChatServiceClient({
    authClient: await auth.getClient({
      scopes: ['https://www.googleapis.com/auth/chat.users.readstate']
    })
  });

  // Initialize request arguments.
  const request = {
    threadReadState: {
      name: 'users/me/spaces/SPACE_NAME/threads/THREAD_NAME/threadReadState',
      lastReadTime: {
        seconds: Math.floor(Date.now() / 1000),
        nanos: 0
      }
    },
    updateMask: {
      paths: ['last_read_time']
    }
  };

  // Make the request
  const response = await chatClient.updateThreadReadState(request);
  console.log(response);
}

main().catch(console.error);

Python

"""
This sample shows how to update the calling user's thread read state.
"""
from google.apps import chat_v1
import google.auth
from google.protobuf import timestamp_pb2

# Read the documentation for more details:
# https://developers.google.com/workspace/chat/api/reference/rest/v1/users.spaces.threads/updateThreadReadState

def update_thread_read_state():
    # Authenticate with Chat API using user credentials.
    credentials, _ = google.auth.default(
        scopes=["https://www.googleapis.com/auth/chat.users.readstate"]
    )
    client = chat_v1.ChatServiceClient(credentials=credentials)

    # Set timestamp for last read time.
    now = timestamp_pb2.Timestamp()
    now.GetCurrentTime()

    thread_read_state = chat_v1.ThreadReadState(
        name="users/me/spaces/SPACE_NAME/threads/THREAD_NAME/threadReadState",
        last_read_time=now,
    )

    request = chat_v1.UpdateThreadReadStateRequest(
        thread_read_state=thread_read_state,
        update_mask={"paths": ["last_read_time"]},
    )

    response = client.update_thread_read_state(request=request)
    print(response)

if __name__ == "__main__":
    update_thread_read_state()

To run this sample, replace the following:

  • SPACE_NAME: the ID from the space's name. You can obtain the ID by calling the ListSpaces method or from the space's URL.
  • THREAD_NAME: the ID from the thread's name. You can obtain the ID from the response body returned after creating a message asynchronously with the Chat API, or with the custom name assigned to the message at creation.

The Chat API updates the specified thread read state and returns an instance of ThreadReadState.