MCP Tools Reference: chatmcp.googleapis.com

Công cụ: search_conversations

Tìm kiếm các cuộc trò chuyện trên Google Chat (không gian có tên, tin nhắn trực tiếp (DM) hoặc cuộc trò chuyện nhóm) theo tên hiển thị hoặc người tham gia để tìm mã nhận dạng cuộc trò chuyện.

Công cụ này tìm kiếm siêu dữ liệu của cuộc trò chuyện chứ KHÔNG tìm kiếm nội dung tin nhắn. Để tìm kiếm trong nhật ký tin nhắn hoặc tìm tin nhắn theo từ khoá/người gửi/dấu thời gian, hãy sử dụng biểu tượng search_messages.

Nếu chỉ có participants, công cụ này sẽ tìm thấy tin nhắn trực tiếp 1:1 (nếu bạn cung cấp một người tham gia) hoặc cuộc trò chuyện nhóm (nếu bạn cung cấp nhiều người tham gia) có chứa những người tham gia được chỉ định và người dùng gọi.

Nếu chỉ cung cấp query, công cụ này sẽ tìm kiếm những cuộc trò chuyện có cụm từ tìm kiếm là một chuỗi con không phân biệt chữ hoa chữ thường của tên hiển thị của cuộc trò chuyện.

Nếu bạn cung cấp cả participants và query, công cụ này sẽ tìm các cuộc trò chuyện theo người tham gia rồi lọc theo tên hiển thị.

Nếu bạn không cung cấp participants và query, thì công cụ này sẽ liệt kê tất cả cuộc trò chuyện mà người dùng gọi là thành viên.

Công cụ này chỉ liệt kê những cuộc trò chuyện mà người dùng gọi là thành viên.

Trả về danh sách các đối tượng cuộc trò chuyện chứa mã nhận dạng cuộc trò chuyện (định dạng: spaces/{space}), tên hiển thị và loại cuộc trò chuyện.

LƯU Ý QUAN TRỌNG: Danh sách conversations trống không có nghĩa là không còn kết quả nào nữa. Nếu có next_page_token, bạn có thể tìm nạp thêm các trang. Nếu bạn nhận được một danh sách trống nhưng có biểu tượng next_page_token, hãy hỏi người dùng xem bạn có nên tiếp tục tìm kiếm hay không.

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

Curl Request 
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_conversations",
    "arguments": {
      // provide these details according to the tool MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

Giản đồ đầu vào

SearchConversationsRequest

Biểu diễn dưới dạng JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Trường
spaceNameQuery

string

Không bắt buộc. ers_text: Văn bản cần tìm trong tên hiển thị của không gian (so khớp chuỗi con không phân biệt chữ hoa chữ thường).
pageSize

integer

Không bắt buộc. Số lượng không gian tối đa cần trả về. Dịch vụ có thể trả về ít hơn giá trị này. Nếu bạn không chỉ định, hệ thống sẽ trả về tối đa 20 không gian. Giá trị tối đa là 1.000; các giá trị trên 1.000 sẽ được chuyển đổi thành 1.000.
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_conversations trước đó. Cung cấp thông tin này để truy xuất trang tiếp theo.
participants[]

string

Không bắt buộc. Danh sách địa chỉ email của những người tham gia để lọc các cuộc trò chuyện, không bao gồm người gọi.

Giản đồ đầu ra

Phản hồi chứa danh sách các cuộc trò chuyện phù hợp.

SearchConversationsResponse

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

object (Conversation)

Danh sách các đối tượng cuộc trò chuyện phù hợp với tiêu chí tìm kiếm. Mỗi cuộc trò chuyện đều có conversation_id (định dạng: spaces/{space}), display_name, conversation_type và last_active_timestamp.
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.

Cuộc trò chuyện

Biểu diễn dưới dạng JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Trường
conversationId

string

Mã nhận dạng của cuộc trò chuyện (ví dụ: "spaces/AAAAAAAAA").
displayName

string

Tên hiển thị của cuộc trò chuyện.
conversationType

enum (ConversationType)

Loại cuộc trò chuyện (DIRECT_MESSAGE, GROUP_CHAT hoặc NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Thời gian hoạt động gần đây nhất của cuộc trò chuyện ở định dạng ISO 8601.

Hãy dùng RFC 3339, trong đó dữ liệu đầu ra được tạo sẽ luôn được chuẩn hoá theo múi giờ và sử dụng 0, 3, 6 hoặc 9 chữ số thập phân. Các khoảng lệch khác ngoài "Z" cũng được chấp nhận. Ví dụ: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" hoặc "2014-10-02T15:01:23+05:30".

Dấu thời gian

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

string (int64 format)

Biểu thị số giây của thời gian UTC kể từ thời gian bắt đầu của hệ thống Unix 1970-01-01T00:00:00Z. Phải nằm trong khoảng từ -62135596800 đến 253402300799 (tương ứng với 0001-01-01T00:00:00Z đến 9999-12-31T23:59:59Z).
nanos

integer

Phân số không âm của một giây ở độ phân giải nano giây. Trường này là phần nano giây của thời lượng, chứ không phải là một lựa chọn thay thế cho giây. Giá trị giây âm có phân số vẫn phải có giá trị nano giây không âm để đếm thời gian. Phải nằm trong khoảng từ 0 đến 999.999.999.

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.

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. Aware Client 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 tác động nào đến môi trường của công cụ. Mặc định: false.
  • openWorldHint: Nếu đúng, 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ụ: 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.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly