MCP Tools Reference: chatmcp.googleapis.com

الأداة: search_messages

يبحث عن رسائل Google Chat باستخدام الكلمات الرئيسية والفلاتر ويعرضها بتنسيق Markdown. تعمل هذه الميزة في جميع المساحات التي يمكن للمستخدم الوصول إليها، أو يمكن حصر نطاقها في محادثة معيّنة.

يُرجى اتّباع هذه الإرشادات عند تحديد ما إذا كنت ستستخدم search_messages أو أدوات البحث أو القراءة الأخرى:

  • استخدِم search_messages عند البحث عن محتوى رسالة محدّد أو كلمات رئيسية أو إشارات أو روابط أو مُرسِلين أو رسائل غير مقروءة قد تكون في مساحات متعددة أو بدون معرّف محادثة معروف.
  • استخدِم list_messages عندما تعرف المعرّف المحدّد للمساحة أو سلسلة المحادثات وتريد قراءة الرسائل بالتسلسل حسب الترتيب الزمني.
  • استخدِم search_conversations للعثور على البيانات الوصفية للمساحة، مثل معرّفات المحادثات حسب الاسم المعروض للمساحة أو المشاركين (يبحث في البيانات الوصفية فقط، وليس في محتوى الرسائل).

في حال توفير searchParameters بدون فلاتر محدّدة، يتم عرض الرسائل الحديثة من المحادثات التي يمكن للمستخدم الوصول إليها.

يوضّح نموذج الرمز التالي كيفية استخدام curl لاستدعاء أداة search_messages MCP.

طلب 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)
  ]
}
الحقول
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)

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

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)
    }
  ]
}
الحقول
messageId

string

اسم مورد الرسالة التنسيق: spaces/{space}/messages/{message}
threadId

string

سلسلة المحادثات التي تنتمي إليها هذه الرسالة سيكون هذا الحقل فارغًا إذا كانت الرسالة غير مرتبطة بسلسلة محادثات. التنسيق: spaces/{space}/threads/{thread}
plaintextBody

string

نص الرسالة باستخدام تنسيق Markdown
sender

object (User)

مُرسِل الرسالة
createTime

string

النتائج فقط. الطابع الزمني لوقت إنشاء الرسالة
threadedReply

boolean

تُستخدَم لتحديد ما إذا كانت الرسالة ردًا في سلسلة محادثات.
attachments[]

object (ChatAttachmentMetadata)

المرفقات المضمَّنة في الرسالة
reactionSummaries[]

object (ReactionSummary)

ملخّص التفاعلات باستخدام رموز الإيموجي المضمّن في الرسالة

المستخدم

تمثيل 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)
}
الحقول
attachmentId

string

اسم المرفق التنسيق: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

اسم المرفق
mimeType

string

نوع المحتوى (نوع MIME)
source

enum (Source)

مصدر المرفق

ReactionSummary

تمثيل JSON 
{
  "emoji": string,
  "count": integer
}
الحقول
emoji

string

سلسلة يونيكود الإيموجي أو اسم الإيموجي المخصّص
count

integer

تمثّل هذه السمة إجمالي عدد التفاعلات باستخدام الإيموجي المرتبط.

UserType

نوع مستخدم Google Chat

عمليات التعداد
USER_TYPE_UNSPECIFIED غير محدد
HUMAN مستخدم بشري
APP مستخدم التطبيق

المصدر

مصدر المرفق

عمليات التعداد
SOURCE_UNSPECIFIED محجوز
DRIVE_FILE الملف هو ملف Google Drive.
UPLOADED_CONTENT يتم تحميل الملف إلى Chat.

التعليقات التوضيحية للأدوات

يتم إرسال تعليقات توضيحية للأدوات إلى عملاء "برنامج إدارة الأجهزة الجوّالة" لوصف المخاطر الأساسية لأداة معيّنة. تتعامل معظم البرامج مع هذه التلميحات على أنّها غير موثوق بها، ولكن يمكن استخدامها لتحديد الوقت الذي قد يتم فيه إرسال طلب تأكيد إلى المستخدم.

بالإضافة إلى سلسلة العنوان، يتم تحديد تلميحات القيم المنطقية التالية على النحو التالي:

  • ‫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