MCP Tools Reference: chatmcp.googleapis.com

Công cụ: search_messages

Tìm kiếm tin nhắn trò chuyện trên Google Chat bằng từ khoá và bộ lọc, sau đó trả về tin nhắn ở định dạng Markdown. Hoạt động trên tất cả không gian mà người dùng có quyền truy cập hoặc có thể được giới hạn trong một cuộc trò chuyện cụ thể.

Hãy làm theo hướng dẫn này khi quyết định sử dụng search_messages so với các công cụ tìm kiếm hoặc đọc khác:

  • Sử dụng search_messages khi tìm nội dung tin nhắn, từ khoá, lượt đề cập, đường liên kết, người gửi hoặc tin nhắn chưa đọc cụ thể, có thể trên nhiều không gian hoặc không có mã cuộc trò chuyện đã biết.
  • Sử dụng list_messages khi bạn biết mã nhận dạng cụ thể của không gian hoặc chuỗi tin nhắn và muốn đọc tin nhắn theo thứ tự thời gian.
  • Sử dụng search_conversations để tìm siêu dữ liệu của không gian, chẳng hạn như mã cuộc trò chuyện theo tên hiển thị của không gian hoặc người tham gia (lệnh này chỉ tìm siêu dữ liệu, chứ không tìm nội dung tin nhắn).

Nếu bạn cung cấp searchParameters mà không có bộ lọc cụ thể, thì các tin nhắn gần đây trong những cuộc trò chuyện mà người dùng có thể truy cập sẽ được trả về.

Mã mẫu sau đây cho biết cách sử dụng curl để gọi công cụ MCP search_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": "search_messages",
    "arguments": {
      // Provide these details according to the MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

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

SearchMessagesRequest

Biểu diễn dưới dạng JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Trường
searchParameters

object (SearchParameters)

Bắt buộc. Các tham số tìm kiếm cần dùng cho hoạt động tìm kiếm.
pageSize

integer

Không bắt buộc. Số lượng kết quả tối đa cần trả về (tối đa 100). Nếu không chỉ định, hệ thống sẽ trả về tối đa 25 kết quả.
pageToken

string

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

SearchParameters

Biểu diễn dưới dạng JSON 
{
  "keywords": [
    string
  ],
  "conversationId": string,
  "sender": string,
  "isUnread": boolean,
  "hasLink": boolean,
  "startTime": string,
  "endTime": string,
  "mentionsMe": boolean,
  "conversationIncludesUser": string,
  "spaceDisplayNames": [
    string
  ],
  "conversationTypes": [
    enum (ConversationType)
  ],
  "hasAttachment": boolean
}
Trường
keywords[]

string

Không bắt buộc. Một nhóm từ khoá dùng để lọc kết quả.
conversationId

string

Không bắt buộc. Phạm vi tìm kiếm theo một giá trị nhận dạng cuộc trò chuyện cụ thể, như được trả về từ công cụ search_conversations. Định dạng: spaces/{ID}.
sender

string

Không bắt buộc. Lọc ra tin nhắn của một người dùng cụ thể. Bạn có thể sử dụng email hoặc tên tài nguyên của người gửi. Tên tài nguyên người dùng được định dạng là users/{ID}, trong đó {ID} có thể là mã nhận dạng người dùng hoặc địa chỉ email của họ.
isUnread

boolean

Không bắt buộc. Lọc ra những tin nhắn mà người dùng gọi chưa đọc.
hasLink

boolean

Không bắt buộc. Lọc những thư chứa ít nhất một URL.
startTime

string

Không bắt buộc. Lọc thư được tạo sau thời điểm này. Định dạng: Dấu thời gian ISO 8601.
endTime

string

Không bắt buộc. Lọc những tin nhắn được tạo trước thời điểm này. Định dạng: Dấu thời gian ISO 8601.
mentionsMe

boolean

Không bắt buộc. Lọc ra những tin nhắn đề cập rõ ràng đến người dùng đang gọi.
conversationIncludesUser

string

Không bắt buộc. Lọc tin nhắn trong tin nhắn trực tiếp và cuộc trò chuyện nhóm có chứa email hoặc mã nhận dạng của người dùng cụ thể.
spaceDisplayNames[]

string

Không bắt buộc. Lọc theo danh sách tên không gian; tên hiển thị của không gian được so khớp một phần. Lưu ý: Chỉ trả về 5 kết quả phù hợp nhất.
conversationTypes[]

enum (ConversationType)

Không bắt buộc. Lọc theo loại cuộc trò chuyện.
hasAttachment

boolean

Không bắt buộc. Lọc những thư có chứa ít nhất một tệp đính kèm. Lưu ý: Trường này đang trong quá trình phát triển và có thể chưa được hỗ trợ trong một số môi trường.

ConversationType

Xác định loại cuộc trò chuyện.

Enum
CONVERSATION_TYPE_UNSPECIFIED Không xác định.
NAMED_SPACE Một không gian có tên.
GROUP_CHAT Cuộc trò chuyện nhóm giữa 3 người trở lên.
DIRECT_MESSAGE Tin nhắn trực tiếp giữa hai người hoặc giữa một người và một ứng dụng Chat.

Giản đồ đầu ra

Phản hồi cho yêu cầu tìm tin nhắn trò chuyện trong Google Chat. Nếu next_page_token được điền sẵn, bạn có thể gọi lại SearchMessages bằng mã thông báo đó để truy xuất trang kết quả tiếp theo.

SearchMessagesResponse

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

object (ChatMessage)

Danh sách các đối tượng thư khớp với tiêu chí tìm kiếm.
nextPageToken

string

Mã thông báo có thể được gửi dưới dạng page_token để truy xuất trang tiếp theo. Nếu trường này bị bỏ qua, thì sẽ không có trang tiếp theo.

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