MCP Tools Reference: chatmcp.googleapis.com

ابزار: search_conversations

مکالمات گوگل چت (فضاهای نامگذاری شده، پیام‌های مستقیم (DM) یا چت‌های گروهی) را بر اساس نام نمایشی یا شرکت‌کنندگان جستجو می‌کند تا شناسه‌های مکالمه را پیدا کند.

این ابزار فراداده‌های مکالمه را جستجو می‌کند، نه محتوای پیام را. برای جستجو در تاریخچه پیام یا یافتن پیام‌ها بر اساس کلمه کلیدی/فرستنده/زمان، از search_messages یا participants برای یافتن شناسه‌های مکالمه استفاده کنید.

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

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

اگر فقط یک query ارائه شده باشد، این ابزار مکالماتی را جستجو می‌کند که پرس‌وجو در آنها یک زیررشته‌ی غیرحساس به حروف بزرگ و کوچک از نام نمایشی مکالمه باشد.

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

اگر نه participants ارائه شود و نه query ، این ابزار تمام مکالماتی را که کاربر تماس‌گیرنده عضوی از آن است، فهرست می‌کند.

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

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

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

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

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

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

جستجوگفتگوهادرخواست

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

string

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

pageSize

integer

اختیاری. حداکثر تعداد فاصله برای برگرداندن. سرویس ممکن است کمتر از این مقدار را برگرداند. اگر مشخص نشود، حداکثر 20 فاصله برگردانده می‌شود. حداکثر مقدار 1000 است؛ مقادیر بالاتر از 1000 به 1000 محدود می‌شوند.

pageToken

string

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

participants[]

string

اختیاری. فهرست آدرس‌های ایمیل شرکت‌کنندگان برای فیلتر کردن مکالمات، به جز تماس‌گیرنده.

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

پاسخی که شامل فهرستی از مکالمات منطبق است.

جستجوگفتگوهاپاسخ

نمایش 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

شناسه‌ی مکالمه (مثلاً «فاصله‌ها/AAAAAAAAA»).

displayName

string

نام نمایشی مکالمه.

conversationType

enum ( ConversationType )

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

lastActiveTimestamp

string ( Timestamp format)

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

از RFC 3339 استفاده می‌کند، که در آن خروجی تولید شده همیشه به صورت Z-normalized خواهد بود و از ارقام کسری ۰، ۳، ۶ یا ۹ استفاده می‌کند. آفست‌های غیر از "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)

ثانیه‌های زمان UTC را از زمان یونیکس ۱۹۷۰-۰۱-۰۱T۰۰:۰۰:۰۰Z نشان می‌دهد. باید بین -۶۲۱۳۵۵۹۶۸۰۰ و ۲۵۳۴۰۲۳۰۰۷۹۹ باشد (که معادل ۰۰۰۱-۰۱-۰۱T۰۰:۰۰:۰۰Z تا ۹۹۹۹-۱۲-۳۱T۲۳:۵۹:۵۹Z است).

nanos

integer

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

نوع مکالمه

نوع گفتگو را مشخص می‌کند.

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

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

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

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

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

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

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

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

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly