## Tool: `send_message`

> [!WARNING]
> **Developer Preview:** Available as part of the [Google Workspace Developer Preview Program](https://developers.google.com/workspace/preview), which grants early access to certain features.

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 |
|---|
| ```bash 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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.Citation`) } ], "footerCitedSources": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.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 (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.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 (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://protobuf.dev/reference/protobuf/google.protobuf#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 (`https://protobuf.dev/reference/protobuf/google.protobuf#struct` format)`` Represents a JSON object. |
| `listValue` | ``array (`https://protobuf.dev/reference/protobuf/google.protobuf#list-value` format)`` Represents a JSON array. |
|   ||

### ListValue

| JSON representation |
|---|
| ``` { "values": [ value ] } ``` |

| Fields ||
|---|---|
| `values[]` | ``value (`https://protobuf.dev/reference/protobuf/google.protobuf#value` format)`` Repeated field of dynamically typed values. |

### Citation

| JSON representation |
|---|
| ``` { "id": string, "citedSources": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/send_message#Input.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatMessage`) } } ``` |

| Fields ||
|---|---|
| `message` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatMessage`)`` The message that was sent. |

### ChatMessage

| JSON representation |
|---|
| ``` { "messageId": string, "threadId": string, "plaintextBody": string, "sender": { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.User`) }, "createTime": string, "threadedReply": boolean, "attachments": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatAttachmentMetadata`) } ], "reactionSummaries": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ReactionSummary`) } ], "quotedMessageMetadata": { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatAttachmentMetadata`)`` Attachments included in the message. |
| `reactionSummaries[]` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ReactionSummary`)`` The emoji reactions summary included in the message. |
| `quotedMessageMetadata` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.UserType`)`` The type of the user. |

### ChatAttachmentMetadata

| JSON representation |
|---|
| ``` { "attachmentId": string, "filename": string, "mimeType": string, "source": enum (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.QuoteType`), "plaintextBody": string, "sender": string, "attachments": [ { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatAttachmentMetadata`) } ], "forwardedMetadata": { object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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 (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.ChatAttachmentMetadata`)`` Output only. Attachments that were part of the original message. Populated only for the `FORWARD` quote type. |
| `forwardedMetadata` | ``object (`https://developers.google.com/workspace/chat/api/reference/mcp/tools_list/list_messages#Output.Schema.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](https://modelcontextprotocol.io/specification/latest/schema#toolannotations) 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`