Google Chat के उपयोगकर्ताओं से जानकारी इकट्ठा करना और उसे प्रोसेस करना

इस गाइड में बताया गया है कि Google Chat ऐप्लिकेशन, कार्ड-आधारित इंटरफ़ेस में फ़ॉर्म इनपुट बनाकर, उपयोगकर्ताओं से जानकारी कैसे इकट्ठा और प्रोसेस कर सकते हैं.

Google Chat में, ऐड-ऑन उपयोगकर्ताओं को Google Chat ऐप्लिकेशन के तौर पर दिखते हैं. ज़्यादा जानने के लिए, Google Chat के एक्सटेंशन के बारे में खास जानकारी देखें.

अलग-अलग तरह के विजेट वाला डायलॉग.
पहली इमेज: ऐसा चैट ऐप्लिकेशन जो संपर्क जानकारी इकट्ठा करने के लिए डायलॉग बॉक्स खोलता है.

चैट ऐप्लिकेशन, Chat में या उसके बाहर कार्रवाइयां करने के लिए, उपयोगकर्ताओं से जानकारी का अनुरोध करते हैं. इनमें ये तरीके भी शामिल हैं:

  • सेटिंग कॉन्फ़िगर करें. उदाहरण के लिए, उपयोगकर्ताओं को सूचना सेटिंग को पसंद के मुताबिक बनाने या Chat ऐप्लिकेशन को एक या उससे ज़्यादा स्पेस में कॉन्फ़िगर करने और जोड़ने की अनुमति देने के लिए.
  • Google Workspace के अन्य ऐप्लिकेशन में जानकारी बनाएं या अपडेट करें. उदाहरण के लिए, उपयोगकर्ताओं को Google Calendar इवेंट बनाने की अनुमति दें.
  • उपयोगकर्ताओं को दूसरे ऐप्लिकेशन या वेब सेवाओं में संसाधनों को ऐक्सेस और अपडेट करने की अनुमति दें. उदाहरण के लिए, Chat ऐप्लिकेशन की मदद से उपयोगकर्ता, सीधे Chat स्पेस से सहायता टिकट की स्थिति अपडेट कर सकते हैं.

ज़रूरी शर्तें

Node.js

Google Workspace का ऐसा ऐड-ऑन जो Google Chat में काम करता है. इसे बनाने के लिए, एचटीटीपी से जुड़ी शुरुआती जानकारी वाला लेख पढ़ें.

Apps Script

Google Workspace का ऐसा ऐड-ऑन जो Google Chat में काम करता है. कोई ऐप्लिकेशन बनाने के लिए, Apps Script का शुरुआती कोर्स पूरा करें.

कार्ड का इस्तेमाल करके फ़ॉर्म बनाना

जानकारी इकट्ठा करने के लिए, Chat ऐप्लिकेशन फ़ॉर्म और उनके इनपुट डिज़ाइन करते हैं और उन्हें कार्ड में बनाते हैं. उपयोगकर्ताओं को कार्ड दिखाने के लिए, Chat ऐप्लिकेशन इन Chat इंटरफ़ेस का इस्तेमाल कर सकते हैं:

  • चैट मैसेज, जिनमें एक या उससे ज़्यादा कार्ड शामिल हैं.
  • डायलॉग, ये कार्ड होते हैं जो मैसेज और होम पेजों से नई विंडो में खुलते हैं.

चैट ऐप्लिकेशन, इन विजेट का इस्तेमाल करके कार्ड बना सकते हैं:

  • फ़ॉर्म इनपुट विजेट, जो उपयोगकर्ताओं से जानकारी का अनुरोध करते हैं. इसके अलावा, फ़ॉर्म इनपुट विजेट में पुष्टि करने की सुविधा जोड़ी जा सकती है. इससे यह पक्का किया जा सकता है कि उपयोगकर्ता सही तरीके से जानकारी डालें और उसे सही फ़ॉर्मैट में डालें. चैट ऐप्लिकेशन, इन फ़ॉर्म इनपुट विजेट का इस्तेमाल कर सकते हैं:

    • फ़्री-फ़ॉर्म या सुझाए गए टेक्स्ट के लिए टेक्स्ट इनपुट (textInput).
    • चुने गए इनपुट (selectionInput), चुने जा सकने वाले यूज़र इंटरफ़ेस (यूआई) एलिमेंट होते हैं. जैसे, चेकबॉक्स, रेडियो बटन, और ड्रॉप-डाउन मेन्यू. चुनने के लिए दिए गए इनपुट विजेट, स्टैटिक या डाइनैमिक डेटा सोर्स से भी आइटम पॉप्युलेट कर सकते हैं. उदाहरण के लिए, उपयोगकर्ता उन 'Chat स्पेस' की सूची में से कोई एक चुन सकते हैं जिनके वे सदस्य हैं.

  • बटन विजेट, ताकि उपयोगकर्ता कार्ड में डाली गई वैल्यू सबमिट कर सकें. उपयोगकर्ता के बटन पर क्लिक करने के बाद, Chat ऐप्लिकेशन अपने पास मौजूद जानकारी को प्रोसेस कर सकता है.

