MCP Tools Reference: chatmcp.googleapis.com

เครื่องมือ: search_conversations

ค้นหาการสนทนาใน Google Chat เพื่อค้นหารหัสการสนทนา พื้นที่ทำงานที่มีชื่อจะค้นหาได้จากชื่อที่แสดง (space_name_query) ส่วนข้อความส่วนตัว (DM) และแชทเป็นกลุ่มจะค้นหาได้จากอีเมลของผู้เข้าร่วมเท่านั้น (participants)

เครื่องมือนี้จะค้นหาข้อมูลเมตาของการสนทนา ไม่ใช่เนื้อหาข้อความ หากต้องการค้นหาภายในประวัติข้อความหรือค้นหาข้อความตามคีย์เวิร์ด/ผู้ส่ง/การประทับเวลา ให้ใช้ search_messages

หากระบุเฉพาะ participants เครื่องมือนี้จะค้นหาข้อความส่วนตัวแบบ 1:1 (หากระบุผู้เข้าร่วม 1 คน) หรือแชทเป็นกลุ่ม (หากระบุผู้เข้าร่วมหลายคน) ที่มีผู้เข้าร่วมที่ระบุและผู้ใช้ที่โทร ระบบจะไม่แสดงพื้นที่ทำงานที่มีชื่อ

หากระบุเฉพาะ space_name_query เครื่องมือนี้จะค้นหาเฉพาะพื้นที่ทำงานที่มีชื่อซึ่งคำค้นหาเป็นสตริงย่อยที่ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่ของชื่อที่แสดงของพื้นที่ทำงาน ระบบจะไม่แสดงผล DM และแชทเป็นกลุ่ม ดังนั้นอย่าส่งชื่อบุคคลเป็น space_name_query เพื่อค้นหา DM กับบุคคลนั้น ให้ค้นหาอีเมลของบุคคลนั้นและส่งใน participants แทน

หากระบุทั้ง participants และ space_name_query เครื่องมือนี้จะค้นหา DM หรือแชทเป็นกลุ่มตามผู้เข้าร่วม แล้วกรองตามชื่อที่แสดง

หากไม่ได้ระบุทั้ง participants และ space_name_query เครื่องมือนี้จะแสดงรายการพื้นที่ทำงานที่มีชื่อซึ่งผู้ใช้ที่โทรเป็นสมาชิกอยู่ (ไม่รวม DM และแชทเป็นกลุ่ม)

เครื่องมือนี้จะแสดงเฉพาะการสนทนาที่ผู้ใช้ที่โทรเป็นสมาชิกเท่านั้น

แสดงรายการออบเจ็กต์การสนทนาที่มีรหัสการสนทนา (รูปแบบ: spaces/{space}) ชื่อที่แสดง และประเภทการสนทนา

สำคัญ: รายการ conversations ที่ว่างเปล่าไม่ได้หมายความว่าไม่มีผลลัพธ์อีกต่อไปโดยรวม หากมี next_page_token ระบบจะดึงข้อมูลหน้าเว็บเพิ่มเติมได้ หากคุณได้รับรายการที่ว่างเปล่าแต่มี next_page_token ให้ถามผู้ใช้ว่าคุณควรค้นหาต่อหรือไม่

ตัวอย่างโค้ดต่อไปนี้แสดงวิธีใช้ curl เพื่อเรียกใช้เครื่องมือ MCP search_conversations

คำขอ 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 MCP tool specification.
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

สคีมาอินพุต

SearchConversationsRequest

การแสดง JSON 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
ฟิลด์
spaceNameQuery

string

ไม่บังคับ ข้อความที่จะค้นหาภายในชื่อที่แสดงของการสนทนา (การจับคู่สตริงย่อยที่ไม่คำนึงถึงตัวพิมพ์เล็กและตัวพิมพ์ใหญ่)

