MCP Tools Reference: chatmcp.googleapis.com

ابزار: list_messages

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

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

درخواست کرل 
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 tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

درخواست لیستچتپیام‌ها

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

string

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

threadId

string

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

pageSize

integer

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

pageToken

string

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

startTime

string

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

endTime

string

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

طرحواره خروجی

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

پاسخ لیستچتپیام‌ها

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

object ( ChatMessage )

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

nextPageToken

string

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

چتپیام

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

string

نام منبع پیام. قالب: فاصله‌ها/{فاصله}/پیام‌ها/{پیام}

threadId

string

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

plaintextBody

string

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

sender

object ( User )

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

createTime

string

فقط خروجی. مهر زمانی که پیام ایجاد شده است.

threadedReply

boolean

اینکه آیا پیام، پاسخ یک تاپیک است یا خیر.

attachments[]

object ( ChatAttachmentMetadata )

پیوست‌های موجود در پیام.

reactionSummaries[]

object ( ReactionSummary )

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

کاربر

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

string

نام منبع یک کاربر چت. فرمت: users/{user}.

displayName

string

نام نمایشی کاربر چت.

email

string

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

userType

enum ( UserType )

نوع کاربر.

فراداده پیوست چت

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

string

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

filename

string

نام فایل پیوست.

mimeType

string

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

source

enum ( Source )

منبع پیوست.

خلاصه واکنش

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

string

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

count

integer

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

نوع کاربر

نوع کاربر گوگل چت.

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

منبع

منبع پیوست.

انوم‌ها
SOURCE_UNSPECIFIED رزرو شده.
DRIVE_FILE فایل، فایل گوگل درایو است.
UPLOADED_CONTENT فایل در چت آپلود شد.

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

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

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

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

راهنمایی مخرب: ❌ | راهنمایی بی‌اثر: ✅ | راهنمایی فقط خواندنی: ✅ | راهنمایی جهان باز: ❌

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

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

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