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
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Node.js Cloud Client Library.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
credentials.jsonto your local directory.
- Choose an authorization scope that supports user authentication.
Python
- A Business or Enterprise Google Workspace account with access to Google Chat.
- Set up your environment:
- Create a Google Cloud project.
- Configure the OAuth consent screen.
- Enable and configure the Google Chat API with a name, icon, and description for your Chat app.
- Install the Python Cloud Client Library.
-
Create OAuth client ID credentials for a desktop application. To run the sample in this
guide, save the credentials as a JSON file named
credentials.jsonto your local directory.
- Choose an authorization scope that supports user authentication.
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.readstateauthorization scope. - Call the
UpdateThreadReadStatemethod. - Pass
updateMaskwith the valuelastReadTime. - Pass
threadReadStateas an instance ofThreadReadStatewith the following:- The
namefield 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
mealias. 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
- The
lastReadTimefield 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
lastReadTimeto 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
lastReadTimeto 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 coerceslastReadTimeto the current request time. - Minimum timestamp: The
lastReadTimefield must be on or after the Unix epoch (1970-01-01T00:00:00Z). Setting a negative timestamp (before1970-01-01T00:00:00Z) returns anINVALID_ARGUMENT(400) error.
- Mark as unread: Set
- The
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'sname. You can obtain the ID by calling theListSpacesmethod or from the space's URL.THREAD_NAME: the ID from the thread'sname. 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.