नीचे दिए गए उदाहरण में, कार्ड टेक्स्ट इनपुट, तारीख और समय चुनने वाले टूल, और चुनने के लिए दिए गए इनपुट का इस्तेमाल करके संपर्क जानकारी इकट्ठा करता है:

जानकारी इकट्ठा करने के लिए इस्तेमाल किए जा सकने वाले इंटरैक्टिव विजेट के ज़्यादा उदाहरणों के लिए, Google Chat API के दस्तावेज़ में इंटरैक्टिव कार्ड या डायलॉग डिज़ाइन करना देखें.

इंटरैक्टिव विजेट से डेटा पाना

जब भी उपयोगकर्ता किसी बटन पर क्लिक करते हैं, तो इंटरैक्शन की जानकारी के साथ Chat ऐप्लिकेशन की कार्रवाई ट्रिगर होती है. इवेंट पेलोड के commonEventObject में, formInputs ऑब्जेक्ट में वे सभी वैल्यू होती हैं जिन्हें उपयोगकर्ता डालता है.

ऑब्जेक्ट commonEventObject.formInputs.WIDGET_NAME से वैल्यू वापस पाई जा सकती हैं. यहां WIDGET_NAME, name फ़ील्ड है, जिसे आपने विजेट के लिए तय किया है. वैल्यू, विजेट के लिए किसी खास डेटा टाइप के तौर पर दिखती हैं.

यहां किसी इवेंट ऑब्जेक्ट का एक हिस्सा दिखाया गया है, जिसमें उपयोगकर्ता ने हर विजेट के लिए वैल्यू डाली है:

{
  "commonEventObject": { "formInputs": {
    "contactName": { "stringInputs": {
      "value": ["Kai 0"]
    }},
    "contactBirthdate": { "dateInput": {
      "msSinceEpoch": 1000425600000
    }},
    "contactType": { "stringInputs": {
      "value": ["Personal"]
    }}
  }}
}

डेटा पाने के लिए, आपका Chat ऐप्लिकेशन इवेंट ऑब्जेक्ट को मैनेज करता है, ताकि उपयोगकर्ताओं को विजेट में डाली गई वैल्यू मिल सकें. नीचे दी गई टेबल में, किसी फ़ॉर्म इनपुट विजेट की वैल्यू पाने का तरीका बताया गया है. हर विजेट के लिए, टेबल में वह डेटा टाइप दिखता है जिसे विजेट स्वीकार करता है. साथ ही, टेबल में यह भी दिखता है कि इवेंट ऑब्जेक्ट में वैल्यू कहां सेव की जाती है. साथ ही, टेबल में वैल्यू का एक उदाहरण भी दिखता है.

फ़ॉर्म इनपुट विजेट इनपुट डेटा का टाइप इवेंट ऑब्जेक्ट से इनपुट वैल्यू उदाहरण के तौर पर दी गई वैल्यू
textInput stringInputs event.commonEventObject.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs पहली या सिर्फ़ एक वैल्यू पाने के लिए, event.commonEventObject.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker, जो सिर्फ़ तारीखें स्वीकार करता है. dateInput event.commonEventObject.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

डेटा को किसी दूसरे कार्ड पर ट्रांसफ़र करना

जब कोई उपयोगकर्ता किसी कार्ड की जानकारी सबमिट करता है, तो आपको इनमें से कोई भी काम करने के लिए, अतिरिक्त कार्ड दिखाने पड़ सकते हैं:

  • अलग-अलग सेक्शन बनाकर, उपयोगकर्ताओं को लंबे फ़ॉर्म भरने में मदद करें.
  • उपयोगकर्ताओं को शुरुआती कार्ड में दी गई जानकारी की झलक दिखाएं और उसकी पुष्टि करने का विकल्प दें, ताकि वे सबमिट करने से पहले अपने जवाबों की समीक्षा कर सकें.
  • फ़ॉर्म के बाकी हिस्सों में जानकारी अपने-आप भर जाए. उदाहरण के लिए, उपयोगकर्ताओं को अपॉइंटमेंट बनाने के लिए कहने के लिए, Chat ऐप्लिकेशन एक शुरुआती कार्ड दिखा सकता है. इस कार्ड में, अपॉइंटमेंट की वजह पूछी जाती है. इसके बाद, एक और कार्ड दिखता है. इसमें अपॉइंटमेंट के टाइप के आधार पर, उपलब्ध समय की जानकारी दी जाती है.

शुरुआती कार्ड से डेटा इनपुट ट्रांसफ़र करने के लिए, actionParameters के साथ button विजेट बनाया जा सकता है. इसमें विजेट का name और उपयोगकर्ता की डाली गई वैल्यू शामिल होती है, जैसा कि यहां दिए गए उदाहरण में दिखाया गया है:

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "submitForm",
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

यहां WIDGET_NAME, विजेट का name है और USER_INPUT_VALUE वह वैल्यू है जो उपयोगकर्ता डालता है. उदाहरण के लिए, किसी व्यक्ति का नाम इकट्ठा करने वाले टेक्स्ट इनपुट के लिए, विजेट का नाम contactName और उदाहरण के तौर पर दी गई वैल्यू Kai O है.

जब कोई उपयोगकर्ता बटन पर क्लिक करता है, तो आपके Chat ऐप्लिकेशन को एक इवेंट ऑब्जेक्ट मिलता है. इससे आपको डेटा मिल सकता है.

फ़ॉर्म सबमिशन का जवाब देना

कार्ड मैसेज या डायलॉग से डेटा मिलने के बाद, Chat ऐप्लिकेशन जवाब देता है. इसमें, डेटा मिलने की पुष्टि की जाती है या गड़बड़ी का मैसेज दिया जाता है.

नीचे दिए गए उदाहरण में, Chat ऐप्लिकेशन इस बात की पुष्टि करने के लिए एक मैसेज भेजता है कि उसे कार्ड मैसेज से सबमिट किया गया फ़ॉर्म मिल गया है.

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  const chatMessage = chatEvent.messagePayload.message;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle CARD_CLICKED events
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openDialog":
            return res.send(openDialog());
        case "openNextCard":
            return res.send(openNextCard(req.body));
        case "submitForm":
            return res.send(submitForm(req.body));
    }
  }
};

/**
 * Submits information from a dialog or card message.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

Apps Script 

/**
 * Sends private text message that confirms submission.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} a message response that posts a private message.
 */
function submitForm(event) {
  const chatUser = event.chat.user;
  const contactName = event.commonEventObject.parameters["contactName"];

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    privateMessageViewer: chatUser,
    text: "✅ " + contactName + " has been added to your contacts."
  }}}}};
}

किसी डायलॉग को प्रोसेस और बंद करने के लिए, आपको एक ऐसा RenderActions ऑब्जेक्ट दिखाना होगा जिससे यह पता चलता हो कि आपको पुष्टि करने वाला मैसेज भेजना है, ओरिजनल मैसेज या कार्ड को अपडेट करना है या सिर्फ़ डायलॉग बॉक्स को बंद करना है. इसके लिए, डायलॉग बॉक्स बंद करना लेख पढ़ें.

समस्या हल करें

जब Google Chat ऐप्लिकेशन या कार्ड में कोई गड़बड़ी होती है, तो Chat इंटरफ़ेस पर "कोई गड़बड़ी हुई" मैसेज दिखता है. या "आपका अनुरोध प्रोसेस नहीं किया जा सका." कभी-कभी Chat के यूज़र इंटरफ़ेस (यूआई) पर, गड़बड़ी का कोई मैसेज नहीं दिखता. हालांकि, Chat ऐप्लिकेशन या कार्ड से कोई अनचाहा नतीजा मिल सकता है. उदाहरण के लिए, हो सकता है कि कार्ड का मैसेज न दिखे.

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