MCP Tools Reference: chatmcp.googleapis.com

Alat: search_messages

Menelusuri pesan Google Chat menggunakan kata kunci dan filter, lalu menampilkan hasilnya dalam format Markdown. Berfungsi di semua ruang yang dapat diakses pengguna, atau dapat dicakupkan ke percakapan tertentu.

Ikuti panduan ini saat memutuskan untuk menggunakan search_messages vs alat penelusuran atau pembacaan lainnya:

  • Gunakan search_messages saat mencari konten pesan, kata kunci, sebutan, link, pengirim, atau pesan yang belum dibaca tertentu, yang berpotensi berada di beberapa ruang atau tanpa ID percakapan yang diketahui.
  • Gunakan list_messages jika Anda mengetahui ID ruang atau rangkaian pesan tertentu dan ingin membaca pesan secara berurutan dalam urutan kronologis.
  • Gunakan search_conversations untuk menemukan metadata ruang seperti ID percakapan berdasarkan nama tampilan ruang atau peserta (alat ini hanya menelusuri metadata, bukan konten pesan).

Jika searchParameters diberikan tanpa filter tertentu, pesan terbaru di seluruh percakapan yang dapat diakses oleh pengguna akan ditampilkan.

Contoh kode berikut menunjukkan cara menggunakan curl untuk memanggil alat MCP search_messages.

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

Skema Input

SearchMessagesRequest

Representasi JSON 
{
  "searchParameters": {
    object (SearchParameters)
  },
  "pageSize": integer,
  "pageToken": string
}
Kolom
searchParameters

object (SearchParameters)

Wajib. Parameter penelusuran yang akan digunakan untuk penelusuran.
pageSize

integer

Opsional. Jumlah hasil maksimum yang akan ditampilkan (maksimal hingga 100). Jika tidak ditentukan, paling banyak 25 yang akan ditampilkan.
pageToken

string

Opsional. Token halaman, yang diterima dari panggilan search_messages sebelumnya. Berikan ini untuk mengambil halaman selanjutnya.

SearchParameters

Representasi 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
}
Kolom
keywords[]

string

Opsional. Kumpulan kata kunci yang digunakan untuk memfilter hasil.
conversationId

string

Opsional. Membatasi penelusuran ke ID percakapan tertentu, seperti yang ditampilkan dari alat search_conversations. Format: spaces/{ID}.
sender

string

Opsional. Memfilter pesan dari pengguna tertentu. Email atau nama resource pengirim dapat digunakan. Nama resource pengguna diformat sebagai users/{ID}, dengan {ID} dapat berupa ID orang atau alamat emailnya.
isUnread

boolean

Opsional. Filter untuk pesan yang belum dibaca oleh pengguna yang menelepon.
hasLink

boolean

Opsional. Filter untuk pesan yang berisi minimal satu URL.
startTime

string

Opsional. Filter untuk pesan yang dibuat setelah waktu ini. Format: Stempel waktu ISO 8601.
endTime

string

Opsional. Filter untuk pesan yang dibuat sebelum waktu ini. Format: Stempel waktu ISO 8601.
mentionsMe

boolean

Opsional. Memfilter pesan yang secara eksplisit menyebutkan pengguna yang menelepon.
conversationIncludesUser

string

Opsional. Filter pesan dalam DM dan chat grup yang menyertakan email atau ID pengguna tertentu.
spaceDisplayNames[]

string

Opsional. Filter menurut daftar nama ruang; nama tampilan ruang dicocokkan sebagian. Catatan: Hanya 5 kecocokan teratas yang ditampilkan.
conversationTypes[]

enum (ConversationType)

Opsional. Filter menurut jenis percakapan.
hasAttachment

boolean

Opsional. Memfilter pesan yang berisi minimal satu lampiran. Catatan: Kolom ini sedang dalam pengembangan dan mungkin belum didukung di semua lingkungan.

ConversationType

Menentukan jenis percakapan.

Enum
CONVERSATION_TYPE_UNSPECIFIED Tidak ditentukan.
NAMED_SPACE Ruang bernama.
GROUP_CHAT Chat grup antara 3 orang atau lebih.
DIRECT_MESSAGE Pesan langsung antara dua orang, atau antara seseorang dan aplikasi Chat.

Skema Output

Respons untuk menelusuri pesan chat Google Chat. Jika next_page_token diisi, panggil SearchMessages dapat dipanggil lagi dengan token tersebut untuk mengambil halaman hasil berikutnya.

SearchMessagesResponse

Representasi JSON 
{
  "messages": [
    {
      object (ChatMessage)
    }
  ],
  "nextPageToken": string
}
Kolom
messages[]

object (ChatMessage)

Daftar objek pesan yang cocok dengan kriteria penelusuran.
nextPageToken

string

Token yang dapat dikirim sebagai page_token untuk mengambil halaman berikutnya. Jika kolom ini dihilangkan, tidak akan ada halaman berikutnya.

ChatMessage

Representasi JSON 
{
  "messageId": string,
  "threadId": string,
  "plaintextBody": string,
  "sender": {
    object (User)
  },
  "createTime": string,
  "threadedReply": boolean,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "reactionSummaries": [
    {
      object (ReactionSummary)
    }
  ],
  "quotedMessageMetadata": {
    object (QuotedMessageMetadata)
  }
}
Kolom
messageId

string

Nama resource pesan. Format: spaces/{space}/messages/{message}
threadId

string

Rangkaian pesan yang menyertakan pesan ini. Kolom ini akan kosong jika pesan tidak di-thread. Format: spaces/{space}/threads/{thread}
plaintextBody

string

Isi teks pesan menggunakan pemformatan Markdown.
sender

object (User)

Pengirim pesan.
createTime

string

Hanya output. Stempel waktu saat pesan dibuat. Format: Stempel waktu ISO 8601.
threadedReply

boolean

Apakah pesan merupakan balasan rangkaian pesan.
attachments[]

object (ChatAttachmentMetadata)

Lampiran yang disertakan dalam pesan.
reactionSummaries[]

object (ReactionSummary)

Ringkasan reaksi emoji yang disertakan dalam pesan.
quotedMessageMetadata

object (QuotedMessageMetadata)

Hanya output. Informasi tentang pesan asli yang dikutip atau diteruskan dalam pesan ini. Catatan: Kolom ini sedang dalam pengembangan dan mungkin belum ada di semua lingkungan.

Pengguna

Representasi JSON 
{
  "userId": string,
  "displayName": string,
  "email": string,
  "userType": enum (UserType)
}
Kolom
userId

string

Nama resource pengguna Chat. Format: users/{user}.
displayName

string

Nama tampilan pengguna Chat.
email

string

Alamat email pengguna. Kolom ini hanya diisi jika jenis pengguna adalah HUMAN.
userType

enum (UserType)

Jenis pengguna.

ChatAttachmentMetadata

Representasi JSON 
{
  "attachmentId": string,
  "filename": string,
  "mimeType": string,
  "source": enum (Source),
  "driveFileId": string
}
Kolom
attachmentId

string

Nama resource lampiran. Format: spaces/{space}/messages/{message}/attachments/{attachment}.
filename

string

Nama lampiran.
mimeType

string

Jenis konten (jenis MIME).
source

enum (Source)

Sumber lampiran.
driveFileId

string

Hanya output. ID untuk file Google Drive. Hanya diisi jika sumbernya adalah DRIVE_FILE. Gunakan dengan MCP Google Drive.

ReactionSummary

Representasi JSON 
{
  "emoji": string,
  "count": integer
}
Kolom
emoji

string

String unicode emoji atau nama emoji kustom.
count

integer

Jumlah total reaksi yang menggunakan emoji terkait.

QuotedMessageMetadata

Representasi JSON 
{
  "messageId": string,
  "lastUpdateTime": string,
  "quoteType": enum (QuoteType),
  "plaintextBody": string,
  "sender": string,
  "attachments": [
    {
      object (ChatAttachmentMetadata)
    }
  ],
  "forwardedMetadata": {
    object (ForwardedMetadata)
  }
}
Kolom
messageId

