MCP Tools Reference: chatmcp.googleapis.com

Ferramenta: list_messages

Recupera mensagens de uma conversa específica do Google Chat (espaço, mensagem direta ou mensagem direta em grupo) no formato Markdown. Permite filtrar por conversa, período e número de mensagens. Além disso, a próxima página de mensagens pode ser recuperada para fornecer mais contexto. As mensagens particulares (visíveis apenas para um usuário) são filtradas.

O exemplo de código abaixo mostra como usar curl para chamar a ferramenta MCP list_messages.

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

Esquema de entrada

ListChatMessagesRequest

Representação JSON 
{
  "conversationId": string,
  "threadId": string,
  "pageSize": integer,
  "pageToken": string,
  "startTime": string,
  "endTime": string
}
Campos
conversationId

string

Obrigatório. O ID da conversa. Uma conversa pode ser um espaço, uma mensagem direta (DM) ou uma DM/Chat em grupo. Formato: spaces/{space}
threadId

string

Opcional. O ID de uma conversa específica. Se fornecido, somente as mensagens dessa conversa serão retornadas. Se omitido, as mensagens de todas as conversas são consideradas. Formato: spaces/{space}/threads/{thread}
pageSize

integer

Opcional. O número máximo de mensagens a serem retornadas. O serviço pode retornar um valor inferior a este. Se não for especificado, o padrão será 20. O valor máximo é 50. Se você usar um valor maior que 50, ele será alterado automaticamente para 50.
pageToken

string

Opcional. Um token de página recebido de uma chamada list_messages anterior. Forneça isso para recuperar a página subsequente.
startTime

string

Opcional. Carimbo de data/hora ISO 8601 para filtrar mensagens. Somente as mensagens criadas após esse horário serão retornadas.
endTime

string

Opcional. Carimbo de data/hora ISO 8601 para filtrar mensagens. Somente as mensagens criadas antes desse horário serão retornadas.

Esquema de saída

Resposta que contém a lista de mensagens da conversa solicitada.

ListChatMessagesResponse

Representação JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Campos
messages[]

object (ChatMessage)

Lista de mensagens recuperadas, em ordem cronológica inversa (as mais recentes primeiro).
nextPageToken

string

Um token, que pode ser enviado como page_token em um ListMessagesRequest subsequente para recuperar a próxima página de mensagens. Se esse campo estiver vazio, não haverá mais páginas.

ChatMessage

Representação JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Campos
messageId

string

Nome do recurso da mensagem. Formato: spaces/{space}/messages/{message}
threadId

string

A conversa a que esta mensagem pertence. Esse campo vai ficar vazio se a mensagem não estiver em uma conversa. Formato: spaces/{space}/threads/{thread}
plaintextBody

string

Corpo de texto da mensagem usando a formatação Markdown.
sender

object (User)

O remetente da mensagem.
createTime

string

Apenas saída. Carimbo de data/hora de quando a mensagem foi criada. Formato: carimbo de data/hora ISO 8601.
threadedReply

boolean

Se a mensagem é uma resposta de conversa.
attachments[]

object (ChatAttachmentMetadata)

Anexos incluídos na mensagem.
reactionSummaries[]

object (ReactionSummary)

O resumo das reações com emojis incluído na mensagem.
quotedMessageMetadata

object (QuotedMessageMetadata)

Apenas saída. Informações sobre uma mensagem original que é citada ou encaminhada nesta mensagem. Observação: esse campo está em desenvolvimento e talvez ainda não esteja presente em todos os ambientes.

Usuário

Representação JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Campos
userId

string

Nome do recurso de um usuário do Chat. Formato: users/{user}.
displayName

string

O nome de exibição de um usuário do Chat.
email

string

O endereço de e-mail do usuário. Esse campo só é preenchido quando o tipo de usuário é HUMAN.
userType

enum (UserType)

O tipo do usuário.

ChatAttachmentMetadata

Representação JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Campos
attachmentId

string

Nome do recurso do anexo. Formato: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nome do anexo.
mimeType

string

Tipo de conteúdo (tipo MIME).
source

enum (Source)

A origem do anexo.
driveFileId

string

