Organize conversations into sessions

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 method to send a message that starts a new thread.
  • Session threads: Each session is represented by a 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 automatically posts the reply in that session thread. To reply asynchronously by calling the 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. Your Chat app can read or update the session title and icon using the Google Chat API.
  • Space session state: The 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

  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 method to start or reply inside a session thread, and the 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 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 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 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 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"
  }
}

Get a session thread

To retrieve details about a session thread, including its current title and icon, call the 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 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 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 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 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 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 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"
}