MCP Tools Reference: chatmcp.googleapis.com

Công cụ: list_messages

Truy xuất tin nhắn từ một cuộc trò chuyện cụ thể trên Google Chat (Không gian, tin nhắn trực tiếp (DM) hoặc tin nhắn trực tiếp theo nhóm) ở định dạng Markdown. Cho phép lọc theo chuỗi thư, phạm vi thời gian và số lượng thư. Ngoài ra, bạn có thể truy xuất trang tin nhắn tiếp theo để có thêm bối cảnh. Tin nhắn riêng tư (tin nhắn chỉ hiển thị với một người dùng) sẽ bị lọc ra.

Mã mẫu sau đây cho biết cách sử dụng curl để gọi công cụ MCP list_messages.

Yêu cầu 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
}'

Lược đồ đầu vào

ListChatMessagesRequest

Biểu diễn dưới dạng JSON 
{
  "conversationId": string,
  "threadId": string,
  "pageSize": integer,
  "pageToken": string,
  "startTime": string,
  "endTime": string
}
Trường
conversationId

string

Bắt buộc. Mã nhận dạng cuộc trò chuyện. Cuộc trò chuyện có thể là một không gian, tin nhắn trực tiếp (DM) hoặc tin nhắn trực tiếp/cuộc trò chuyện nhóm. Định dạng: spaces/{space}
threadId

string

Không bắt buộc. Mã nhận dạng của một chuỗi tin nhắn cụ thể trong cuộc trò chuyện. Nếu được cung cấp, chỉ những tin nhắn trong chuỗi này mới được trả về. Nếu bạn bỏ qua, hệ thống sẽ xem xét tin nhắn trong tất cả các chuỗi của cuộc trò chuyện. Định dạng: spaces/{space}/threads/{thread}
pageSize

integer

Không bắt buộc. Số lượng tin nhắn tối đa cần trả về. Dịch vụ có thể trả về ít hơn giá trị này. Nếu không được chỉ định, giá trị mặc định là 20. Giá trị tối đa là 50. Nếu bạn sử dụng giá trị lớn hơn 50, thì giá trị đó sẽ tự động được thay đổi thành 50.
pageToken

string

Không bắt buộc. Mã thông báo trang, nhận được từ lệnh gọi list_messages trước đó. Cung cấp mã này để truy xuất trang tiếp theo.
startTime

string

Không bắt buộc. Dấu thời gian ISO 8601 để lọc tin nhắn. Chỉ những tin nhắn được tạo sau thời điểm này mới được trả về.
endTime

string

Không bắt buộc. Dấu thời gian ISO 8601 để lọc tin nhắn. Chỉ những tin nhắn được tạo trước thời điểm này mới được trả về.

Giản đồ đầu ra

Phản hồi chứa danh sách tin nhắn trong cuộc trò chuyện được yêu cầu.

ListChatMessagesResponse

Biểu diễn dưới dạng JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Trường
messages[]

object (ChatMessage)

Danh sách tin nhắn được truy xuất, theo thứ tự thời gian đảo ngược (mới nhất trước).
nextPageToken

string

Mã thông báo, có thể được gửi dưới dạng page_token trong ListMessagesRequest tiếp theo để truy xuất trang thư tiếp theo. Nếu trường này trống, thì tức là không còn trang nào nữa.

ChatMessage

Biểu diễn dưới dạng JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Trường
messageId

string

Tên tài nguyên của thông báo. Định dạng: spaces/{space}/messages/{message}
threadId

string

Chuỗi tin nhắn chứa tin nhắn này. Trường này sẽ trống nếu tin nhắn không thuộc chuỗi tin nhắn. Định dạng: spaces/{space}/threads/{thread}
plaintextBody

string

Nội dung văn bản của thông báo sử dụng định dạng Markdown.
sender

object (User)

Người gửi tin nhắn.
createTime

string

Chỉ có đầu ra. Dấu thời gian khi thông báo được tạo. Định dạng: Dấu thời gian ISO 8601.
threadedReply

boolean

Liệu tin nhắn có phải là tin nhắn trả lời trong chuỗi hay không.
attachments[]

object (ChatAttachmentMetadata)

Tệp đính kèm có trong thư.
reactionSummaries[]

object (ReactionSummary)

Bản tóm tắt về lượt thể hiện cảm xúc bằng emoji có trong tin nhắn.
quotedMessageMetadata

object (QuotedMessageMetadata)

Chỉ có đầu ra. Thông tin về tin nhắn gốc được trích dẫn hoặc chuyển tiếp trong tin nhắn này. Lưu ý: Trường này đang được phát triển và có thể chưa có trong một số môi trường.

Người dùng

Biểu diễn dưới dạng JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Trường
userId

string

Tên tài nguyên của người dùng Chat. Định dạng: users/{user}.
displayName

string

Tên hiển thị của người dùng Chat.
email

string

Địa chỉ email của người dùng. Trường này chỉ được điền sẵn khi loại người dùng là HUMAN.
userType

enum (UserType)

Loại người dùng.

ChatAttachmentMetadata

Biểu diễn dưới dạng JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Trường
attachmentId

string

Tên tài nguyên của tệp đính kèm. Định dạng: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Tên của tệp đính kèm.
mimeType

string

Loại nội dung (loại MIME).
source

enum (Source)

Nguồn của tệp đính kèm.
driveFileId

