MCP Tools Reference: chatmcp.googleapis.com

ابزار: send_message

پیام Google Chat را با قالب‌بندی Markdown به مکالمه ارسال می‌کند.

این ابزار از شناسه مکالمه، شناسه رشته اختیاری، و نوشتار پیام به‌عنوان ورودی استفاده می‌کند.

شناسه‌های مکالمه را می‌توان بااستفاده از ابزار search_conversations پیدا کرد.

پیام ایجادشده را برمی‌گرداند.

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار MCP send_message را نشان می‌دهد.

درخواست 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
}'

طرح‌واره ورودی

SendMessageRequest

نمایش JSON 
{
  "conversationId": string,
  "threadId": string,
  "messageText": string,
  "cards": [
    {
      object
    }
  ],
  "inlineCitations": [
    {
      object (Citation)
    }
  ],
  "footerCitedSources": [
    {
      object (CitedSource)
    }
  ]
}
فیلدها
conversationId

string

الزامی. شناسه مکالمه (مثلاً «spaces/AAAA...») برای ارسال پیام به آن.
threadId

string

اختیاری. شناسه رشته (مثلاً spaces/AAAA.../threads/BBBB...) برای ارسال پیام به آن. اگر تنظیم نشده باشد، پیام به رشته جدیدی ارسال خواهد شد.
messageText

string

الزامی. محتوای اصلی پیام. قالب‌بندی را می‌توان بااستفاده از Markdown استاندارد اضافه کرد (توجه داشته باشید که از جدول‌ها پشتیبانی نمی‌شود). قالب‌بندی زیر پشتیبانی می‌شود:

  • پررنگ: **text**
  • ایتالیک: *text* یا _text_
  • خط‌خورده: ~~text~~
  • تک‌فاصله: text
  • بلوک تک‌فاصله:
```
line 1
line 2
```
  • فهرست گلوله‌ای:
* item 1
* item 2
  • فهرست مرتب‌شده:
1. item 1
2. item 2
  • نقل‌قول کشیده: > quoted text
  • اَبَرپیوند: [label](url)
  • نام بردن از کاربر: از تگ HTML خودبسته chat-user با مشخصه‌های data-email="user@example.com" یا data-user="users/USER_ID" استفاده کنید. درصورت مشخص بودن، مشخصه data-user با USER_ID را ترجیح دهید و درغیراین‌صورت به مشخصه data-email با ایمیل کاربر برگردید. اگر از مشخصه data-user استفاده می‌کنید، حتماً پیشوند users/ را که در مقادیر برگشتی ابزار دیگر دیده می‌شود اضافه کنید. توجه: حداکثر ۱۰ نامبردن در هر پیام مجاز است. نام بردن از همه کاربران (مثلاً بااستفاده از @all یا برچسب HTML با users/all) اکیداً ممنوع است.
  • اموجی سفارشی: از برچسب HTML خودبسته chat-emoji با مشخصه‌های data-custom-emoji="customEmojis/abc" یا data-emoji-name=":xyz:" استفاده کنید.
  • نقل‌قول: نوشتار نقل‌شده را در تگ HTML chat-citation با مشخصه data-id مطابق با شناسه نقل‌قول قرار دهید. اگر برچسب chat-citation دارای data-id باشد که با هیچ Citation.id مطابقت نداشته باشد، برچسب نادیده گرفته می‌شود و نوشتار پیچیده به‌عنوان نوشتار ساده ارائه می‌شود. توجه: حداکثر ۲۰ نقل‌قول درون‌خطی برای هر پیام مجاز است.
cards[]

object (Struct format)

اختیاری. کارت‌ها به پیام پیوست شد. حداکثر اندازه برای هر کارت ۳۲ کیلوبایت است. هر کارت به‌عنوان یک ساختار JSON مطابق با قالب «کارت Google Chat» (کارت Google Workspace UIKit / کارت‌های نسخه ۲) نمایش داده می‌شود. برای پیوست کردن کارت به پیام، برنامه Chat باید عضو فضا باشد. تصاویر در کارت‌ها پشتیبانی نمی‌شوند.