หาก participants ว่างเปล่า ระบบจะค้นหาเฉพาะพื้นที่ทำงานที่มีชื่อเท่านั้น และจะไม่แสดงข้อความส่วนตัว (DM) และแชทเป็นกลุ่ม ดังนั้นการค้นหาชื่อบุคคลที่นี่จะไม่พบ DM กับบุคคลดังกล่าว หากต้องการค้นหา DM หรือแชทเป็นกลุ่ม ให้ระบุอีเมลของสมาชิกใน participants แทน หากตั้งค่า participants ไว้ การค้นหานี้จะกรอง DM หรือแชทเป็นกลุ่มที่ตรงกันเพิ่มเติมตามชื่อที่แสดง
pageSize

integer

ไม่บังคับ จำนวนพื้นที่ทำงานสูงสุดที่จะแสดงผล บริการอาจแสดงผลลัพธ์น้อยกว่าค่านี้ หากไม่ระบุ ระบบจะแสดงผลพื้นที่ทำงานไม่เกิน 20 รายการ ค่าสูงสุดคือ 1,000 โดยค่าที่มากกว่า 1,000 จะถูกบังคับให้เป็น 1,000
pageToken

string

ไม่บังคับ โทเค็นหน้าเว็บที่ได้รับจากการเรียก search_conversations ก่อนหน้า ระบุโทเค็นนี้เพื่อเรียกข้อมูลหน้าถัดไป
participants[]

string

ไม่บังคับ รายชื่ออีเมลของผู้เข้าร่วมเพื่อกรองการสนทนา โดยไม่รวมผู้โทร ใช้ตัวเลือกนี้เพื่อค้นหาข้อความส่วนตัว (DM) และแชทเป็นกลุ่ม โดยผู้เข้าร่วมคนเดียวจะแสดงผล DM แบบ 1:1 กับบุคคลนั้น และผู้เข้าร่วมหลายคนจะแสดงผลแชทเป็นกลุ่มที่มีผู้เข้าร่วมทั้งหมด ระบบจะไม่แสดงพื้นที่ทำงานที่มีชื่อเมื่อตั้งค่าช่องนี้

สคีมาเอาต์พุต

การตอบกลับที่มีรายการการสนทนาที่ตรงกัน

SearchConversationsResponse

การแสดง JSON 
{
  "conversations": [
    {
      object (Conversation)
    }
  ],
  "nextPageToken": string
}
ช่อง
conversations[]

object (Conversation)

รายการออบเจ็กต์การสนทนาที่ตรงกับเกณฑ์การค้นหา การสนทนาแต่ละรายการประกอบด้วย conversation_id (รูปแบบ: spaces/{space}), display_name, conversation_type และ last_active_timestamp
nextPageToken

string

โทเค็นที่ส่งเป็น page_token เพื่อเรียกข้อมูลหน้าถัดไปได้ หากไม่มีช่องนี้ แสดงว่าไม่มีหน้าถัดไป

จะป้อนข้อมูลก็ต่อเมื่อมีการกรองคำขอตาม participants เท่านั้น

การสนทนา

การแสดง JSON 
{
  "conversationId": string,
  "displayName": string,
  "conversationType": enum (ConversationType),
  "lastActiveTimestamp": string
}
ช่อง
conversationId

string

รหัสของการสนทนา (เช่น "spaces/AAAAAAAAA")
displayName

string

ชื่อที่แสดงของการสนทนา สำหรับพื้นที่ทำงานที่มีชื่อ ค่าจะเป็นชื่อพื้นที่ทำงาน สำหรับข้อความส่วนตัวแบบ 1:1 ชื่อนี้จะเป็นชื่อของผู้เข้าร่วมคนอื่น สำหรับแชทเป็นกลุ่มที่ไม่มีชื่อ ชื่อนี้จะเป็นชื่อที่สร้างขึ้นตามชื่อของสมาชิก
conversationType

enum (ConversationType)

ประเภทการสนทนา (DIRECT_MESSAGE, GROUP_CHAT หรือ NAMED_SPACE)
lastActiveTimestamp

string (Timestamp format)

เวลาที่ใช้งานล่าสุดของการสนทนาในรูปแบบ ISO 8601

ใช้ RFC 3339 โดยเอาต์พุตที่สร้างขึ้นจะได้รับการแปลงเป็นรูปแบบ Z เสมอ และใช้ตัวเลขเศษส่วน 0, 3, 6 หรือ 9 หลัก นอกจากนี้ ระบบยังยอมรับออฟเซ็ตอื่นๆ นอกเหนือจาก "Z" ด้วย เช่น "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" หรือ "2014-10-02T15:01:23+05:30"

