MCP Tools Reference: chatmcp.googleapis.com

Strumento: send_message

Invia un messaggio chat di Google Chat a una conversazione con formattazione Markdown.

Questo strumento utilizza come input un ID conversazione, un ID thread facoltativo e un testo del messaggio.

Gli ID conversazione possono essere trovati utilizzando lo strumento search_conversations.

Restituisce il messaggio creato.

Il seguente esempio di codice mostra come utilizzare curl per chiamare lo strumento MCP send_message.

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

Schema di input

SendMessageRequest

Rappresentazione JSON 
{
  "conversationId": string,
  "threadId": string,
  "messageText": string,
  "cards": [
    {
      object
    }
  ],
  "inlineCitations": [
    {
      object (Citation)
    }
  ],
  "footerCitedSources": [
    {
      object (CitedSource)
    }
  ]
}
Campi
conversationId

string

Obbligatorio. L'ID della conversazione (ad es. "spaces/AAAA…") a cui inviare il messaggio.
threadId

string

Facoltativo. L'ID del thread (ad es. "spaces/AAAA…/threads/BBBB…") a cui inviare il messaggio. Se non viene impostato, il messaggio verrà inviato a un nuovo thread.
messageText

string

Obbligatorio. I contenuti principali del messaggio. La formattazione può essere aggiunta utilizzando il linguaggio Markdown standard (tieni presente che le tabelle NON sono supportate). È supportata la seguente formattazione:

  • Grassetto: **text**
  • Corsivo: *text* o _text_
  • Barrato: ~~text~~
  • Monospace: text
  • Blocco a spaziatura fissa:
```
line 1
line 2
```
  • Elenco puntato:
* item 1
* item 2
  • Elenco ordinato:
1. item 1
2. item 2
  • Citazione a blocco: > quoted text
  • Link ipertestuale: [label](url)
  • Menziona utente: utilizza un tag HTML con chiusura automatica chat-user con gli attributi data-email="user@example.com" o data-user="users/USER_ID". Preferisci l'attributo data-user con USER_ID, se noto, e utilizza l'attributo data-email con l'indirizzo email dell'utente in caso contrario. Se utilizzi l'attributo data-user, assicurati di includere il prefisso users/ visualizzato nei valori restituiti da altri strumenti. Nota: sono consentite al massimo 10 menzioni per messaggio. È severamente vietato menzionare tutti gli utenti (ad es. utilizzando @all o un tag HTML con users/all).
  • Emoji personalizzate: utilizza un tag HTML con chiusura automatica chat-emoji con gli attributi data-custom-emoji="customEmojis/abc" o data-emoji-name=":xyz:".
  • Citazione: racchiudi il testo citato in un tag HTML chat-citation con l'attributo data-id corrispondente all'ID citazione. Se un tag chat-citation ha un data-id che non corrisponde ad alcun Citation.id, il tag viene ignorato e il testo racchiuso viene visualizzato come testo normale. Nota: sono consentite massimo 20 citazioni in linea per messaggio.
cards[]

object (Struct format)

Facoltativo. Schede allegate al messaggio. La dimensione massima è di 32 kB per tessera. Ogni scheda è rappresentata come una struttura JSON che segue il formato della scheda di Google Chat (scheda UIKit di Google Workspace/Cards v2). Per allegare schede a un messaggio, l'app di Chat deve essere un membro dello spazio. Le immagini nelle schede non sono supportate.

Identificazione della carta:

  • Il campo stringa name di primo livello in ogni scheda funge da identificatore.
  • Se a un messaggio sono allegate più schede, ogni scheda DEVE specificare un name univoco e non vuoto.
inlineCitations[]

object (Citation)

Facoltativo. Citazioni in linea a cui viene fatto riferimento all'interno di message_text tramite i tag chat-citation. Sono consentite massimo 20 citazioni in linea per messaggio. Le citazioni in linea non referenziate (quelle senza un tag chat-citation corrispondente in message_text) vengono ignorate e non causano un errore di convalida.
footerCitedSources[]

object (CitedSource)

Facoltativo. Le fonti citate di primo livello vengono visualizzate come schede di riferimento nella parte inferiore (piè di pagina) del messaggio. In totale, sono consentite al massimo 50 fonti citate tra tutte le citazioni in linea e le fonti a piè di pagina di un messaggio.

Struct

Rappresentazione JSON 
{
  "fields": {
    string: value,
    ...
  }
}
Campi
fields

map (key: string, value: value (Value format))

Mappa non ordinata di valori con tipo dinamico.

Un oggetto contenente un elenco di coppie "key": value. Esempio: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

Rappresentazione JSON 
{
  "key": string,
  "value": value
}
Campi
key

string
value

value (Value format)

Valore