شناسه کارت:

  • فیلد رشته name سطح بالا در هر کارت به‌عنوان شناسه آن عمل می‌کند.
  • اگر چند کارت به پیامی پیوست شده باشد، هر کارت باید name یکتا و غیرخالی را مشخص کند.
inlineCitations[]

object (Citation)

اختیاری. نقل‌قول‌های درون‌خطی ارجاع‌شده در message_text ازطریق برچسب‌های chat-citation. حداکثر ۲۰ نقل‌قول درون‌خطی برای هر پیام مجاز است. نقل‌قول‌های درون‌خطی بدون ارجاع (آن‌هایی که برچسب chat-citation منطبق در message_text ندارند) نادیده گرفته می‌شوند و باعث خطای اعتبارسنجی نمی‌شوند.
footerCitedSources[]

object (CitedSource)

اختیاری. منابع نقل‌شده سطح بالا که به‌عنوان کارت‌های مرجع در پایین (پانویس) پیام نمایش داده می‌شوند. درمجموع حداکثر ۵۰ منبع نقل‌شده در همه نقل‌قول‌های درون‌خطی و منابع پانویس در یک پیام مجاز است.

ساختار

نمایش JSON 
{
  "fields": {
    string: value,
    ...
  }
}
فیلدها
fields

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

نقشه نامرتب مقادیر تایپ‌شده پویا.

شیئی که حاوی فهرستی از جفت‌های "key": value است. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

FieldsEntry

نمایش JSON 
{
  "key": string,
  "value": value
}
فیلدها
key

string
value

value (Value format)

مقدار

نمایش JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
فیلدها
فیلد اتحادیه kind. نوع مقدار. kind فقط می‌تواند یکی از موارد زیر باشد:
nullValue

null

نشان‌دهنده null JSON است.
numberValue

number

نشان‌دهنده عدد JSON است. نباید NaN، Infinity، یا -Infinity باشد، چون این موارد در JSON پشتیبانی نمی‌شوند. این مورد همچنین نمی‌تواند مقادیر بزرگ Int64 را نشان دهد، زیرا قالب JSON معمولاً از آن‌ها در نوع عدد خود پشتیبانی نمی‌کند.
stringValue

string

رشته JSON را نشان می‌دهد.
boolValue

boolean

نشان‌دهنده یک مقدار بولی JSON (true یا false در JSON) است.
structValue

object (Struct format)

نشان‌دهنده شیء JSON است.
listValue

array (ListValue format)

نشان‌دهنده آرایه JSON است.

ListValue

نمایش JSON 
{
  "values": [
    value
  ]
}
فیلدها
values[]

value (Value format)

فیلد تکراری مقادیر تایپ‌شده پویا.

نقل‌قول

نمایش JSON 
{
  "id": string,
  "citedSources": [
    {
      object (CitedSource)
    }
  ]
}
فیلدها
id

string

الزامی. شناسه یکتایی که با مشخصه data-id در برچسب chat-citation مطابقت دارد (مثلاً متن نقل‌شده را با chat-citation و مشخصه data-id="ID" دربرمی‌گیرد) در message_text. باید فقط شامل حروف ASCII، ارقام، زیرخط، یا خط تیره باشد (۱ تا ۶۳ نویسه). باید در میان همه نقل‌قول‌های موجود در پیام منحصربه‌فرد باشد.
citedSources[]

object (CitedSource)

الزامی. یک یا چند منبع به این کارت شناور استناد پیوست شده است. درمجموع حداکثر ۵۰ منبع نقل‌شده در همه نقل‌قول‌های درون‌خطی و منابع پانویس در یک پیام مجاز است.

CitedSource

نمایش JSON 
{
  "title": string,
  "url": string,
  "snippet": string,
  "imageUrl": string,
  "footer": string
}
فیلدها
title

string

الزامی. عنوان نوشتار ساده منبع (مثلاً «برنامه پیش‌نمای توسعه‌دهندگان نرم‌افزار Google Workspace»). قالب‌بندی Markdown در عنوان‌ها پشتیبانی نمی‌شود.
url

string

