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

اختيارية: الحد الأقصى لعدد النتائج التي سيتم عرضها (بحد أقصى 100 نتيجة). إذا لم يتم تحديدها، سيتم عرض 25 نتيجة كحد أقصى.
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

اختيارية: فلترة الرسائل التي تحتوي على عنوان URL واحد على الأقل
startTime

string

اختيارية: فلترة الرسائل التي تم إنشاؤها بعد هذا الوقت التنسيق: طابع زمني بتنسيق ISO 8601.
endTime

string

اختيارية: فلترة الرسائل التي تم إنشاؤها قبل هذا الوقت التنسيق: طابع زمني بتنسيق ISO 8601.
mentionsMe

boolean

اختيارية: للفلترة بحثًا عن الرسائل التي تشير صراحةً إلى المستخدم المتصل
conversationIncludesUser

string

اختيارية: يمكنك فلترة الرسائل في الرسائل المباشرة والمحادثات الجماعية التي تتضمّن عنوان البريد الإلكتروني أو رقم التعريف الخاص بمستخدم معيّن.
spaceDisplayNames[]

string

اختيارية: يمكنك الفلترة حسب قائمة بأسماء المساحات، وتتم مطابقة الأسماء المعروضة للمساحات جزئيًا. ملاحظة: يتم عرض أفضل 5 نتائج مطابقة فقط.
conversationTypes[]

enum (ConversationType)

اختيارية: الفلترة حسب نوع المحادثة
hasAttachment

boolean

اختيارية: فلترة الرسائل التي تحتوي على مرفق واحد على الأقل ملاحظة: هذا الحقل قيد التطوير وقد لا يكون متاحًا في جميع البيئات بعد.

ConversationType

تحدّد نوع المحادثة.

عمليات التعداد
CONVERSATION_TYPE_UNSPECIFIED غير محدد
NAMED_SPACE مساحة مُسمّاة
GROUP_CHAT محادثة جماعية بين 3 أشخاص أو أكثر
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. يمكنك استخدامها مع بروتوكول سياق النموذج (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.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