string

Hanya output. Nama resource pesan asli yang dikutip atau diteruskan. Format: spaces/{space}/messages/{message}
lastUpdateTime

string

Hanya output. Stempel waktu saat pesan asli dibuat atau terakhir diperbarui sebelum dikutip atau diteruskan. Format: Stempel waktu ISO 8601.
quoteType

enum (QuoteType)

Hanya output. Jenis kutipan.
plaintextBody

string

Hanya output. Snapshot isi teks pesan asli pada saat mengutip atau meneruskan. Diformat menggunakan Markdown untuk FORWARD, dan teks biasa untuk REPLY.
sender

string

Hanya output. Nama tampilan penulis pesan asli.
attachments[]

object (ChatAttachmentMetadata)

Hanya output. Lampiran yang merupakan bagian dari pesan asli. Hanya diisi untuk jenis penawaran harga FORWARD.
forwardedMetadata

object (ForwardedMetadata)

Hanya output. Metadata tentang percakapan sumber pesan yang diteruskan. Hanya diisi untuk jenis penawaran harga FORWARD.

ForwardedMetadata

Representasi JSON 
{
  "conversationId": string,
  "conversationDisplayName": string
}
Kolom
conversationId

string

Hanya output. Nama resource percakapan sumber. Format: spaces/{space}
conversationDisplayName

string

Hanya output. Nama tampilan percakapan sumber pada saat pesan diteruskan. Untuk ruang bernama, ini adalah nama ruang. Untuk pesan langsung personal, ini adalah nama peserta lain. Untuk chat grup tanpa nama, nama ini dibuat berdasarkan nama anggota.

UserType

Jenis pengguna Google Chat.

Enum
USER_TYPE_UNSPECIFIED Tidak ditentukan.
HUMAN Pengguna manusia.
APP Pengguna aplikasi.

Sumber

Sumber lampiran.

Enum
SOURCE_UNSPECIFIED Dilindungi Undang-Undang.
DRIVE_FILE File tersebut adalah file Google Drive.
UPLOADED_CONTENT File diupload ke Chat.

QuoteType

Jenis kutipan yang menunjukkan apakah pesan tersebut adalah balasan kutipan atau pesan yang diteruskan.

Enum
QUOTE_TYPE_UNSPECIFIED Dilindungi Undang-Undang. Jenis kutipan tidak ditentukan.
REPLY Pesan tersebut adalah balasan kutipan untuk pesan asli dalam rangkaian pesan yang sama.
FORWARD Pesan diteruskan dari pesan asli dalam percakapan yang berbeda, atau dari rangkaian pesan yang berbeda dalam percakapan yang sama.

Anotasi Alat

Anotasi alat dikirim ke klien MCP untuk menjelaskan risiko dasar alat tertentu. Sebagian besar klien memperlakukan petunjuk ini sebagai tidak tepercaya, tetapi petunjuk tersebut dapat digunakan untuk memutuskan kapan perintah konfirmasi dapat dikirim kepada pengguna.

Bersama dengan string judul, petunjuk boolean berikut ditentukan sebagai berikut:

  • readOnlyHint: Jika benar, alat tidak akan mengubah lingkungannya. Default: false.
  • destructiveHint: Jika benar, alat dapat melakukan tindakan destruktif. Jika salah (false), alat hanya dapat melakukan tindakan aditif. Default: true.
  • idempotentHint: Jika benar, memanggil alat berulang kali dengan argumen yang sama tidak akan memberikan efek tambahan pada lingkungannya. Default: false.
  • openWorldHint: Jika benar, alat dapat berinteraksi dengan 'open world' entitas eksternal. Jika salah, alat hanya dapat berinteraksi dengan entity internal. Misalnya, alat penelusuran web akan bersifat open world, sedangkan alat memori tidak akan bersifat open world.

Petunjuk Destruktif: ❌ | Petunjuk Idempoten: ✅ | Petunjuk Hanya Baca: ✅ | Petunjuk Open World: ❌

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • 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