MCP Tools Reference: chatmcp.googleapis.com

ابزار: search_conversations

مکالمه‌های Google Chat را برای پیدا کردن شناسه‌های مکالمه جستجو می‌کند. فضاهای نام‌دار براساس نام نمایشی (space_name_query) پیدا می‌شوند. پیام‌های مستقیم (DM) و گپ‌های گروهی فقط براساس نشانی ایمیل شرکت‌کنندگان (participants) پیدا می‌شوند.

این ابزار فراداده مکالمه را جستجو می‌کند، نه محتوای پیام را. برای جستجو در سابقه پیام یا پیدا کردن پیام‌ها براساس کلیدواژه/فرستنده/مُهر زمان، از search_messages استفاده کنید.

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

اگر فقط space_name_query ارائه شده باشد، این ابزار فقط فضاهای نام‌گذاری‌شده‌ای را جستجو می‌کند که پُرسمان در آن‌ها زیررشته‌ای از نام نمایشی فضا باشد و به حروف بزرگ و کوچک حساس نباشد. پیام‌های مستقیم و گپ‌های گروهی هرگز برگردانده نمی‌شوند، بنابراین نام شخص را به‌عنوان space_name_query برای پیدا کردن پیام مستقیم با او ارسال نکنید؛ نشانی ایمیل او را جستجو کنید و آن را در participants ارسال کنید.

اگر هم participants و هم space_name_query ارائه شده باشد، این ابزار گپ‌های گروهی یا پیام‌های مستقیم را براساس شرکت‌کنندگان پیدا می‌کند و سپس آن‌ها را براساس نام نمایشی فیلتر می‌کند.

اگر هیچ‌کدام از participants یا space_name_query ارائه نشده باشد، این ابزار فضاهای نام‌گذاری‌شده‌ای را که کاربر تماس‌گیرنده عضو آن‌ها است فهرست می‌کند (پیام‌های مستقیم و گپ‌های گروهی شامل نمی‌شوند).

این ابزار فقط مکالمه‌هایی را فهرست می‌کند که کاربر تماس‌گیرنده عضو آن‌ها است.

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

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

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

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

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

SearchConversationsRequest

نمایش JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
فیلدها
spaceNameQuery

string

اختیاری. نوشتاری که باید در نام‌های نمایشی مکالمه جستجو شود (مطابقت رشته فرعی غیرحساس به حروف بزرگ و کوچک).

اگر participants خالی باشد، فقط فضاهای نام‌گذاری‌شده جستجو می‌شوند و پیام‌های مستقیم (DM) و گپ‌های گروهی هرگز برگردانده نمی‌شوند، بنابراین جستجوی نام فرد در اینجا منجر به پیدا کردن پیام مستقیم با او نخواهد شد. برای پیدا کردن پیام مستقیم یا گپ گروهی، نشانی ایمیل اعضا را در participants ارائه دهید. اگر participants تنظیم شده باشد، این پُرسمان پیام‌های مستقیم یا گپ‌های گروهی مطابقت‌داده‌شده را براساس نام نمایشی بیشتر فیلتر می‌کند.
pageSize

integer

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

string

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

string

اختیاری. فهرست نشانی‌های ایمیل شرکت‌کنندگان برای فیلتر کردن مکالمه‌ها، به‌استثنای تماس‌گیرنده. از این برای پیدا کردن پیام‌های مستقیم (DM) و گپ‌های گروهی استفاده کنید: یک شرکت‌کننده پیام مستقیم دونفره با آن شخص را برمی‌گرداند و چند شرکت‌کننده گپ‌های گروهی حاوی همه آن‌ها را برمی‌گرداند. وقتی این فیلد تنظیم شده باشد، فضاهای نام‌گذاری‌شده برگردانده نمی‌شوند.

طرح خروجی

پاسخ حاوی فهرست مکالمه‌های منطبق.

SearchConversationsResponse

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

object (Conversation)

فهرست اشیای مکالمه که با معیارهای جستجو مطابقت دارد. هر مکالمه شامل conversation_id (قالب: spaces/{space})، display_name، conversation_type، و last_active_timestamp است.
nextPageToken

string

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

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

مکالمه

نمایش JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
فیلدها
conversationId

string

شناسه مکالمه (برای نمونه، «spaces/AAAAAAAAA»).
displayName

string

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

enum (ConversationType)

نوع مکالمه (DIRECT_MESSAGE،‏ GROUP_CHAT، یا NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

آخرین زمان فعال مکالمه در قالب ISO 8601.

از RFC 3339 استفاده می‌کند، که در آن خروجی تولیدشده همیشه Z-نرمال‌سازی می‌شود و از ۰، ۳، ۶، یا ۹ رقم اعشاری استفاده می‌کند. انحراف‌های غیراز «Z» نیز پذیرفته می‌شود. مثال‌ها: "2014-10-02T15:01:23Z"، "2014-10-02T15:01:23.045123456Z"، یا "2014-10-02T15:01:23+05:30".

مُهر زمان

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

string (int64 format)

نشان‌دهنده ثانیه‌های ساعت هماهنگ جهانی از تاریخ یونیکس 1970-01-01T00:00:00Z است. باید بین ‎-۶۲۱۳۵۵۹۶۸۰۰ و ۲۵۳۴۰۲۳۰۰۷۹۹ باشد (که معادل ۰۰۰۱-۰۱-۰۱T00:00:00Z تا ۹۹۹۹-۱۲-۳۱T23:59:59Z است).
nanos

integer

کسرهای غیرمنفی ثانیه با وضوح نانوثانیه. این فیلد بخش نانوثانیه مدت زمان است، نه جایگزینی برای ثانیه. مقادیر منفی ثانیه با کسرها باید همچنان مقادیر نانو غیرمنفی داشته باشند که در زمان به جلو شمارش می‌شوند. باید بین ۰ و ۹۹۹٬۹۹۹٬۹۹۹ باشد.

ConversationType

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

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

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

حاشیه‌نویسی‌های ابزار به کارخواهان 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.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly