MCP Tools Reference: chatmcp.googleapis.com

ابزار: search_messages

پیام‌های Google Chat را بااستفاده از کلیدواژه‌ها و فیلترها جستجو می‌کند و آن‌ها را در قالب Markdown برمی‌گرداند. در همه فضاهایی که کاربر به آن‌ها دسترسی دارد کار می‌کند، یا می‌تواند به مکالمه خاصی محدود شود.

هنگام تصمیم‌گیری برای استفاده از search_messages درمقابل سایر ابزارهای جستجو یا خواندن، این راهنمایی را دنبال کنید:

  • وقتی به‌دنبال محتوای پیام، کلیدواژه، نام‌بردن، پیوند، فرستنده، یا پیام خوانده‌نشده خاصی هستید، از search_messages استفاده کنید، به‌ویژه زمانی که این موارد در چند فضا قرار دارند یا شناسه مکالمه مشخصی ندارند.
  • وقتی شناسه فضا یا رشته خاصی را می‌دانید و می‌خواهید پیام‌ها را به‌ترتیب زمانی بخوانید، از list_messages استفاده کنید.
  • از search_conversations برای پیدا کردن فراداده فضا مانند شناسه‌های مکالمه براساس نام نمایشی فضا یا شرکت‌کنندگان استفاده کنید (این روش فقط فراداده را جستجو می‌کند، نه محتوای پیام).

اگر searchParameters بدون فیلترهای خاص ارائه شود، پیام‌های اخیر در مکالمه‌های دردسترس کاربر برگردانده می‌شود.

نمونه کد زیر نحوه استفاده از curl برای فراخوانی ابزار MCP search_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": "search_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

SearchMessagesRequest

نمایش JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
فیلدها
searchParameters

object (SearchParameters)

الزامی. پارامترهای جستجو برای استفاده در جستجو.
pageSize

integer

اختیاری. حداکثر تعداد نتایج برای برگرداندن (حداکثر تا ۱۰۰). اگر مشخص نشده باشد، حداکثر ۲۵ مورد برگردانده می‌شود.
pageToken

string

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

SearchParameters

نمایش JSON 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
فیلدها
keywords[]

string

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

string

اختیاری. جستجو را به شناسه مکالمه خاصی محدود می‌کند، همان‌طور که از ابزار search_conversations برگردانده شده است. قالب: spaces/{ID}.
sender

string

اختیاری. فیلتر کردن پیام‌های کاربر خاص. می‌توان از ایمیل یا نام منبع فرستنده استفاده کرد. نام‌های منبع کاربر به‌صورت users/{ID} قالب‌بندی می‌شوند که در آن {ID} می‌تواند شناسه فرد یا نشانی ایمیل او باشد.
isUnread

boolean

اختیاری. فیلتر کردن پیام‌هایی که کاربر تماس‌گیرنده نخوانده است.
hasLink

boolean

اختیاری. فیلتر کردن پیام‌هایی که حداقل یک نشانی وب دارند.
startTime

string

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

string

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

boolean

اختیاری. فیلتر کردن پیام‌هایی که صریحاً از کاربر تماس‌گیرنده نام می‌برند.
conversationIncludesUser

string

اختیاری. پیام‌های موجود در پیام‌های مستقیم و گپ‌های گروهی را که حاوی شناسه یا ایمیل کاربر خاصی هستند فیلتر کنید.
spaceDisplayNames[]

string

اختیاری. براساس فهرستی از نام‌های فضا فیلتر کنید؛ نام‌های نمایشی فضا تاحدودی مطابقت دارند. توجه: فقط ۵ مورد منطبق برتر برگردانده می‌شود.
conversationTypes[]

enum (ConversationType)

اختیاری. براساس نوع مکالمه فیلتر کنید.
hasAttachment

boolean

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

ConversationType

نوع مکالمه را تعریف می‌کند.

شمارشی‌ها
CONVERSATION_TYPE_UNSPECIFIED نامشخص.
NAMED_SPACE فضای نام‌گذاری‌شده.
GROUP_CHAT گپ گروهی بین ۳ نفر یا بیشتر.
DIRECT_MESSAGE پیام مستقیم بین دو انسان، یا یک انسان و برنامه Chat.

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

پاسخ به جستجوی پیام‌های Google Chat. اگر next_page_token پر شده باشد، می‌توان SearchMessages را دوباره با آن کد برای بازیابی صفحه بعدی نتایج فراخوانی کرد.

SearchMessagesResponse

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

object (ChatMessage)

فهرست اشیای پیام که با معیارهای جستجو مطابقت دارند.
nextPageToken

string

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

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.readonly
  • https://www.googleapis.com/auth/chat.spaces.readonly
  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.users.readstate.readonly