Rappresentazione JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
Campi
Campo unione kind. Il tipo di valore. kind può essere solo uno dei seguenti tipi:
nullValue

null

Rappresenta un null JSON.
numberValue

number

Rappresenta un numero JSON. Non deve essere NaN, Infinity o -Infinity, poiché questi valori non sono supportati in JSON. Inoltre, non può rappresentare valori Int64 di grandi dimensioni, poiché il formato JSON in genere non li supporta nel tipo di numero.
stringValue

string

Rappresenta una stringa JSON.
boolValue

boolean

Rappresentano un valore booleano JSON (valore letterale true o false in JSON).
structValue

object (Struct format)

Rappresenta un oggetto JSON.
listValue

array (ListValue format)

Rappresenta un array JSON.

ListValue

Rappresentazione JSON 
{
  "values": [
    value
  ]
}
Campi
values[]

value (Value format)

Campo ripetuto di valori con tipo dinamico.

Citazione

Rappresentazione JSON 
{
  "id": string,
  "citedSources": [
    {
      object (CitedSource)
    }
  ]
}
Campi
id

string

Obbligatorio. Identificatore univoco corrispondente all'attributo data-id nel tag chat-citation (ad es. racchiudendo il testo citato con chat-citation e l'attributo data-id="ID") in message_text. Deve essere composto solo da lettere ASCII, numeri, trattini bassi o trattini (1-63 caratteri). Deve essere univoco tra tutte le citazioni nel messaggio.
citedSources[]

object (CitedSource)

Obbligatorio. Una o più fonti allegate a questa scheda popup della citazione. In totale, sono consentite al massimo 50 fonti citate tra tutte le citazioni in linea e le fonti a piè di pagina di un messaggio.

CitedSource

Rappresentazione JSON 
{
  "title": string,
  "url": string,
  "snippet": string,
  "imageUrl": string,
  "footer": string
}
Campi
title

string

Obbligatorio. Titolo in testo normale della fonte (ad es. "Programma Anteprima per gli sviluppatori di Google Workspace"). La formattazione Markdown non è supportata nei titoli.
url

string

Obbligatorio. L'URL della risorsa citata (deve essere un URL http:// o https:// valido, ad esempio "https://developers.google.com/workspace/preview").
snippet

string

Facoltativo. Un breve estratto o snippet direttamente dalla fonte. Visualizzato nella scheda popup o nel piè di pagina. Solo testo normale. La lunghezza massima è di 1000 caratteri.
imageUrl

string

Facoltativo. URL di una miniatura di anteprima dell'immagine (deve utilizzare un URL https://).
footer

string

Facoltativo. Testo dell'attribuzione aggiuntivo visualizzato nel piè di pagina della scheda (ad es. nome di dominio "developers.google.com" o nome dell'autore/dell'organizzazione).

NullValue

Rappresenta un null JSON.

NullValue è un sentinel che utilizza un enum con un solo valore per rappresentare il valore null per l'unione di tipi Value.

Un campo di tipo NullValue con un valore diverso da 0 è considerato non valido. La maggior parte dei serializzatori ProtoJSON emetterà un Value con un null_value impostato come null JSON indipendentemente dal valore intero, quindi eseguirà un round trip a un valore 0.

Enum
NULL_VALUE Valore null.

Schema di output

Risposta all'invio di un messaggio a una conversazione di Google Chat.

SendMessageResponse

Rappresentazione JSON 
{
  "message": {
    object (ChatMessage)
  }
}
Campi
message

object (ChatMessage)

Il messaggio inviato.

ChatMessage

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

string

Nome della risorsa del messaggio. Formato: spaces/{space}/messages/{message}
threadId

string

Il thread a cui appartiene questo messaggio. Questo campo sarà vuoto se il messaggio non è in un thread. Formato: spaces/{space}/threads/{thread}
plaintextBody

string

Corpo del testo del messaggio che utilizza la formattazione Markdown.
sender

object (User)

Il mittente del messaggio.
createTime

string

Solo output. Timestamp della creazione del messaggio. Formato: timestamp ISO 8601.
threadedReply

boolean

Indica se il messaggio è una risposta a un thread.
attachments[]

object (ChatAttachmentMetadata)

Allegati inclusi nel messaggio.
reactionSummaries[]

object (ReactionSummary)

Il riepilogo delle reazioni con emoji incluso nel messaggio.
quotedMessageMetadata

object (QuotedMessageMetadata)

Solo output. Informazioni su un messaggio originale citato o inoltrato in questo messaggio. Nota: questo campo è in fase di sviluppo e potrebbe non essere ancora presente in tutti gli ambienti.

Utente

Rappresentazione JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Campi
userId

string

Nome risorsa di un utente di Chat. Formato: users/{user}.
displayName

string

