MCP Tools Reference: chatmcp.googleapis.com

ابزار: list_messages

پیام‌ها را از مکالمه Google Chat مشخص‌شده (فضا، پیام مستقیم (DM)، یا پیام مستقیم گروهی) در قالب Markdown بازیابی می‌کند. امکان فیلتر کردن براساس رشته، محدوده زمانی، و تعداد پیام‌ها را فراهم می‌کند. علاوه‌براین، صفحه بعدی پیام‌ها را می‌توان برای ارائه بافت بیشتر بازیابی کرد. پیام‌های خصوصی (پیام‌هایی که فقط برای یک کاربر قابل‌مشاهده است) فیلتر می‌شوند.

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

درخواست 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": "list_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

ListChatMessagesRequest

نمایش JSON 
{
  "conversationId": string,
  "threadId": string,
  "pageSize": integer,
  "pageToken": string,
  "startTime": string,
  "endTime": string
}
فیلدها
conversationId

string

الزامی. شناسه مکالمه. مکالمه می‌تواند فضا، پیام مستقیم (DM)، یا پیام مستقیم/ گپ گروهی باشد. قالب: spaces/{space}
threadId

string

اختیاری. شناسه رشته‌ای خاص در مکالمه. اگر ارائه شود، فقط پیام‌های این رشته برگردانده می‌شود. اگر حذف شود، پیام‌های همه رشته‌های مکالمه درنظر گرفته می‌شود. قالب: spaces/{space}/threads/{thread}
pageSize

integer

اختیاری. حداکثر تعداد پیام‌ها برای برگرداندن. سرویس ممکن است کمتر از این مقدار را برگرداند. اگر مشخص نشده باشد، به‌طور پیش‌فرض ۲۰ است. حداکثر مقدار ۵۰ است. اگر از مقداری بیشتر از ۵۰ استفاده کنید، به‌طور خودکار به ۵۰ تغییر می‌کند.
pageToken

string

اختیاری. یک توکن صفحه، که از یک فراخوانی list_messages قبلی دریافت شده است. برای بازیابی صفحه بعدی، این را ارائه دهید.
startTime

string

اختیاری. مُهر زمان ISO 8601 برای فیلتر کردن پیام‌ها. فقط پیام‌هایی که بعداز این زمان ایجاد شده‌اند برگردانده خواهند شد.
endTime

string

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

طرح‌واره برونداد

پاسخ حاوی فهرست پیام‌های مکالمه درخواست‌شده.

ListChatMessagesResponse

نمایش JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
فیلدها
messages[]

object (ChatMessage)

فهرست پیام‌های بازیابی‌شده، به‌ترتیب زمانی معکوس (جدیدترین در ابتدا).
nextPageToken

string

یک توکن که می‌تواند به‌عنوان page_token در ListMessagesRequest بعدی ارسال شود تا صفحه بعدی پیام‌ها را بازیابی کند. اگر این فیلد خالی باشد، صفحه دیگری وجود ندارد.

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.readonly