MCP Tools Reference: chatmcp.googleapis.com

Tool: send_message

Sends a Google Chat message to a conversation with Markdown formatting.

This tool uses a conversation ID, an optional thread ID, and a message text as inputs.

Conversation IDs can be found using the search_conversations tool.

It returns the created message.

The following code sample shows how to use curl to call the send_message MCP tool.

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

Input Schema

SendMessageRequest

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

string

Required. The ID of the conversation (e.g., 'spaces/AAAA...') to send the message to.
threadId

string

Optional. The ID of the thread (e.g., 'spaces/AAAA.../threads/BBBB...') to send the message to. If not set, the message will be sent to a new thread.
messageText

string

Required. The main content of the message. Formatting can be added using standard Markdown (note that tables are NOT supported). The following formatting is supported:

  • Bold: **text**
  • Italic: *text* or _text_
  • Strikethrough: ~~text~~
  • Monospace: text
  • Monospace block:
```
line 1
line 2
```
  • Bulleted list:
* item 1
* item 2
  • Ordered list:
1. item 1
2. item 2
  • Block quote: > quoted text
  • Hyperlink: [label](url)
  • Mention user: Use a self-closing HTML tag chat-user with attributes data-email="user@example.com" or data-user="users/USER_ID". Prefer the data-user attribute with USER_ID if known and fall back to the data-email attribute with the user email otherwise. If you use the data-user attribute make sure to include the users/ prefix seen in other tool return values. Note: A maximum of 10 mentions are allowed per message. Mentioning all users (e.g., using @all or an HTML tag with users/all) is strictly prohibited.
  • Custom emoji: Use a self-closing HTML tag chat-emoji with attributes data-custom-emoji="customEmojis/abc" or data-emoji-name=":xyz:".
  • Citation: Wrap the cited text in an HTML tag chat-citation with the data-id attribute matching the citation ID. If a chat-citation tag has a data-id that does not match any Citation.id, the tag is ignored and the wrapped text is rendered as plain text. Note: A maximum of 20 inline citations are allowed per message.
cards[]

object (Struct format)

Optional. Cards attached to the message. Maximum size is 32 KB per card. Each card is represented as a JSON struct following the Google Chat Card format (Google Workspace UIKit Card / Cards v2). To attach cards to a message, the Chat app must be a member of the space. Images in cards aren't supported.

Card identification:

  • The top-level name string field in each card serves as its identifier.
  • If multiple cards are attached to a message, each card MUST specify a unique, non-empty name.
inlineCitations[]

object (Citation)

Optional. Inline citations referenced within message_text via chat-citation tags. A maximum of 20 inline citations are allowed per message. Unreferenced inline citations (those without a matching chat-citation tag in message_text) are ignored and do not cause a validation error.
footerCitedSources[]

object (CitedSource)

Optional. Top-level cited sources displayed as reference cards at the bottom (footer) of the message. A maximum of 50 cited sources are allowed in total across all inline citations and footer sources in a message.

Struct

JSON representation 
{
  "fields": {
    string: value,
    ...
  }
}
Fields
fields

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

Unordered map of dynamically typed values.

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

JSON representation 
{
  "key": string,
  "value": value
}
Fields
key

string
value

value (Value format)

Value

JSON representation 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
Fields
Union field kind. The kind of value. kind can be only one of the following:
nullValue

null

Represents a JSON null.
numberValue

number

Represents a JSON number. Must not be NaN, Infinity or -Infinity, since those are not supported in JSON. This also cannot represent large Int64 values, since JSON format generally does not support them in its number type.
stringValue

string

Represents a JSON string.
boolValue

boolean

Represents a JSON boolean (true or false literal in JSON).
structValue

object (Struct format)

Represents a JSON object.
listValue

array (ListValue format)

Represents a JSON array.

ListValue

JSON representation 
{
  "values": [
    value
  ]
}
Fields
values[]

value (Value format)

Repeated field of dynamically typed values.

Citation

JSON representation 
{
  "id": string,
  "citedSources": [
    {
      object (CitedSource)
    }
  ]
}
Fields
id

string

Required. Unique identifier matching the data-id attribute in the chat-citation tag (e.g. wrapping cited text with chat-citation and attribute data-id="ID") in message_text. Must consist only of ASCII letters, digits, underscores, or hyphens (1-63 characters). Must be unique among all citations in the message.
citedSources[]

object (CitedSource)

