> [!NOTE]
> **Note:** This is a [Developer Preview Program](https://developers.google.com/workspace/preview) feature.

In Google Chat, you can configure your agentic
Chat app to organize 1:1 direct messages with users
into separate, thread-based conversation sessions. Sessions let users start
fresh conversations with your Chat app for distinct
tasks or topics while keeping previous conversations organized and accessible
in the **Recent** list.

## How sessions work

When you enable sessions for your Chat app, 1:1
direct messages between a user and your Chat app use
separate threads for each conversation session:

- **Starting a session** : Users can start a new session in the Chat UI in the 1:1 direct message space with your Chat app, or browse previous sessions in the **Recent** list. You can also start a new session by calling the [`spaces.messages.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create) method to [send a message](https://developers.google.com/workspace/chat/create-messages#create-message-thread) that starts a new thread.
- **Session threads** : Each session is represented by a [`Thread`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads#Thread) resource (`spaces/{space}/threads/{thread}`). All messages exchanged within a session belong to that session's thread. When you enable sessions in an existing 1:1 direct message, previous top-level messages appear as individual sessions. Each session thread supports up to 500 replies after the initial message that starts the session. After a session reaches this limit, the user or Chat app must start a new session thread.
- **Replying in a session** : When a user sends a message or invokes a command in a session, [returning a synchronous message
  response](https://developers.google.com/workspace/chat/receive-respond-interactions) automatically posts the reply in that session thread. To reply asynchronously by calling the [`spaces.messages.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create) method, set `message.thread.name` to the thread resource name from the interaction event and set `messageReplyOption` to `REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD` (or `REPLY_MESSAGE_OR_FAIL`).
- **Default session titles and icons** : When a new session starts, Chat automatically sets the session title (`threadMetadata.title`) to the text of the first message in the session and the session icon (`threadMetadata.icon`) to the default `notes` [Google Material Icon](https://fonts.google.com/icons). Your Chat app can read or update the session title and icon using the Google Chat API.
- **Space session state** : The [`Space`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces#Space) resource includes the `sessionState` field (set to `THREAD` when sessions are enabled) and the `sessionEnableTime` timestamp indicating when sessions were most recently enabled in the space.

## Enable sessions in the Google Cloud console

To enable sessions for 1:1 direct messages with your
Chat app, turn on **Agentic features** in the
Google Cloud console. Turning on **Agentic features** also displays an **Agent**
label next to your Chat app's name in
Chat:

1. In the Google Cloud console, go to the Chat API **Configuration**
   page:

   [Go to the Chat API Configuration page](https://console.cloud.google.com/apis/api/chat.googleapis.com/hangouts-chat)
2. Under **Interactive features** , ensure **Enable interactive features** is
   turned on.

3. Under **Agentic features** , turn on **Enable Agentic features**.

4. Click **Save**.

## Manage sessions with the Chat API

Your Chat app can use the
[`spaces.messages.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create)
method to start or reply inside a session thread, and the
[`spaces.threads`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads) REST
resource to get, update, and list conversation sessions in a 1:1 direct
message space.

### Prerequisites

To call the `spaces.threads` methods, your Chat app
must meet the following requirements:

- Authenticate with [app authentication](https://developers.google.com/workspace/chat/authenticate-authorize-chat-app) using the `https://www.googleapis.com/auth/chat.bot` authorization scope.
- Call the methods for a 1:1 direct message space with the Chat app (`spaceType` is `DIRECT_MESSAGE` and `singleUserBotDm` is `true`).

### Start a new session

To proactively start a new session from your Chat app
(for example, to send a task notification), call the
[`spaces.messages.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create)
method without specifying `thread.name`. You can optionally provide a
`thread.threadKey` and set the initial session title and icon in
`thread.threadMetadata`:

    POST https://chat.googleapis.com/v1/spaces/SPACE_ID/messages
    Content-Type: application/json

    {
      "text": "Your weekly pipeline report is ready.",
      "thread": {
        "threadKey": "weekly-report-2026-11-02",
        "threadMetadata": {
          "title": "Weekly pipeline report",
          "icon": {
            "materialIcon": {
              "name": "lightbulb"
            }
          }
        }
      }
    }

### Reply in a session

When a user sends a message or invokes a command in a session, the
[interaction event](https://developers.google.com/workspace/chat/receive-respond-interactions) includes the
session's thread resource name (`spaces/{space}/threads/{thread}`). Returning a
synchronous message response automatically replies in that session thread.

To reply asynchronously inside the same session, call the
[`spaces.messages.create`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.messages/create)
method, set `messageReplyOption` to `REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD` (or
`REPLY_MESSAGE_OR_FAIL`), and specify `thread.name` in the request body:

    POST https://chat.googleapis.com/v1/spaces/SPACE_ID/messages?messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD
    Content-Type: application/json

    {
      "text": "Here is the summary you requested.",
      "thread": {
        "name": "spaces/SPACE_ID/threads/THREAD_ID"
      }
    }

> [!NOTE]
> **Note:** In a 1:1 direct message where sessions aren't enabled (`space.sessionState` isn't `THREAD`), calling `spaces.messages.create` with `thread.name` and `REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD` posts a threaded reply on the user's message or command. To post a top-level message when sessions aren't enabled, check `space.sessionState` first---if it isn't `THREAD`, omit `thread` and set `messageReplyOption` to `MESSAGE_REPLY_OPTION_UNSPECIFIED`.

### Get a session thread

To retrieve details about a session thread, including its current title and
icon, call the
[`spaces.threads.get`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads/get)
method with the thread's resource name (`spaces/{space}/threads/{thread}`):

    GET https://chat.googleapis.com/v1/spaces/SPACE_ID/threads/THREAD_ID

Replace `SPACE_ID` and `THREAD_ID` with the space ID and thread ID of the
session.

If successful, the response body contains a
[`Thread`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads#Thread)
resource:

    {
      "name": "spaces/SPACE_ID/threads/THREAD_ID",
      "threadMetadata": {
        "title": "Troubleshoot deployment pipeline",
        "icon": {
          "materialIcon": {
            "name": "notes"
          }
        }
      }
    }

### Update a session title and icon

To update a session's title or icon---for example, to summarize the conversation
topic after responding to the user---call the
[`spaces.threads.patch`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads/patch)
method and specify the fields to update in `updateMask`:

- `thread_metadata.title`: Updates the session title (`threadMetadata.title`). Session titles can be up to 1,024 characters long.
- `thread_metadata.icon`: Updates the session icon (`threadMetadata.icon`). Only a supported subset of [Google Material Icons](https://fonts.google.com/icons) renders in the Chat UI (`materialIcon`); other icon names fall back to the default `notes` icon.
- `thread_metadata`: Updates both the session title and icon.

    PATCH https://chat.googleapis.com/v1/spaces/SPACE_ID/threads/THREAD_ID?updateMask=thread_metadata.title,thread_metadata.icon
    Content-Type: application/json

    {
      "threadMetadata": {
        "title": "Q4 budget planning summary",
        "icon": {
          "materialIcon": {
            "name": "lightbulb"
          }
        }
      }
    }

If successful, the response body contains the updated
[`Thread`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads#Thread)
resource:

    {
      "name": "spaces/SPACE_ID/threads/THREAD_ID",
      "threadMetadata": {
        "title": "Q4 budget planning summary",
        "icon": {
          "materialIcon": {
            "name": "lightbulb"
          }
        }
      }
    }

### List sessions in a direct message

To list the sessions in a 1:1 direct message space with your
Chat app, call the
[`spaces.threads.list`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads/list)
method. The response returns threads in reverse chronological order based on
when each session was created (most recent comes first).

You can optionally specify the following query parameters:

- `pageSize`: The maximum number of threads to return. The default value is `20` and the maximum value is `100`.
- `pageToken`: A page token received from a previous `spaces.threads.list` call to retrieve the next page of results.

    GET https://chat.googleapis.com/v1/spaces/SPACE_ID/threads?pageSize=20

If successful, the response body contains a list of
[`Thread`](https://developers.google.com/workspace/chat/api/reference/rest/v1/spaces.threads#Thread)
resources and an optional `nextPageToken`:

    {
      "threads": [
        {
          "name": "spaces/SPACE_ID/threads/THREAD_ID_2",
          "threadMetadata": {
            "title": "Q4 budget planning summary",
            "icon": {
              "materialIcon": {
                "name": "lightbulb"
              }
            }
          }
        },
        {
          "name": "spaces/SPACE_ID/threads/THREAD_ID_1",
          "threadMetadata": {
            "title": "Troubleshoot deployment pipeline",
            "icon": {
              "materialIcon": {
                "name": "notes"
              }
            }
          }
        }
      ],
      "nextPageToken": "NEXT_PAGE_TOKEN"
    }

## Related topics

- [Configure the Google Chat API](https://developers.google.com/workspace/chat/configure-chat-api)
- [Receive and respond to user interactions](https://developers.google.com/workspace/chat/receive-respond-interactions)
- [Send a message](https://developers.google.com/workspace/chat/create-messages)