MCP Tools Reference: chatmcp.googleapis.com

Alat: search_conversations

Menelusuri percakapan Google Chat (ruang bernama, pesan langsung (DM), atau chat grup) berdasarkan nama tampilan atau peserta untuk menemukan ID percakapan.

Alat ini menelusuri metadata percakapan, BUKAN konten pesan. Untuk menelusuri dalam histori pesan atau menemukan pesan berdasarkan kata kunci/pengirim/stempel waktu, gunakan search_messages.

Jika hanya participants yang diberikan, alat ini akan menemukan pesan langsung 1:1 (jika satu peserta diberikan) atau chat grup (jika beberapa peserta diberikan) yang menyertakan peserta yang ditentukan dan pengguna yang memanggil.

Jika hanya query yang diberikan, alat ini akan menelusuri percakapan yang kuerinya adalah substring yang tidak peka huruf besar/kecil dari nama tampilan percakapan.

Jika participants dan query diberikan, alat ini akan menemukan percakapan berdasarkan peserta, lalu memfilternya berdasarkan nama tampilan.

Jika participants maupun query tidak diberikan, alat ini akan mencantumkan semua percakapan yang diikuti pengguna yang memanggil.

Alat ini hanya mencantumkan percakapan yang diikuti pengguna yang memanggil.

Menampilkan daftar objek percakapan yang berisi ID percakapan (format: spaces/{space}), nama tampilan, dan jenis percakapan.

PENTING: Daftar conversations kosong tidak berarti tidak ada hasil lainnya secara keseluruhan. Jika next_page_token ada, halaman lainnya dapat diambil. Jika Anda mendapatkan daftar kosong, tetapi next_page_token ada, tanyakan kepada pengguna apakah Anda harus melanjutkan penelusuran.

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

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

Skema Input

SearchConversationsRequest

Representasi JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
Kolom
spaceNameQuery

string

Opsional. Teks yang akan ditelusuri dalam nama tampilan ruang (kecocokan substring yang tidak peka huruf besar/kecil).
pageSize

integer

Opsional. Jumlah maksimum ruang yang akan ditampilkan. Layanan dapat menampilkan kurang dari nilai ini. Jika tidak ditentukan, maksimal 20 ruang akan ditampilkan. Nilai maksimumnya adalah 1.000; nilai di atas 1.000 akan dipaksa menjadi 1.000.
pageToken

string

Opsional. Token halaman, yang diterima dari panggilan search_conversations sebelumnya. Berikan token ini untuk mengambil halaman berikutnya.
participants[]

string

Opsional. Daftar alamat email peserta untuk memfilter percakapan, tidak termasuk pemanggil.

Skema Output

Respons yang berisi daftar percakapan yang cocok.

SearchConversationsResponse

Representasi JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
Kolom
conversations[]

object (Conversation)

Daftar objek percakapan yang cocok dengan kriteria penelusuran. Setiap percakapan mencakup conversation_id (format: spaces/{space}), display_name, conversation_type, dan last_active_timestamp.
nextPageToken

string

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

Percakapan

Representasi JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
Kolom
conversationId

string

ID percakapan (misalnya, "spaces/AAAAAAAAA").
displayName

string

Nama tampilan percakapan.
conversationType

enum (ConversationType)

Jenis percakapan (DIRECT_MESSAGE, GROUP_CHAT, atau NAMED_SPACE).
lastActiveTimestamp

string (Timestamp format)

Waktu aktif terakhir percakapan dalam format ISO 8601.

Menggunakan RFC 3339 yang outputnya akan selalu dinormalisasi Z dan menggunakan 0, 3, 6, atau 9 digit pecahan. Offset selain "Z" juga diterima. Contoh: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z", atau "2014-10-02T15:01:23+05:30".

Stempel waktu

Representasi JSON 
{
  "seconds": string,
  "nanos": integer
}
Kolom
seconds

string (int64 format)

Mewakili detik waktu UTC sejak epoch Unix 1970-01-01T00:00:00Z. Harus antara -62135596800 dan 253402300799 inklusif (yang sesuai dengan 0001-01-01T00:00:00Z hingga 9999-12-31T23:59:59Z).
nanos

integer

Pecahan detik non-negatif pada resolusi nanodetik. Kolom ini adalah bagian nanodetik dari durasi, bukan alternatif untuk detik. Nilai detik negatif dengan pecahan harus tetap memiliki nilai nanos non-negatif yang menghitung maju dalam waktu. Harus antara 0 dan 999.999.999 inklusif.

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 orang dan aplikasi Chat.

Anotasi Alat

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

Selain string judul, petunjuk boolean berikut ditentukan sebagai berikut:

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

Petunjuk Destruktif: ❌ | Petunjuk Idempoten: ✅ | Petunjuk Hanya Baca: ✅ | Petunjuk Dunia Terbuka: ❌

Cakupan Otorisasi

Memerlukan salah satu cakupan OAuth berikut:

  • https://www.googleapis.com/auth/chat.memberships.readonly
  • https://www.googleapis.com/auth/chat.spaces
  • https://www.googleapis.com/auth/chat.spaces.readonly