MCP Tools Reference: chatmcp.googleapis.com

الأداة: list_messages

تسترد هذه الأداة الرسائل من محادثة محدّدة في Google Chat (مساحة أو رسالة مباشرة أو رسالة مباشرة جماعية) بتنسيق 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

الحقل مطلوب. رقم تعريف المحادثة يمكن أن تكون المحادثة مساحة أو رسالة مباشرة أو رسالة مباشرة جماعية أو محادثة جماعية. التنسيق: spaces/{space}
threadId

string

اختيارية: رقم تعريف سلسلة محادثات معيّنة ضمن المحادثة في حال توفيره، سيتم عرض الرسائل من هذه السلسلة فقط. في حال حذف هذه المَعلمة، يتم أخذ الرسائل من جميع سلاسل المحادثات في الاعتبار. التنسيق: spaces/{space}/threads/{thread}
pageSize

integer

اختيارية: الحد الأقصى لعدد الرسائل التي سيتم عرضها. قد تعرض الخدمة عددًا أقل من هذه القيمة. في حال عدم تحديدها، يتم ضبط القيمة التلقائية على 20. الحدّ الأقصى للقيمة هو 50. إذا استخدمت قيمة أكبر من 50، سيتم تغييرها تلقائيًا إلى 50.
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. يمكنك استخدامها مع بروتوكول سياق النموذج (MCP) في Google Drive.

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