الزامی. نشانی وب منبع نقل‌شده (باید نشانی وب معتبر http:// ‎ یا https:// ‎ باشد، مثلاً «https://developers.google.com/workspace/preview»).
snippet

string

اختیاری. گزیده یا قطعه‌ای کوتاه مستقیماً از منبع. در کارت شناور یا پانویس نمایش داده می‌شود. فقط نوشتار ساده. حداکثر طول ۱۰۰۰ نویسه است.
imageUrl

string

اختیاری. نشانی وب ریزعکس پیش‌نمایش تصویر (باید از نشانی وب https:// ‎ استفاده کند).
footer

string

اختیاری. نوشتار ارجاع اضافی که در پانویس کارت نمایش داده می‌شود (مثلاً نام دامنه «developers.google.com» یا نام نویسنده/ سازمان).

NullValue

نشان‌دهنده null JSON است.

NullValue یک نگهبان است که از یک شمارش با تنها یک مقدار برای نمایش مقدار تهی برای اتحاد نوع Value استفاده می‌کند.

فیلدی از نوع NullValue با هر مقداری غیراز 0 نامعتبر تلقی می‌شود. اکثر سریال‌سازهای ProtoJSON بدون توجه به مقدار عدد صحیح، یک Value با null_value تنظیم‌شده به‌عنوان JSON null منتشر می‌کنند و بنابراین به مقدار 0 رفت‌وبرگشت خواهند داشت.

شمارشی‌ها
NULL_VALUE مقدار تهی.

طرح خروجی

پاسخ به ارسال پیام به مکالمه Google Chat.

SendMessageResponse

نمایش JSON 
{
  "message": {
    object (ChatMessage)
  }
}
فیلدها
message

object (ChatMessage)

پیامی که ارسال شده است.

ChatMessage

نمایش JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
فیلدها
messageId

string

نام منبع پیام. قالب: spaces/{space}/messages/{message}
threadId

string

رشته‌ای که این پیام به آن تعلق دارد. اگر پیام رشته‌ای نباشد، این قسمت خالی خواهد بود. قالب: spaces/{space}/threads/{thread}
plaintextBody

string

متن اصلی پیام بااستفاده از قالب‌بندی Markdown.
sender

object (User)

فرستنده پیام.
createTime

string

فقط خروجی. مُهر زمان ایجاد پیام. قالب: مُهر زمان ISO 8601.
threadedReply

boolean

آیا پیام پاسخ رشته است.
attachments[]

object (ChatAttachmentMetadata)

پیوست‌ها در پیام گنجانده شده است.
reactionSummaries[]

object (ReactionSummary)

خلاصه واکنش‌های اموجی موجود در پیام.
quotedMessageMetadata

object (QuotedMessageMetadata)

فقط خروجی. اطلاعات درباره پیام اصلی که در این پیام نقل‌قول یا بازارسال شده است. توجه: این فیلد درحال توسعه است و ممکن است هنوز در همه محیط‌ها وجود نداشته باشد.

کاربر

نمایش JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
فیلدها
userId

string

نام منبع کاربر Chat. قالب: users/{user}.
displayName

string

نام نمایشی کاربر Chat.
email

string

نشانی ایمیل کاربر. این فیلد فقط زمانی پر می‌شود که نوع کاربر HUMAN (انسان) باشد.
userType

enum (UserType)

نوع کاربر.

ChatAttachmentMetadata

نمایش JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
فیلدها
attachmentId

string

نام منبع پیوست. قالب: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

نام پیوست.
mimeType

string

نوع محتوا (نوع MIME).
source

enum (Source)

منبع پیوست.
driveFileId

string

فقط خروجی. شناسه فایل Google Drive. فقط زمانی درج می‌شود که منبع DRIVE_FILE باشد. با Google Drive MCP استفاده کنید.

ReactionSummary

نمایش JSON 
{
  "emoji": string,
  "count": integer
}
فیلدها
emoji

string

رشته یونی‌کد اموجی یا نام اموجی سفارشی.
count

integer

تعداد کل واکنش‌ها بااستفاده از اموجی مربوطه.

QuotedMessageMetadata

نمایش JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
فیلدها
messageId

string

فقط خروجی. نام منبع پیام اصلی که نقل‌قول یا بازارسال شده است. قالب: spaces/{space}/messages/{message}
lastUpdateTime

string

فقط خروجی. مُهر زمان مربوط به وقتی که پیام اصلی ایجاد شده یا آخرین‌بار قبل‌از نقل‌قول یا بازارسال شدن به‌روز شده است. قالب: مهر زمان ISO 8601.
quoteType

enum (QuoteType)

فقط خروجی. نوع مظنه قیمت.
plaintextBody

string

فقط خروجی. عکس آنی از متن اصلی پیام در زمان نقل‌قول یا بازارسال. قالب‌بندی‌شده بااستفاده از Markdown برای FORWARD، و نوشتار ساده برای REPLY.
sender

string

فقط خروجی. نام نمایشی نویسنده پیام اصلی.
attachments[]

object (ChatAttachmentMetadata)

فقط خروجی. پیوست‌هایی که بخشی از پیام اصلی بوده‌اند. فقط برای نوع مظنه FORWARD درج می‌شود.
forwardedMetadata

object (ForwardedMetadata)

فقط خروجی. فراداده درباره مکالمه منبع پیام بازارسال‌شده. فقط برای نوع مظنه FORWARD درج می‌شود.

ForwardedMetadata

نمایش JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
فیلدها
conversationId

string

فقط خروجی. نام منبع مکالمه منبع. قالب: spaces/{space}
conversationDisplayName

string

فقط خروجی. نام نمایشی مکالمه منبع در زمان بازارسال پیام. برای فضاهای نام‌گذاری‌شده، این نام فضا است. برای پیام‌های مستقیم یک‌به‌یک، این نام شرکت‌کننده دیگر است. برای گپ‌های گروهی بی‌نام، این نام براساس نام اعضا تولید می‌شود.

UserType

نوع کاربر Google Chat.

شمارشی‌ها
USER_TYPE_UNSPECIFIED نامشخص.
HUMAN کاربر انسانی.
APP کاربر برنامه.

منبع

منبع پیوست.

شمارشی‌ها
SOURCE_UNSPECIFIED رزروشده.
DRIVE_FILE فایل از نوع Google Drive باشد.
UPLOADED_CONTENT فایل در Chat بارگذاری می‌شود.

QuoteType

نوع نقل‌قول که نشان می‌دهد پیام پاسخ نقل‌شده است یا پیام بازارسال‌شده.

شمارشی‌ها
QUOTE_TYPE_UNSPECIFIED رزروشده. نوع نقل‌قول تعریف‌نشده.
REPLY پیام پاسخ نقل‌قولی به پیام اصلی در همان رشته است.
FORWARD پیام از پیام اصلی در مکالمه‌ای متفاوت یا از رشته‌ای متفاوت در همان مکالمه بازارسال شده است.

حاشیه‌نویسی‌های ابزار

حاشیه‌نویسی‌های ابزار به کارخواهان MCP ارسال می‌شود تا خطر اصلی ابزار موردنظر را شرح دهد. اکثر کارخواه‌ها این راهنمایی‌ها را غیرقابل‌اعتماد تلقی می‌کنند، اما می‌توان از آن‌ها برای تصمیم‌گیری درباره زمان ارسال پیام‌واره تأیید به کاربر استفاده کرد.

همراه با رشته عنوان، نکات بولی زیر به‌صورت زیر تعریف می‌شوند:

  • ‫readOnlyHint: اگر درست باشد، ابزار محیط خود را تغییر نمی‌دهد. پیش‌فرض: false.
  • ‫destructiveHint: اگر درست باشد، ابزار می‌تواند کنش‌های مخرب انجام دهد. اگر نادرست باشد، ابزار فقط می‌تواند کنش‌های افزایشی انجام دهد. پیش‌فرض: true.
  • idempotentHint: اگر درست باشد، فراخوانی مکرر ابزار با همان آرگومان‌ها تأثیر اضافی بر محیط آن نخواهد داشت. پیش‌فرض: false.
  • ‫openWorldHint: اگر درست باشد، ابزار می‌تواند با «دنیای باز» نهادهای خارجی تعامل داشته باشد. اگر نادرست باشد، ابزار فقط می‌تواند با نهادهای داخلی تعامل داشته باشد. برای مثال، ابزار جستجوی وب دنیای باز است، درحالی‌که ابزار حافظه دنیای باز نیست.

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

دامنه‌های مجوز

به یکی از دامنه‌های OAuth زیر نیاز دارد:

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