MCP Tools Reference: chatmcp.googleapis.com

الأداة: send_message

يتم إرسال رسالة محادثة Google Chat إلى محادثة بتنسيق Markdown.

تستخدم هذه الأداة معرّف محادثة ومعرّف سلسلة محادثات اختياريًا ونص رسالة كمدخلات.

يمكن العثور على معرّفات المحادثات باستخدام أداة search_conversations.

وتعرض الرسالة التي تم إنشاؤها.

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

طلب 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": "send_message",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

SendMessageRequest

تمثيل JSON 
{
  "conversationId": string,
  "threadId": string,
  "messageText": string,
  "cards": [
    {
      object
    }
  ],
  "inlineCitations": [
    {
      object (Citation)
    }
  ],
  "footerCitedSources": [
    {
      object (CitedSource)
    }
  ]
}
الحقول
conversationId

string

الحقل مطلوب. رقم تعريف المحادثة (مثلاً، 'spaces/AAAA...‎') لإرسال الرسالة إليها
threadId

string

اختيارية: معرّف سلسلة المحادثات (مثلاً، 'spaces/AAAA.../threads/BBBB...') لإرسال الرسالة إليها في حال عدم ضبط هذه السياسة، سيتم إرسال الرسالة إلى سلسلة محادثات جديدة.
messageText

string

الحقل مطلوب. المحتوى الرئيسي للرسالة يمكن إضافة التنسيق باستخدام Markdown العادي (يُرجى العِلم أنّ الجداول غير متاحة). يمكن استخدام التنسيقات التالية:

  • غامق: **text**
  • مائل: *text* أو _text_
  • نص مشطوب: ~~text~~
  • أحادي المسافة: text
  • كتلة أحادية المسافة:
```
line 1
line 2
```
  • قائمة نقطية:
* item 1
* item 2
  • قائمة مع ترتيب:
1. item 1
2. item 2
  • اقتباس موسّع: > quoted text
  • الرابط التشعّبي: [label](url)
  • الإشارة إلى مستخدم: استخدِم علامة HTML ذاتية الإغلاق chat-user مع السمتَين data-email="user@example.com" أو data-user="users/USER_ID". يُفضَّل استخدام السمة data-user مع USER_ID إذا كانت معروفة، وإلا فيجب استخدام السمة data-email مع عنوان البريد الإلكتروني للمستخدم. إذا كنت تستخدم السمة data-user، احرص على تضمين البادئة users/‎ التي تظهر في القيم الأخرى التي تعرضها الأداة. ملاحظة: يُسمح بـ 10 إشارات كحدّ أقصى في كل رسالة. يُمنع منعًا باتًا الإشارة إلى جميع المستخدمين (مثلاً، باستخدام @all أو علامة HTML مع users/all).
  • إيموجي مخصّص: استخدِم علامة HTML ذاتية الإغلاق chat-emoji مع السمتَين data-custom-emoji="customEmojis/abc" أو data-emoji-name=":xyz:".
  • الاقتباس: يجب تضمين النص المقتبس في علامة HTML‏ chat-citation مع السمة data-id التي تطابق معرّف الاقتباس. إذا كانت علامة chat-citation تحتوي على data-id لا يتطابق مع أي Citation.id، يتم تجاهل العلامة ويتم عرض النص الملتف كنص عادي. ملاحظة: يُسمح بحد أقصى 20 اقتباسًا مضمّنًا في كل رسالة.
cards[]

object (Struct format)

اختيارية: البطاقات المرفقة بالرسالة الحد الأقصى للحجم هو 32 كيلوبايت لكل بطاقة. يتم تمثيل كل بطاقة كبنية JSON باتّباع تنسيق بطاقة Google Chat (بطاقة Google Workspace UIKit / الإصدار 2 من البطاقات). لإرفاق بطاقات برسالة، يجب أن يكون تطبيق Chat عضوًا في المساحة.

تعريف البطاقة:

  • ويُعدّ حقل السلسلة name ذو المستوى الأعلى في كل بطاقة معرّفًا لها.
  • إذا تم إرفاق بطاقات متعددة برسالة، يجب أن تحدّد كل بطاقة name فريدًا وغير فارغ.
inlineCitations[]

object (Citation)

اختيارية: الاقتباسات المضمّنة المُشار إليها ضمن message_text من خلال علامات chat-citation يُسمح بـ 20 اقتباسًا مضمّنًا كحدّ أقصى لكل رسالة. يتم تجاهل الاقتباسات المضمّنة غير المُشار إليها (تلك التي لا تحتوي على علامة chat-citation مطابقة في message_text) ولا تؤدي إلى حدوث خطأ في التحقّق من الصحة.
footerCitedSources[]

object (CitedSource)

اختيارية: المصادر المقتبَسة من المستوى الأعلى التي تظهر كبطاقات مرجعية في أسفل الرسالة (التذييل) يُسمح بـ 50 مصدرًا مقتبسًا كحد أقصى في المجموع في جميع الاقتباسات المضمّنة ومصادر التذييل في الرسالة.