string

Chỉ có đầu ra. Mã nhận dạng của tệp trên Google Drive. Chỉ được điền sẵn khi nguồn là DRIVE_FILE. Sử dụng với MCP của Google Drive.

ReactionSummary

Biểu diễn dưới dạng JSON 
{
  "emoji": string,
  "count": integer
}
Trường
emoji

string

Chuỗi unicode của biểu tượng cảm xúc hoặc tên biểu tượng cảm xúc tuỳ chỉnh.
count

integer

Tổng số lượt bày tỏ cảm xúc bằng biểu tượng cảm xúc liên quan.

QuotedMessageMetadata

Biểu diễn dưới dạng JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Trường
messageId

string

Chỉ có đầu ra. Tên tài nguyên của tin nhắn gốc được trích dẫn hoặc chuyển tiếp. Định dạng: spaces/{space}/messages/{message}
lastUpdateTime

string

Chỉ có đầu ra. Dấu thời gian khi tin nhắn gốc được tạo hoặc cập nhật lần gần đây nhất trước khi được trích dẫn hoặc chuyển tiếp. Định dạng: Dấu thời gian ISO 8601.
quoteType

enum (QuoteType)

Chỉ có đầu ra. Loại báo giá.
plaintextBody

string

Chỉ có đầu ra. Ảnh chụp nhanh nội dung văn bản của thư gốc tại thời điểm trích dẫn hoặc chuyển tiếp. Được định dạng bằng Markdown cho FORWARD và văn bản thuần túy cho REPLY.
sender

string

Chỉ có đầu ra. Tên hiển thị của tác giả tin nhắn gốc.
attachments[]

object (ChatAttachmentMetadata)

Chỉ có đầu ra. Tệp đính kèm trong thư gốc. Chỉ được điền sẵn cho loại báo giá FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Chỉ có đầu ra. Siêu dữ liệu về cuộc trò chuyện nguồn của tin nhắn được chuyển tiếp. Chỉ được điền sẵn cho loại báo giá FORWARD.

ForwardedMetadata

Biểu diễn dưới dạng JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Trường
conversationId

string

Chỉ có đầu ra. Tên tài nguyên của cuộc trò chuyện nguồn. Định dạng: spaces/{space}
conversationDisplayName

string

Chỉ có đầu ra. Tên hiển thị của cuộc trò chuyện gốc tại thời điểm tin nhắn được chuyển tiếp. Đối với không gian có tên, đây là tên không gian. Đối với tin nhắn trực tiếp 1:1, đây là tên của người tham gia còn lại. Đối với cuộc trò chuyện nhóm chưa đặt tên, đây là tên được tạo dựa trên tên của các thành viên.

UserType

Loại người dùng Google Chat.

Enum
USER_TYPE_UNSPECIFIED Không xác định.
HUMAN Người dùng là con người.
APP Người dùng ứng dụng.

Nguồn

Nguồn của tệp đính kèm.

Enum
SOURCE_UNSPECIFIED Đã đặt trước.
DRIVE_FILE Tệp này là tệp trên Google Drive.
UPLOADED_CONTENT Tệp được tải lên Chat.

QuoteType

Loại trích dẫn cho biết tin nhắn là tin nhắn trả lời khi trích dẫn hay tin nhắn được chuyển tiếp.

Enum
QUOTE_TYPE_UNSPECIFIED Đã đặt trước. Loại dấu ngoặc kép không xác định.
REPLY Tin nhắn này là tin nhắn trả lời trích dẫn cho một tin nhắn gốc trong cùng một chuỗi.
FORWARD Tin nhắn được chuyển tiếp từ một tin nhắn gốc trong một cuộc trò chuyện khác hoặc từ một chuỗi tin nhắn khác trong cùng một cuộc trò chuyện.

Chú thích về công cụ

Chú thích về công cụ được gửi đến ứng dụng MCP để mô tả rủi ro cơ bản của một công cụ nhất định. Hầu hết ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng có thể dùng chúng để quyết định thời điểm gửi lời nhắc xác nhận cho người dùng.

Cùng với chuỗi tiêu đề, các gợi ý boolean sau đây được xác định như sau:

  • readOnlyHint: Nếu đúng, công cụ sẽ không sửa đổi môi trường của nó. Mặc định: false.
  • destructiveHint: Nếu đúng, thì công cụ có thể thực hiện các hành động có tính huỷ diệt. Nếu là false, thì công cụ chỉ có thể thực hiện các hành động bổ sung. Mặc định: true.
  • idempotentHint: Nếu đúng, thì việc gọi công cụ nhiều lần với cùng một đối số sẽ không có thêm hiệu ứng nào đối với môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, thì công cụ có thể tương tác với "thế giới mở" của các thực thể bên ngoài. Nếu là false, thì công cụ chỉ có thể tương tác với các thực thể nội bộ. Ví dụ: công cụ tìm kiếm trên web sẽ là công cụ thế giới mở, còn công cụ ghi nhớ sẽ không phải là công cụ thế giới mở.

Gợi ý về hành động huỷ diệt: ❌ | Gợi ý về hành động luỹ đẳng: ✅ | Gợi ý về hành động chỉ đọc: ✅ | Gợi ý về hành động thế giới mở: ❌

Phạm vi cấp phép

Yêu cầu một trong các phạm vi OAuth sau:

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