MCP Tools Reference: chatmcp.googleapis.com

Outil : search_conversations

Recherche des conversations Google Chat pour trouver les ID de conversation. Les espaces nommés sont identifiés par leur nom à afficher (space_name_query). Les messages privés (MP) et les chats de groupe ne sont identifiés que par les adresses e-mail des participants (participants).

Cet outil recherche les métadonnées de la conversation, PAS le contenu des messages. Pour effectuer une recherche dans l'historique des messages ou trouver des messages par mot clé, expéditeur ou code temporel, utilisez search_messages.

Si seuls les participants sont fournis, cet outil recherche les messages privés (si un participant est fourni) ou les chats de groupe (si plusieurs participants sont fournis) qui incluent les participants spécifiés et l'utilisateur appelant. Les espaces nommés ne sont pas renvoyés.

Si seul un space_name_query est fourni, cet outil ne recherche QUE les espaces nommés dont la requête est une sous-chaîne non sensible à la casse du nom à afficher de l'espace. Les messages privés et les chats de groupe ne sont jamais renvoyés. Ne transmettez donc PAS le nom d'une personne en tant que space_name_query pour trouver un message privé avec elle. Recherchez plutôt son adresse e-mail et transmettez-la dans participants.

Si les deux options participants et space_name_query sont fournies, cet outil recherche les MP ou les chats de groupe par participant, puis les filtre par nom à afficher.

Si ni participants ni space_name_query ne sont fournis, cet outil liste les espaces nommés dont l'utilisateur appelant est membre (les messages privés et les chats de groupe ne sont pas inclus).

Cet outil ne liste que les conversations dont l'utilisateur appelant est membre.

Renvoie une liste d'objets de conversation contenant des ID de conversation (format : spaces/{space}), des noms à afficher et des types de conversation.

IMPORTANT : Une liste conversations vide ne signifie pas qu'il n'y a plus de résultats. Si next_page_token est présent, d'autres pages peuvent être récupérées. Si vous obtenez une liste vide, mais un next_page_token, demandez à l'utilisateur si vous devez continuer la recherche.

L'exemple de code suivant montre comment utiliser curl pour appeler l'outil MCP search_conversations.

Requête 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": "search_conversations",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Schéma d'entrée

SearchConversationsRequest

Représentation JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Champs
spaceNameQuery

string

Facultatif. Texte à rechercher dans les noms à afficher des conversations (correspondance de sous-chaîne non sensible à la casse).

Si participants est vide, seuls les espaces nommés sont recherchés, et les messages privés (MP) et les chats de groupe ne sont jamais renvoyés. Par conséquent, rechercher le nom d'une personne ici ne permettra pas de trouver un MP avec elle. Pour trouver un MP ou un chat de groupe, indiquez plutôt les adresses e-mail des membres dans participants. Si participants est défini, cette requête filtre davantage les MP ou les chats de groupe correspondants par nom à afficher.
pageSize

integer

Facultatif. Nombre maximal d'espaces à renvoyer. Le service peut renvoyer un nombre inférieur à cette valeur. Si ce paramètre n'est pas spécifié, 20 espaces au maximum sont renvoyés. La valeur maximale est 1 000. Les valeurs supérieures sont réduites à 1 000.
pageToken

string

Facultatif. Jeton de page reçu d'un appel search_conversations précédent. Fournissez-le pour récupérer la page suivante.
participants[]

string

Facultatif. Liste des adresses e-mail des participants pour filtrer les conversations, à l'exclusion de l'appelant. Utilisez cette option pour rechercher des messages privés (MP) et des chats de groupe : un seul participant renvoie le MP avec cette personne, et plusieurs participants renvoient les chats de groupe les contenant tous. Les espaces nommés ne sont pas renvoyés lorsque ce champ est défini.

Schéma de sortie

Réponse contenant la liste des conversations correspondantes.

SearchConversationsResponse

Représentation JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Champs
conversations[]

object (Conversation)

Liste des objets de conversation correspondant aux critères de recherche. Chaque conversation inclut les éléments conversation_id (format : spaces/{space}), display_name, conversation_type et last_active_timestamp.
nextPageToken

string

Jeton pouvant être envoyé en tant que page_token pour récupérer la page suivante. Si ce champ est omis, il n'y a pas d'autres pages.

N'est renseigné que si la requête est filtrée par participants.

Conversation

Représentation JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Champs
conversationId

string

ID de la conversation (par exemple, "spaces/AAAAAAAAA").
displayName

string

Nom à afficher de la conversation. Pour les espaces nommés, il s'agit du nom de l'espace. Pour les messages privés, il s'agit du nom de l'autre participant. Pour les chats de groupe sans nom, il s'agit d'un nom généré en fonction des noms des membres.
conversationType

enum (ConversationType)

Type de conversation (DIRECT_MESSAGE, GROUP_CHAT ou NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Dernière heure d'activité de la conversation au format ISO 8601.

Utilise la norme RFC 3339, où la sortie générée utilise toujours le format UTC (indiqué par "Z" pour le temps universel coordonné) avec des secondes fractionnaires de 0, 3, 6 ou 9 chiffres décimaux. Des décalages horaires autres que "Z" (UTC) sont également acceptés. Exemples : "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" ou "2014-10-02T15:01:23+05:30".

Code temporel

Représentation JSON 
{
  "seconds": string,
  "nanos": integer
}
Champs
seconds

string (int64 format)

Représente les secondes de l'heure UTC à partir de l'epoch Unix 1970-01-01T00:00:00Z. Doit être compris entre -62135596800 et 253402300799 inclus (ce qui correspond à 0001-01-01T00:00:00Z à 9999-12-31T23:59:59Z).
nanos

integer

Fractions de secondes non négatives avec une précision de l'ordre de la nanoseconde. Ce champ correspond à la partie en nanosecondes de la durée, et non à une alternative aux secondes. Les valeurs de secondes négatives avec des fractions doivent toujours comporter des valeurs de nanosecondes non négatives comptabilisées dans le temps. La valeur doit être comprise entre 0 et 999 999 999 (inclus).

ConversationType

Définit le type de conversation.

Enums
CONVERSATION_TYPE_UNSPECIFIED Non spécifié.
NAMED_SPACE Un espace nommé.
GROUP_CHAT Un chat de groupe entre trois personnes ou plus.
DIRECT_MESSAGE Message privé entre deux personnes, ou entre une personne et une application Chat.

Annotations d'outils

Les annotations d'outil sont envoyées aux clients MCP pour décrire le risque de base d'un outil donné. La plupart des clients considèrent ces indications comme non fiables, mais elles peuvent être utilisées pour décider quand envoyer une invite de confirmation à un utilisateur.

En plus de la chaîne de titre, les indications booléennes suivantes sont définies comme suit :

  • readOnlyHint : si la valeur est "true", l'outil ne modifie pas son environnement. Valeur par défaut : "false".
  • destructiveHint : si la valeur est "true", l'outil peut effectuer des actions destructrices. Si la valeur est "false", l'outil ne peut effectuer que des actions d'ajout. Valeur par défaut : "true".
  • idempotentHint : si la valeur est "true", l'appel répété de l'outil avec les mêmes arguments n'aura aucun effet supplémentaire sur son environnement. Valeur par défaut : "false".
  • openWorldHint : si la valeur est "true", l'outil peut interagir avec un "monde ouvert" d'entités externes. Si la valeur est "false", l'outil ne peut interagir qu'avec des entités internes. Par exemple, un outil de recherche sur le Web serait en monde ouvert, tandis qu'un outil de mémoire ne le serait pas.

Indice de destructivité : ❌ | Indice d'idempotence : ✅ | Indice de lecture seule : ✅ | Indice de monde ouvert : ❌

Champs d'application des autorisations

Nécessite l'un des champs d'application OAuth suivants :

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly