MCP Tools Reference: chatmcp.googleapis.com

Tool: `search_messages`

Searches for Google Chat messages using keywords and filters. Works across all spaces the user has access to, or can be scoped to a specific conversation.

The following sample demonstrate how to use curl to invoke the search_messages MCP tool.

Curl Request
curl --location 'https://chatmcp.googleapis.com/mcp/v1' \ --header 'content-type: application/json' \ --header 'accept: application/json, text/event-stream' \ --data '{ "method": "tools/call", "params": { "name": "search_messages", "arguments": { // provide these details according to the tool MCP specification } }, "jsonrpc": "2.0", "id": 1 }'

Curl Request

curl --location 'https://chatmcp.googleapis.com/mcp/v1' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "search_messages",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Input Schema

Request to search for Google Chat messages using keywords and filters. Works across all spaces the user has access to, or can be scoped to a specific conversation.

SearchMessagesRequest

JSON representation
{ "searchParameters": { object (`SearchParameters`) }, "orderBy": enum (`OrderBy`), "pageSize": integer, "pageToken": string }

Fields
`searchParameters`	`object (SearchParameters)` Required. The search parameters to use for the search.
`orderBy`	`enum (OrderBy)` Optional. Specifies the order in which the results should be returned. Supported values: `CREATE_TIME_DESC`, `CREATE_TIME_ASC`, or `RELEVANCE_DESC`. NOTE: `RELEVANCE_DESC` cannot be used when the is_unread filter is used. By default, `RELEVANCE_DESC` is used if `is_unread` is not set to true, otherwise `CREATE_TIME_DESC` is used.
`pageSize`	`integer` Optional. The maximum number of results to return (max up to 100). If unspecified, at most 25 are returned.
`pageToken`	`string` Optional. A page token, received from a previous `search_messages` call. Provide this to retrieve the subsequent page.

SearchParameters

JSON representation
{ "keywords": [ string ], "conversationId": string, "sender": string, "isUnread": boolean, "hasLink": boolean, "startTime": string, "endTime": string, "mentionsMe": boolean, "conversationIncludesUser": string, "spaceDisplayNames": [ string ] }

JSON representation

{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ]
}

Fields
`keywords[]`	`string` Optional. A set of keywords which are used to filter the results.
`conversationId`	`string` Optional. Scopes the search to a specific conversation identifier, as returned from the search_conversations tool. Format: `spaces/{ID}`.
`sender`	`string` Optional. Filter for messages from a specific user. Either the email or resource name of the sender can be used. User resource names are formatted as `users/{ID}`, where `{ID}` can be a person ID or their email address.
`isUnread`	`boolean` Optional. Filter for messages that have not been read by the calling user.
`hasLink`	`boolean` Optional. Filter for messages containing at least one URL.
`startTime`	`string` Optional. Filter for messages created after this time. Format: ISO 8601 timestamp.
`endTime`	`string` Optional. Filter for messages created before this time. Format: ISO 8601 timestamp.
`mentionsMe`	`boolean` Optional. Filter for messages that explicitly mention the calling user.
`conversationIncludesUser`	`string` Optional. Filter for messages in DMs and group chats that include the specific user email or ID.
`spaceDisplayNames[]`	`string` Optional. Filter by a list of space names; space display names are partially matched. Note: Only the top 5 matches are returned.

OrderBy

Specifies the order in which the results should be returned. By default, RELEVANCE_DESC is used if is_unread is not set to true, otherwise CREATE_TIME_DESC is used.

Enums
`ORDER_BY_UNSPECIFIED`	Default value.
`CREATE_TIME_DESC`	Order by create time in descending order.
`RELEVANCE_DESC`	Order by relevance in descending order.

Output Schema

Response to search for Google Chat messages. If next_page_token is populated, call SearchMessages can be called again with that token to retrieve the next page of results.

SearchMessagesResponse

JSON representation
{ "messages": [ { object (`ChatMessage`) } ], "nextPageToken": string }

Fields

Fields
`messages[]`	`object (ChatMessage)` List of message objects that match the search criteria, ordered according to the `order_by` request parameter.
`nextPageToken`	`string` A token that can be sent as `page_token` to retrieve the next page. If this field is omitted, there are no subsequent pages.

messages[]

object (ChatMessage)

List of message objects that match the search criteria, ordered according to the order_by request parameter.

nextPageToken

string

A token that can be sent as page_token to retrieve the next page. If this field is omitted, there are no subsequent pages.

ChatMessage

JSON representation

JSON representation
{ "messageId": string, "threadId": string, "plaintextBody": string, "sender": { object (`User`) }, "createTime": string, "threadedReply": boolean, "attachments": [ { object (`ChatAttachmentMetadata`) } ], "reactionSummaries": [ { object (`ReactionSummary`) } ] }

{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ]
}

Fields
`messageId`	`string` Resource name of the message. Format: `spaces/{space}/messages/{message}`
`threadId`	`string` The thread this message belongs to. This will be empty if the message is unthreaded. Format: spaces/{space}/threads/{thread}
`plaintextBody`	`string` Plain text body of the message.
`sender`	`object (User)` The sender of the message.
`createTime`	`string` Output only. Timestamp when the message was created.
`threadedReply`	`boolean` Whether message is a thread reply.
`attachments[]`	`object (ChatAttachmentMetadata)` Attachments included in the message.
`reactionSummaries[]`	`object (ReactionSummary)` The emoji reactions summary included in the message.

User

JSON representation
{ "userId": string, "displayName": string, "email": string, "userType": enum (`UserType`) }

Fields
`userId`	`string` Resource name of a Chat user. Format: `users/{user}`.
`displayName`	`string` The display name of a Chat user.
`email`	`string` The email address of the user. This field is only populated when the user type is HUMAN.
`userType`	`enum (UserType)` The type of the user.

ChatAttachmentMetadata

JSON representation
{ "attachmentId": string, "filename": string, "mimeType": string, "source": enum (`Source`) }

Fields
`attachmentId`	`string` Resource name of the attachment. Format: spaces/{space}/messages/{message}/attachments/{attachment}.
`filename`	`string` Name of the attachment.
`mimeType`	`string` Content type (MIME type).
`source`	`enum (Source)` The source of the attachment.

JSON representation
{ "emoji": string, "count": integer }

Fields

Fields
`emoji`	`string` The emoji unicode string or custom emoji name.
`count`	`integer` The total number of reactions using the associated emoji.

emoji

string

The emoji unicode string or custom emoji name.

count

integer

The total number of reactions using the associated emoji.

UserType

The type of a Google Chat user.

Enums
`USER_TYPE_UNSPECIFIED`	Unspecified.
`HUMAN`	Human user.
`APP`	App user.

Source

The source of the attachment.

Enums
`SOURCE_UNSPECIFIED`	Reserved.
`DRIVE_FILE`	The file is a Google Drive file.
`UPLOADED_CONTENT`	The file is uploaded to Chat.

Tool Annotations

Destructive Hint: ❌ | Idempotent Hint: ✅ | Read Only Hint: ✅ | Open World Hint: ❌