Required. One or more sources attached to this citation hovercard. A maximum of 50 cited sources are allowed in total across all inline citations and footer sources in a message.

CitedSource

JSON representation 
{
  "title": string,
  "url": string,
  "snippet": string,
  "imageUrl": string,
  "footer": string
}
Fields
title

string

Required. Plaintext title of the source (e.g., "Google Workspace Developer Preview Program"). Markdown formatting is not supported in titles.
url

string

Required. The URL of the cited resource (must be a valid http:// or https:// URL, e.g., "https://developers.google.com/workspace/preview").
snippet

string

Optional. A short excerpt or snippet directly from the source. Displayed in the hovercard or footer. Plain text only. Maximum length is 1,000 characters.
imageUrl

string

Optional. URL of an image preview thumbnail (must use an https:// URL).
footer

string

Optional. Additional attribution text displayed in the card footer (e.g. domain name "developers.google.com" or author/org name).

NullValue

Represents a JSON null.

NullValue is a sentinel, using an enum with only one value to represent the null value for the Value type union.

A field of type NullValue with any value other than 0 is considered invalid. Most ProtoJSON serializers will emit a Value with a null_value set as a JSON null regardless of the integer value, and so will round trip to a 0 value.

Enums
NULL_VALUE Null value.

Output Schema

Response to sending a message to a Google Chat conversation.

SendMessageResponse

JSON representation 
{
  "message": {
    object (ChatMessage)
  }
}
Fields
message

object (ChatMessage)

The message that was sent.

ChatMessage

JSON representation 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
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

Text body of the message using Markdown formatting.
sender

object (User)

The sender of the message.
createTime

string

Output only. Timestamp when the message was created. Format: ISO 8601 timestamp.
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.
quotedMessageMetadata

object (QuotedMessageMetadata)

Output only. Information about an original message that is quoted or forwarded in this message. Note: This field is under development and may not be present in all environments yet.

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),
  "driveFileId": string
}
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.
driveFileId

string

Output only. The ID for the Google Drive file. Only populated when the source is DRIVE_FILE. Use with the Google Drive MCP.

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.

QuotedMessageMetadata

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

string

Output only. Resource name of the original message that is quoted or forwarded. Format: spaces/{space}/messages/{message}
lastUpdateTime

string

Output only. Timestamp when the original message was created or last updated prior to being quoted or forwarded. Format: ISO 8601 timestamp.
quoteType

enum (QuoteType)

Output only. The type of quote.
plaintextBody

string

Output only. Snapshot of the text body of the original message at the time of quoting or forwarding. Formatted using Markdown for FORWARD, and plain text for REPLY.
sender

string

Output only. The author display name of the original message.
attachments[]

object (ChatAttachmentMetadata)

Output only. Attachments that were part of the original message. Populated only for the FORWARD quote type.
forwardedMetadata

object (ForwardedMetadata)

Output only. Metadata about the source conversation of the forwarded message. Populated only for the FORWARD quote type.

ForwardedMetadata

JSON representation 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Fields
conversationId

string

Output only. The resource name of the source conversation. Format: spaces/{space}
conversationDisplayName

string

Output only. The display name of the source conversation at the time the message was forwarded. For named spaces, this is the space name. For 1:1 direct messages, this is the other participant's name. For unnamed group chats, this is a generated name based on members' names.

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.

QuoteType

The quote type indicating whether the message is a quote reply or a forwarded message.

Enums
QUOTE_TYPE_UNSPECIFIED Reserved. Undefined quote type.
REPLY The message is a quote reply to an original message in the same thread.
FORWARD The message is forwarded from an original message in a different conversation, or from a different thread in the same conversation.

Tool Annotations

Tool annotations are sent to MCP clients to describe the basic risk of a given tool. Most clients treat these hints as untrusted, but they can be used to decide when a confirmation prompt might be sent to a user.

Along with the title string, the following boolean hints are defined as follows:

  • readOnlyHint: If true, the tool doesn't modify its environment. Default: false.
  • destructiveHint: If true, then the tool can perform destructive actions. If false, then the tool can only perform additive actions. Default: true.
  • idempotentHint: If true, then calling the tool repeatedly with the same arguments will have no additional effect on its environment. Default: false.
  • openWorldHint: If true, then the tool can interact with an 'open world' of external entities. If false, then the tool can only interact with internal entities. For example, a web search tool would be open world, while a memory tool would not be open world.

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

Authorization Scopes

Requires one of the following OAuth scopes:

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