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 
 }'

    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 
 ] 
 }
    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
    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 
     { 
 "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.

    ReactionSummary

    JSON representation 
     { 
 "emoji" 
 : 
 string 
 , 
 "count" 
 : 
 integer 
 }
    Fields
    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: ❌
    Create a Mobile Website
    View Site in Mobile | Classic
    Share by: