MCP Tools Reference: chatmcp.googleapis.com

टूल: search_conversations

यह टूल, Google Chat पर मौजूद बातचीत (नाम वाले स्पेस, डायरेक्ट मैसेज (डीएम) या ग्रुप चैट) को डिसप्ले नेम या उसमें शामिल लोगों के हिसाब से खोजता है, ताकि बातचीत के आईडी ढूंढे जा सकें.

यह टूल, बातचीत के मेटाडेटा को खोजता है. यह मैसेज के कॉन्टेंट को नहीं खोजता. मैसेज के इतिहास में खोजने या कीवर्ड/भेजने वाले/टाइमस्टैंप के हिसाब से मैसेज ढूंढने के लिए, search_messages या participants का इस्तेमाल करके बातचीत के आईडी ढूंढें.

यह टूल, बातचीत के मेटाडेटा को खोजता है. यह मैसेज के कॉन्टेंट को नहीं खोजता. मैसेज के इतिहास में खोजने या कीवर्ड/भेजने वाले/टाइमस्टैंप के हिसाब से मैसेज ढूंढने के लिए, search_messages का इस्तेमाल करें.

अगर सिर्फ़ participants की जानकारी दी जाती है, तो यह टूल 1:1 सीधी बातचीत (अगर एक हिस्सा लेने वाले व्यक्ति की जानकारी दी गई है) या ग्रुप चैट (अगर एक से ज़्यादा हिस्सा लेने वाले लोगों की जानकारी दी गई है) ढूंढता है. इनमें बताए गए लोग और कॉल करने वाला व्यक्ति शामिल होता है.

अगर सिर्फ़ query की जानकारी दी जाती है, तो यह टूल ऐसी बातचीत खोजता है जिसमें क्वेरी, बातचीत के डिसप्ले नेम का केस-इनसेंसिटिव सबस्ट्रिंग हो.

अगर participants और query दोनों की जानकारी दी जाती है, तो यह टूल लोगों के हिसाब से बातचीत ढूंढता है. इसके बाद, उन्हें डिसप्ले नेम के हिसाब से फ़िल्टर करता है.

अगर participants और query दोनों की जानकारी नहीं दी जाती है, तो यह टूल उन सभी बातचीत की सूची दिखाता है जिनमें कॉल करने वाला व्यक्ति शामिल है.

यह टूल सिर्फ़ उन बातचीत की सूची दिखाता है जिनमें कॉल करने वाला व्यक्ति शामिल है.

यह टूल, बातचीत के ऑब्जेक्ट की सूची दिखाता है. इसमें बातचीत के आईडी (फ़ॉर्मैट: spaces/{space}), डिसप्ले नेम, और बातचीत के टाइप शामिल होते हैं.

यह टूल, बातचीत के ऑब्जेक्ट की सूची दिखाता है. इसमें बातचीत के आईडी (फ़ॉर्मैट: spaces/{space}), डिसप्ले नेम, और बातचीत के टाइप शामिल होते हैं.

अहम जानकारी: conversations की खाली सूची का मतलब यह नहीं है कि कुल मिलाकर कोई नतीजा नहीं मिला है. अगर next_page_token मौजूद है, तो ज़्यादा पेज फ़ेच किए जा सकते हैं. अगर आपको खाली सूची मिलती है, लेकिन next_page_token मिलता है, तो उपयोगकर्ता से पूछें कि आपको खोज जारी रखनी चाहिए या नहीं.

यहां दिए गए कोड सैंपल में, search_conversations MCP टूल को कॉल करने के लिए, curl का इस्तेमाल करने का तरीका बताया गया है.

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

इनपुट स्कीमा

SearchConversationsRequest

JSON के काेड में दिखाना 
{
  "spaceNameQuery": string,
  "pageSize": integer,
  "pageToken": string,
  "participants": [
    string
  ]
}
फ़ील्ड
spaceNameQuery

string

ज़रूरी नहीं. यह वह टेक्स्ट है जिसे स्पेस के डिसप्ले नेम में खोजना है. यह केस-इनसेंसिटिव सबस्ट्रिंग मैच होता है.
pageSize

integer

ज़रूरी नहीं. यह स्पेस की वह ज़्यादा से ज़्यादा संख्या है जिसे दिखाया जाना है. ऐसा हो सकता है कि सेवा, इस वैल्यू से कम स्पेस दिखाए. अगर इसे तय नहीं किया जाता है, तो ज़्यादा से ज़्यादा 20 स्पेस दिखाए जाएंगे. इसकी ज़्यादा से ज़्यादा वैल्यू 1000 है. 1000 से ज़्यादा वैल्यू को 1000 में बदल दिया जाएगा.
pageToken

string

ज़रूरी नहीं. यह पेज टोकन है, जो search_conversations के पिछले कॉल से मिला है. अगला पेज पाने के लिए, इसे उपलब्ध कराएं.
participants[]

string

ज़रूरी नहीं. यह उन लोगों के ईमेल पतों की सूची है जिनके हिसाब से बातचीत को फ़िल्टर करना है. इसमें कॉल करने वाला व्यक्ति शामिल नहीं है.

आउटपुट स्कीमा

यह जवाब, खोज के नतीजों से मेल खाने वाली बातचीत की सूची दिखाता है.

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

यह बातचीत का डिसप्ले नेम है.
conversationType

enum (ConversationType)

यह बातचीत का टाइप है. जैसे, DIRECT_MESSAGE, GROUP_CHAT या NAMED_SPACE.
lastActiveTimestamp

string (Timestamp format)

यह ISO 8601 फ़ॉर्मैट में, बातचीत के पिछली बार सक्रिय होने का समय है.

यह आरएफ़सी 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)

यह यूटीसी समय के सेकंड दिखाता है. इसकी शुरुआत, 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

यह बातचीत का टाइप तय करता है.

Enums
CONVERSATION_TYPE_UNSPECIFIED नहीं बताया गया है.
NAMED_SPACE नाम वाला स्पेस.
GROUP_CHAT तीन या उससे ज़्यादा लोगों के बीच की ग्रुप चैट.
DIRECT_MESSAGE दो लोगों के बीच का डायरेक्ट मैसेज या किसी व्यक्ति और Chat ऐप्लिकेशन के बीच का डायरेक्ट मैसेज.

टूल के एनोटेशन

टूल के एनोटेशन, MCP क्लाइंट को भेजे जाते हैं. इनसे किसी टूल के बुनियादी जोखिम के बारे में पता चलता है. ज़्यादातर क्लाइंट, इन संकेतों को भरोसेमंद नहीं मानते. हालांकि, इनका इस्तेमाल यह तय करने के लिए किया जा सकता है कि किसी उपयोगकर्ता को पुष्टि करने का प्रॉम्प्ट कब भेजा जाए.

टाइटल स्ट्रिंग के साथ, ये बूलियन हिंट इस तरह तय किए जाते हैं:

  • readOnlyHint: अगर यह 'सही' पर सेट है, तो टूल अपने एनवायरमेंट में कोई बदलाव नहीं करता. डिफ़ॉल्ट रूप से, यह 'गलत' पर सेट होता है.
  • destructiveHint: अगर यह 'सही' पर सेट है, तो टूल, डिस्ट्रक्टिव ऐक्शन ले सकता है. अगर यह 'गलत' पर सेट है, तो टूल सिर्फ़ ऐडिटिव ऐक्शन ले सकता है. डिफ़ॉल्ट रूप से, यह 'सही' पर सेट होता है.
  • idempotentHint: अगर यह 'सही' पर सेट है, तो एक ही आर्ग्युमेंट के साथ टूल को बार-बार कॉल करने पर, उसके एनवायरमेंट पर कोई अतिरिक्त असर नहीं पड़ेगा. डिफ़ॉल्ट रूप से, यह 'गलत' पर सेट होता है.
  • 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