Il nome visualizzato di un utente di Chat.
email

string

L'indirizzo email dell'utente. Questo campo viene compilato solo quando il tipo di utente è HUMAN.
userType

enum (UserType)

Il tipo di utente.

ChatAttachmentMetadata

Rappresentazione JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Campi
attachmentId

string

Nome della risorsa dell'allegato. Formato: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nome dell'allegato.
mimeType

string

Tipo di contenuti (tipo MIME).
source

enum (Source)

La fonte dell'allegato.
driveFileId

string

Solo output. L'ID del file di Google Drive. Compilato solo quando l'origine è DRIVE_FILE. Utilizzalo con l'MCP di Google Drive.

ReactionSummary

Rappresentazione JSON 
{
  "emoji": string,
  "count": integer
}
Campi
emoji

string

La stringa Unicode dell'emoji o il nome dell'emoji personalizzata.
count

integer

Il numero totale di reazioni che utilizzano l'emoji associata.

QuotedMessageMetadata

Rappresentazione JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Campi
messageId

string

Solo output. Nome della risorsa del messaggio originale citato o inoltrato. Formato: spaces/{space}/messages/{message}
lastUpdateTime

string

Solo output. Timestamp della creazione o dell'ultimo aggiornamento del messaggio originale prima che venisse citato o inoltrato. Formato: timestamp ISO 8601.
quoteType

enum (QuoteType)

Solo output. Il tipo di citazione.
plaintextBody

string

Solo output. Istantanea del corpo del testo del messaggio originale al momento della citazione o dell'inoltro. Formattato utilizzando Markdown per FORWARD e testo normale per REPLY.
sender

string

Solo output. Il nome visualizzato dell'autore del messaggio originale.
attachments[]

object (ChatAttachmentMetadata)

Solo output. Gli allegati che facevano parte del messaggio originale. Compilato solo per il tipo di preventivo FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Solo output. Metadati relativi alla conversazione di origine del messaggio inoltrato. Compilato solo per il tipo di preventivo FORWARD.

ForwardedMetadata

Rappresentazione JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Campi
conversationId

string

Solo output. Il nome della risorsa della conversazione di origine. Formato: spaces/{space}
conversationDisplayName

string

Solo output. Il nome visualizzato della conversazione di origine al momento dell'inoltro del messaggio. Per gli spazi con nome, si tratta del nome dello spazio. Per i messaggi diretti 1:1, si tratta del nome dell'altro partecipante. Per le chat di gruppo senza nome, si tratta di un nome generato in base ai nomi dei membri.

UserType

Il tipo di utente di Google Chat.

Enum
USER_TYPE_UNSPECIFIED Non specificato.
HUMAN Utente umano.
APP Utente dell'app.

Origine

La fonte dell'allegato.

Enum
SOURCE_UNSPECIFIED Riservato.
DRIVE_FILE Il file è un file di Google Drive.
UPLOADED_CONTENT Il file viene caricato in Chat.

QuoteType

Il tipo di citazione che indica se il messaggio è una risposta con citazione o un messaggio inoltrato.

Enum
QUOTE_TYPE_UNSPECIFIED Riservato. Tipo di preventivo non definito.
REPLY Il messaggio è una risposta con citazione a un messaggio originale nello stesso thread.
FORWARD Il messaggio viene inoltrato da un messaggio originale in una conversazione diversa o da un thread diverso nella stessa conversazione.

Annotazioni dello strumento

Le annotazioni degli strumenti vengono inviate ai client MCP per descrivere il rischio di base di un determinato strumento. La maggior parte dei client considera questi suggerimenti non attendibili, ma possono essere utilizzati per decidere quando inviare una richiesta di conferma a un utente.

Oltre alla stringa del titolo, i seguenti suggerimenti booleani sono definiti come segue:

  • readOnlyHint: se true, lo strumento non modifica il suo ambiente. Valore predefinito: false.
  • destructiveHint: se true, lo strumento può eseguire azioni distruttive. Se è false, lo strumento può eseguire solo azioni additive. Valore predefinito: true.
  • idempotentHint: se true, la chiamata ripetuta dello strumento con gli stessi argomenti non avrà alcun effetto aggiuntivo sul suo ambiente. Valore predefinito: false.
  • openWorldHint: se true, lo strumento può interagire con un "open world" di entità esterne. Se false, lo strumento può interagire solo con entità interne. Ad esempio, uno strumento di ricerca web sarebbe open world, mentre uno strumento di memoria non lo sarebbe.

Suggerimento distruttivo: ❌ | Suggerimento idempotente: ❌ | Suggerimento di sola lettura: ❌ | Suggerimento open world: ✅

Ambiti di autorizzazione

Richiede uno dei seguenti ambiti OAuth:

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