Apenas saída. O ID do arquivo do Google Drive. Preenchido apenas quando a origem é DRIVE_FILE. Usar com o MCP do Google Drive.

ReactionSummary

Representação JSON 
{
  "emoji": string,
  "count": integer
}
Campos
emoji

string

A string Unicode do emoji ou o nome do emoji personalizado.
count

integer

O número total de reações usando o emoji associado.

QuotedMessageMetadata

Representação JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Campos
messageId

string

Apenas saída. Nome do recurso da mensagem original que foi citada ou encaminhada. Formato: spaces/{space}/messages/{message}
lastUpdateTime

string

Apenas saída. Carimbo de data/hora de quando a mensagem original foi criada ou atualizada pela última vez antes de ser citada ou encaminhada. Formato: carimbo de data/hora ISO 8601.
quoteType

enum (QuoteType)

Apenas saída. O tipo de cotação.
plaintextBody

string

Apenas saída. Snapshot do corpo de texto da mensagem original no momento da citação ou do encaminhamento. Formatado usando Markdown para FORWARD e texto simples para REPLY.
sender

string

Apenas saída. O nome de exibição do autor da mensagem original.
attachments[]

object (ChatAttachmentMetadata)

Apenas saída. Anexos que faziam parte da mensagem original. Preenchido apenas para o tipo de cotação FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Apenas saída. Metadados sobre a conversa de origem da mensagem encaminhada. Preenchido apenas para o tipo de cotação FORWARD.

ForwardedMetadata

Representação JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Campos
conversationId

string

Apenas saída. O nome do recurso da conversa de origem. Formato: spaces/{space}
conversationDisplayName

string

Apenas saída. O nome de exibição da conversa de origem no momento em que a mensagem foi encaminhada. Para espaços com nome, é o nome do espaço. Nas mensagens diretas individuais, é o nome do outro participante. Para grupos de chat sem nome, esse é um nome gerado com base nos nomes dos participantes.

UserType

O tipo de usuário do Google Chat.

Tipos enumerados
USER_TYPE_UNSPECIFIED Não especificado.
HUMAN Usuário humano.
APP Usuário do app.

Origem

A origem do anexo.

Tipos enumerados
SOURCE_UNSPECIFIED Reservado.
DRIVE_FILE O arquivo é do Google Drive.
UPLOADED_CONTENT O arquivo é enviado para o Chat.

QuoteType

O tipo de citação que indica se a mensagem é uma resposta de citação ou uma mensagem encaminhada.

Tipos enumerados
QUOTE_TYPE_UNSPECIFIED Reservado. Tipo de cotação indefinido.
REPLY A mensagem é uma resposta com citação a uma mensagem original na mesma conversa.
FORWARD A mensagem é encaminhada de uma mensagem original em outra conversa ou de uma conversa diferente na mesma conversa.

Anotações de ferramentas

As anotações de ferramentas são enviadas aos clientes do MCP para descrever o risco básico de uma determinada ferramenta. A maioria dos clientes trata essas dicas como não confiáveis, mas elas podem ser usadas para decidir quando um pedido de confirmação pode ser enviado a um usuário.

Além da string de título, as seguintes dicas booleanas são definidas:

  • readOnlyHint: se for verdadeiro, a ferramenta não modifica o ambiente. (Padrão: falso).
  • destructiveHint: se for verdadeiro, a ferramenta poderá realizar ações destrutivas. Se for falso, a ferramenta só poderá realizar ações aditivas. Padrão: verdadeiro.
  • idempotentHint: se for verdadeiro, chamar a ferramenta repetidamente com os mesmos argumentos não terá efeito adicional no ambiente. (Padrão: falso).
  • openWorldHint: se for verdadeiro, a ferramenta poderá interagir com um "mundo aberto" de entidades externas. Se for falso, a ferramenta só poderá interagir com entidades internas. Por exemplo, uma ferramenta de pesquisa na Web seria de mundo aberto, enquanto uma ferramenta de memória não seria.

Dica destrutiva: ❌ | Dica idempotente: ✅ | Dica somente leitura: ✅ | Dica de jogos de mundo aberto: ❌

Escopos de autorização

Requer um dos seguintes escopos do OAuth:

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.readonly