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)

אופציונלי. כרטיסים שמצורפים להודעה. הגודל המקסימלי הוא 32KB לכל כרטיס. כל כרטיס מיוצג כמבנה JSON לפי הפורמט של כרטיס Google Chat (כרטיס Google Workspace UIKit / כרטיסים v2). כדי לצרף כרטיסים להודעה, האפליקציה ל-Chat צריכה להיות חלק מהמרחב.

זיהוי הכרטיס:

  • שדה המחרוזת name ברמה העליונה בכל כרטיס משמש כמזהה שלו.
  • אם להודעה מצורפים כמה כרטיסים, לכל כרטיס חייב להיות name ייחודי ולא ריק.
inlineCitations[]

object (Citation)

אופציונלי. הפניות למקורות בגוף הטקסט בתוך message_text באמצעות תגי chat-citation. אפשר להוסיף עד 20 ציטוטים בגוף הטקסט בכל הודעה. המערכת מתעלמת מציטוטים בגוף הטקסט שלא מפנים למקור (ציטוטים שאין להם תג chat-citation תואם ב-message_text), והם לא גורמים לשגיאת אימות.
footerCitedSources[]

object (CitedSource)

אופציונלי. מקורות מצוטטים ברמה העליונה שמוצגים ככרטיסי הפניה בחלק התחתון (כותרת תחתונה) של ההודעה. אפשר להוסיף עד 50 מקורות מצוטטים בסך הכול בכל הציטוטים בגוף הטקסט ורשימת המקורות בכותרת התחתונה בהודעה.

Struct

ייצוג ב-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

חובה. כותרת המקור בטקסט פשוט (לדוגמה, "תוכנית 'תצוגה מקדימה למפתחים' של Google Workspace"). אי אפשר להשתמש בפורמט 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 הוא sentinel, שמשתמש ב-enum עם ערך אחד בלבד כדי לייצג את הערך null לאיחוד מסוג Value.

שדה מסוג NullValue עם ערך שונה מ-0 נחשב לא תקין. רוב ה-serializers של ProtoJSON יפיקו Value עם null_value שמוגדר כ-null של JSON, בלי קשר לערך של המספר השלם, ולכן יחזרו לערך 0.

טיפוסים בני מנייה (enum)
NULL_VALUE ערך Null.

סכימת הפלט

תגובה לשליחת הודעה לשיחה ב-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

מחרוזת ה-Unicode של האמוג'י או השם של האמוג'י בהתאמה אישית.
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.

טיפוסים בני מנייה (enum)
USER_TYPE_UNSPECIFIED לא צוין.
HUMAN משתמש אנושי.
APP משתמש באפליקציה.

מקור

המקור של הקובץ המצורף.

טיפוסים בני מנייה (enum)
SOURCE_UNSPECIFIED שמורות.
DRIVE_FILE הקובץ הוא קובץ ב-Google Drive.
UPLOADED_CONTENT הקובץ יועלה ל-Chat.

QuoteType

סוג הציטוט, שמציין אם ההודעה היא תשובה עם ציטוט או הודעה שהועברה.

טיפוסים בני מנייה (enum)
QUOTE_TYPE_UNSPECIFIED שמורות. סוג הציטוט לא מוגדר.
REPLY ההודעה היא תשובה עם ציטוט להודעה מקורית באותו שרשור.
FORWARD ההודעה הועברה מהודעה מקורית בשיחה אחרת, או משרשור אחר באותה שיחה.

הערות לגבי הכלים

הערות הכלים נשלחות ללקוחות MCP כדי לתאר את הסיכון הבסיסי של כלי מסוים. רוב הלקוחות מתייחסים לרמזים האלה כלא מהימנים, אבל אפשר להשתמש בהם כדי להחליט מתי לשלוח למשתמש בקשה לאישור.

בנוסף למחרוזת הכותרת, הרמזים הבוליאניים הבאים מוגדרים כך:

  • ‫readOnlyHint: אם הערך הוא True, הכלי לא משנה את הסביבה שלו. ברירת המחדל: false.
  • ‫destructiveHint: אם הערך הוא True, הכלי יכול לבצע פעולות הרסניות. אם הערך הוא False, הכלי יכול לבצע רק פעולות הוספה. ברירת המחדל: true.
  • ‫idempotentHint: אם הערך הוא True, קריאה חוזרת לכלי עם אותם ארגומנטים לא תשפיע על הסביבה שלו. ברירת המחדל: false.
  • ‫openWorldHint: אם הערך הוא True, הכלי יכול לקיים אינטראקציה עם "עולם פתוח" של ישויות חיצוניות. אם הערך הוא false, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

רמז לפעולה הרסנית: ❌ | רמז לפעולה אידמפוטנטית: ❌ | רמז לפעולה לקריאה בלבד: ❌ | רמז לפעולה בעולם פתוח: ✅

היקפי הרשאות

נדרש אחד מהיקפי ההרשאות הבאים של OAuth:

  • https://www.googleapis.com/auth/chat.messages
  • https://www.googleapis.com/auth/chat.messages.create