بنية

تمثيل JSON 
{
  "fields": {
    string: value,
    ...
  }
}
الحقول
fields

map (key: string, value: value (Value format))

خريطة غير مرتبة للقيم المكتوبة ديناميكيًا.

عنصر يحتوي على قائمة بأزواج "key": value. مثال: { "name": "wrench", "mass": "1.3kg", "count": "3" }

FieldsEntry

تمثيل JSON 
{
  "key": string,
  "value": value
}
الحقول
key

string
value

value (Value format)

القيمة

تمثيل JSON 
{

  "nullValue": null,
  "numberValue": number,
  "stringValue": string,
  "boolValue": boolean,
  "structValue": {
    object
  },
  "listValue": array
}
الحقول
حقل الربط kind نوع القيمة يمكن أن يكون التعليق kind إحدى القيم التالية فقط:
nullValue

null

يمثّل هذا الحقل null بتنسيق JSON.
numberValue

number

يمثّل رقم JSON. يجب ألا تكون القيمة NaN أو Infinity أو -Infinity، لأنّها غير متوافقة مع تنسيق JSON. لا يمكن أن يمثّل هذا أيضًا قيم Int64 كبيرة، لأنّ تنسيق JSON لا يتيحها بشكل عام في نوع الأرقام.
stringValue

string

يمثّل سلسلة JSON.
boolValue

boolean

تمثّل قيمة منطقية بتنسيق JSON (قيمة ثابتة true أو false في JSON).
structValue

object (Struct format)

يمثّل عنصر JSON.
listValue

array (ListValue format)

يمثّل مصفوفة JSON.

ListValue

تمثيل JSON 
{
  "values": [
    value
  ]
}
الحقول
values[]

value (Value format)

حقل متكرّر للقيم المكتوبة ديناميكيًا

معلومات الكتاب

تمثيل JSON 
{
  "id": string,
  "citedSources": [
    {
      object (CitedSource)
    }
  ]
}
الحقول
id

string

الحقل مطلوب. معرّف فريد يتطابق مع السمة data-id في علامة chat-citation (مثلاً، التفاف النص المقتبس باستخدام chat-citation والسمة data-id="ID") في message_text. يجب أن يتألف من أحرف ASCII أو أرقام أو شرطات سفلية أو واصلات فقط (من 1 إلى 63 حرفًا). يجب أن يكون فريدًا بين جميع الاقتباسات في الرسالة.
citedSources[]

object (CitedSource)

الحقل مطلوب. مصدر واحد أو أكثر مرفق بهذه البطاقة المنبثقة للاقتباس. يُسمح بـ 50 مصدرًا مقتبسًا كحد أقصى في المجموع في جميع الاقتباسات المضمّنة ومصادر التذييل في الرسالة.

CitedSource

تمثيل JSON 
{
  "title": string,
  "url": string,
  "snippet": string,
  "imageUrl": string,
  "footer": string
}
الحقول
title

string

الحقل مطلوب. Plaintext title of the source (e.g., "Google Workspace Developer Preview Program"). لا يمكن استخدام تنسيق Markdown في العناوين.
url

string

الحقل مطلوب. عنوان URL للمرجع المقتبس (يجب أن يكون عنوان URL صالحًا يبدأ بـ http:// ‎ أو https:// ‎، مثل "https://developers.google.com/workspace/preview").
snippet

string

اختيارية: مقتطف قصير من المصدر مباشرةً يتم عرضها في البطاقة المنبثقة أو التذييل. يُسمح بالنص العادي فقط. الحد الأقصى للطول هو 1,000 حرف.
imageUrl

string

اختيارية: عنوان URL لصورة مصغّرة لمعاينة الصورة (يجب استخدام عنوان URL يبدأ بـ https:// ‎)
footer

string

اختيارية: نص تحديد المصدر الإضافي الذي يظهر في تذييل البطاقة (مثل اسم النطاق "developers.google.com" أو اسم المؤلف/المؤسسة)

NullValue

يمثّل هذا الحقل null بتنسيق JSON.

‫NullValue هو حارس يستخدم تعدادًا بقيمة واحدة فقط لتمثيل القيمة الفارغة لاتحاد النوع Value.

يُعتبر الحقل من النوع NullValue الذي يحتوي على أي قيمة غير 0 غير صالح. ستُصدر معظم أدوات تسلسل ProtoJSON قيمة Value مع ضبط null_value على أنّه null في JSON بغض النظر عن قيمة العدد الصحيح، وبالتالي ستتحوّل إلى قيمة 0.

عمليات التعداد
NULL_VALUE قيمة فارغة

مخطط النتائج

الرد على إرسال رسالة إلى محادثة في Google Chat

SendMessageResponse

تمثيل JSON 
{
  "message": {
    object (ChatMessage)
  }
}
الحقول
message

object (ChatMessage)

الرسالة التي تم إرسالها

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.create