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

מחרוזת ה-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, הכלי יכול לקיים אינטראקציה רק עם ישויות פנימיות. לדוגמה, כלי חיפוש באינטרנט הוא כלי בעולם פתוח, אבל כלי זיכרון הוא לא כלי בעולם פתוח.

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