การประทับเวลา

การแสดง JSON 
{
  "seconds": string,
  "nanos": integer
}
ช่อง
seconds

string (int64 format)

แสดงวินาทีของเวลา UTC นับตั้งแต่ Unix Epoch 1970-01-01T00:00:00Z ต้องอยู่ระหว่าง -62135596800 ถึง 253402300799 (ซึ่งสอดคล้องกับ 0001-01-01T00:00:00Z ถึง 9999-12-31T23:59:59Z)
nanos

integer

เศษส่วนของวินาทีที่ไม่เป็นค่าลบที่ความละเอียดระดับนาโนวินาที ช่องนี้เป็นส่วนนาโนวินาทีของระยะเวลา ไม่ใช่ทางเลือกแทนวินาที ค่าที่สองที่เป็นลบซึ่งมีเศษส่วนต้องยังคงมีค่านาโนที่ไม่เป็นลบซึ่งนับเวลาไปข้างหน้า ต้องอยู่ระหว่าง 0 ถึง 999,999,999

ConversationType

กำหนดประเภทของการสนทนา

Enum
CONVERSATION_TYPE_UNSPECIFIED ไม่ระบุ
NAMED_SPACE พื้นที่ทำงานที่มีชื่อ
GROUP_CHAT แชทเป็นกลุ่มระหว่างผู้คนตั้งแต่ 3 คนขึ้นไป
DIRECT_MESSAGE ข้อความส่วนตัวระหว่างมนุษย์ 2 คน หรือมนุษย์กับแอปใน Chat

คำอธิบายประกอบเครื่องมือ

ระบบจะส่งคำอธิบายประกอบเครื่องมือไปยังไคลเอ็นต์ MCP เพื่ออธิบายความเสี่ยงพื้นฐานของเครื่องมือหนึ่งๆ ไคลเอ็นต์ส่วนใหญ่จะถือว่าคำแนะนำเหล่านี้ไม่น่าเชื่อถือ แต่สามารถใช้เพื่อตัดสินใจว่าจะส่งข้อความแจ้งยืนยันไปยังผู้ใช้เมื่อใด

นอกจากสตริงชื่อแล้ว ยังมีการกำหนดคำแนะนำบูลีนต่อไปนี้ด้วย

  • readOnlyHint: หากเป็นจริง เครื่องมือจะไม่แก้ไขสภาพแวดล้อมของตนเอง ค่าเริ่มต้น: false
  • destructiveHint: หากเป็น "จริง" เครื่องมือจะดำเนินการที่ทำลายล้างได้ หากเป็นเท็จ เครื่องมือจะดำเนินการได้เฉพาะการดำเนินการแบบเพิ่มเท่านั้น ค่าเริ่มต้น: true
  • idempotentHint: หากเป็นจริง การเรียกใช้เครื่องมือซ้ำๆ ด้วยอาร์กิวเมนต์เดียวกันจะไม่มีผลเพิ่มเติมต่อสภาพแวดล้อม ค่าเริ่มต้น: false
  • openWorldHint: หากเป็น "จริง" เครื่องมือจะโต้ตอบกับเอนทิตีภายนอกแบบ "โอเพนเวิลด์" ได้ หากเป็นเท็จ เครื่องมือจะโต้ตอบได้เฉพาะกับเอนทิตีภายในเท่านั้น ตัวอย่างเช่น เครื่องมือค้นเว็บจะเป็นแบบโอเพนเวิลด์ ส่วนเครื่องมือความทรงจำจะไม่ใช่แบบโอเพนเวิลด์

คำแนะนำแบบทำลาย: ❌ | คำแนะนำแบบนิจพล: ✅ | คำแนะนำแบบอ่านอย่างเดียว: ✅ | คำแนะนำแบบโอเพนเวิลด์: ❌

ขอบเขตการให้สิทธิ์

ต้องใช้ขอบเขต OAuth อย่างใดอย่างหนึ่งต่อไปนี้

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