MCP Tools Reference: chatmcp.googleapis.com

Công cụ: search_messages

Tìm kiếm tin nhắ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ả cá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 cụ thể hoặc tin nhắn chưa đọc có thể nằm trong nhiều không gian hoặc không có mã nhận dạng 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 trình 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ã nhận dạng cuộc trò chuyện theo tên hiển thị của không gian hoặc người tham gia (chỉ tìm kiếm siêu dữ liệu, không tìm kiếm nội dung tin nhắn).

Nếu searchParameters được cung cấp mà không có bộ lọc cụ thể, thì các thông báo gần đây trong các 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ụ search_messages MCP.

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
}'

Giản đồ đầ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, tối đa 25 kết quả sẽ được trả về.
pageToken

string

Không bắt buộc. Mã thông báo trang nhận được từ một lệnh gọi search_messages trước đó. Cung cấp thông tin 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)
  ]
}
Trường
keywords[]

string

Không bắt buộc. Một tập hợp các từ khoá được dùng để lọc kết quả.
conversationId

string

Không bắt buộc. Giới hạn phạm vi tìm kiếm trong một mã 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 thư của một người dùng cụ thể. Bạn có thể sử dụng địa chỉ 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 cá nhân hoặc địa chỉ email của họ.
isUnread

boolean

Không bắt buộc. Lọc 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ông báo chứa ít nhất một URL.
startTime

string

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

string

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

boolean

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

string

Không bắt buộc. Lọc những tin nhắn trong tin nhắn trực tiếp và cuộc trò chuyện nhóm có chứa địa chỉ email hoặc mã nhận dạng cụ thể của người dùng.
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ỉ 5 kết quả trùng khớp hàng đầu được trả về.
conversationTypes[]

enum (ConversationType)

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

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 kiếm tin nhắn trên 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 tin nhắn khớp với tiêu chí tìm kiếm.
nextPageToken

string

Một 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 bạn bỏ qua trường này, thì sẽ không có cá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)
    }
  ]
}
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 thư mà thư này thuộc về. Trường này sẽ trống nếu tin nhắn không được phân luồng. Định dạng: spaces/{space}/threads/{thread}
plaintextBody

string

Nội dung văn bản của thông báo bằng cách 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 cho biết thời điểm tạo thông báo.
threadedReply

boolean

Tin nhắn có phải là tin nhắn trả lời trong một 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ề các lượt thể hiện cảm xúc bằng biểu tượng trong tin nhắn.

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 một 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)
}
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.

ReactionSummary

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

string

Chuỗi unicode 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 thể hiện cảm xúc bằng biểu tượng cảm xúc liên quan.

UserType

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

Enum
USER_TYPE_UNSPECIFIED Không xác định.
HUMAN Người dùng thực.
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 sẽ được tải lên Chat.

Chú giải công cụ

Chú thích công cụ được gửi đến các ứ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 các ứng dụng đều coi những gợi ý này là không đáng tin cậy, nhưng bạn 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 công cụ. Mặc định: false.
  • destructiveHint: Nếu đúng, công cụ có thể thực hiện các hành động phá huỷ. Nếu là false, thì công cụ chỉ có thể thực hiện các thao tác 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 ảnh hưởng nào đến môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, công cụ này 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ụ: một công cụ tìm kiếm trên web sẽ là thế giới mở, trong khi một công cụ bộ nhớ sẽ không phải là thế giới mở.

Gợi ý phá huỷ: ❌ | Gợi ý bất biến: ✅ | Gợi ý chỉ đọc: ✅ | Gợi ý 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