جمع‌آوری و پردازش اطلاعات کاربران Google Chat

این راهنما توضیح می‌دهد که برنامه‌های Google Chat چگونه می‌توانند با ساختن ورودی‌های فرم در میاناهای کارت‌محور، اطلاعات کاربران را جمع‌آوری و پردازش کنند.

کادر گفتگویی که ویجت‌های مختلفی را نمایش می‌دهد.
شکل ۱: A نمونه برنامه Chat که کادر گفتگویی را برای جمع‌آوری اطلاعات تماس باز می‌کند.

برنامه‌های Chat برای انجام کنش‌ها در داخل یا خارج از Chat، ازجمله به روش‌های زیر، از کاربران درخواست اطلاعات می‌کنند:

  • پیکربندی تنظیمات. برای مثال، برای اینکه کاربران بتوانند تنظیمات اعلان را سفارشی‌سازی کنند یا برنامه Chat را در یک یا چند فضا پیکربندی و اضافه کنند.
  • ایجاد یا به‌روزرسانی اطلاعات در سایر برنامه‌های Google Workspace. برای مثال، به کاربران اجازه دهید رویداد «تقویم Google» ایجاد کنند.
  • به کاربران اجازه می‌دهد به منابع در برنامه‌ها یا خدمات وب دیگر دسترسی داشته باشند و آن‌ها را به‌روز کنند. برای مثال، برنامه Chat می‌تواند به کاربران کمک کند وضعیت درخواست پشتیبانی را مستقیماً از فضای Chat به‌روز کنند.

پیش‌نیازها

HTTP

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن آن، شروع سریع HTTP را تکمیل کنید.

Apps Script

برنامه Google Chat که تعاملات کاربر را دریافت و به آن‌ها پاسخ می‌دهد. برای ساختن یکی از آن‌ها، راه‌اندازی سریع Apps Script را تکمیل کنید.

ساختن فرم بااستفاده از کارت‌ها

برنامه‌های Chat برای جمع‌آوری اطلاعات، فرم‌ها و ورودی‌های آن‌ها را طراحی می‌کنند و آن‌ها را در کارت‌ها می‌سازند. برای نمایش کارت‌ها به کاربران، برنامه‌های Chat می‌توانند از میاناهای Chat زیر استفاده کنند:

  • پیام‌هایی که حاوی یک یا چند کارت هستند.
  • صفحه‌های اصلی، که کارتی است که از برگه صفحه اصلی در پیام‌های مستقیم با برنامه Chat ظاهر می‌شود.
  • کادرهای گفتگو، که کارت‌هایی هستند که در پنجره جدیدی از پیام‌ها و صفحه‌های اصلی باز می‌شوند.

برنامه‌های گپ می‌توانند کارت‌ها را بااستفاده از ابزاره‌های زیر بسازند:

  • ابزاره‌های درونداد فرم که از کاربران اطلاعات درخواست می‌کنند. به‌صورت اختیاری، می‌توانید به ابزارک‌های ورودی فرم اعتبارسنجی اضافه کنید تا مطمئن شوید کاربران اطلاعات را به‌درستی وارد و قالب‌بندی می‌کنند. برنامه‌های Chat می‌توانند از ابزارک‌های ورودی فرم زیر استفاده کنند:

  • ابزارک دکمه تا کاربران بتوانند مقادیر واردشده در کارت را ارسال کنند. پس‌از اینکه کاربر روی دکمه کلیک کرد، برنامه Chat می‌تواند اطلاعاتی را که دریافت می‌کند پردازش کند.

در مثال زیر، کارتی اطلاعات تماس را بااستفاده از ورودی نوشتار، انتخابگر تاریخ و زمان، و ورودی انتخاب جمع‌آوری می‌کند:

برای نمونه‌های بیشتر از ابزارک‌های تعاملی که می‌توانید برای جمع‌آوری اطلاعات استفاده کنید، به طراحی کارت یا گفتگوی تعاملی مراجعه کنید.

افزودن منوِ کرکره‌ای

برای سفارشی‌سازی کردن موارد انتخاب یا اجازه دادن به کاربران برای انتخاب یک مورد از منبع داده پویا، برنامه‌های Chat می‌توانند از منوهای کرکره‌ای استفاده کنند که نوعی SelectionInput ابزارک است. برای مثال، کارت زیر منو کرکره‌ای را نمایش می‌دهد که در آن کاربران می‌توانند به‌صورت پویا از فهرست مخاطبین انتخاب کنند:

می‌توانید موارد را برای منو کرکره‌ای از منابع داده زیر پر کنید:

پر کردن موارد از منبع داده Google Workspace

برای پر کردن موارد از منابع داده Google Workspace، مثل کاربران Google Workspace، فیلد platformDataSource را در DataSourceConfig شیء مشخص کنید. برخلاف دیگر انواع ورودی انتخاب، شما SelectionItem اشیا را حذف می‌کنید، زیرا این موارد انتخاب به‌صورت پویا از Google Workspace منبع‌یابی می‌شوند.

کد زیر منو کرکره‌ای کاربران Google Workspace را نشان می‌دهد:

(قالب) JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "contacts",
            "type": "DROPDOWN",
            "label": "Select contact from organization",
            "data_source_configs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "min_characters_trigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

پر کردن موارد از منبع داده خارجی

منوهای کرکره‌ای همچنین می‌توانند موارد را از منبع داده طرف سوم یا خارجی پر کنند. برای استفاده از منبع داده خارجی، remoteDataSource فیلد را در DataSourceConfig شیئی که حاوی تابعی است که از منبع داده پُرسمان می‌کند و موارد را برمی‌گرداند مشخص می‌کنید.

برای کاهش درخواست‌ها به منبع داده خارجی، می‌توانید موارد پیشنهادی را که قبل‌از تایپ کردن کاربران در منو در منو کرکره‌ای نمایش داده می‌شود اضافه کنید. برای پر کردن موارد پیشنهادی از منبع داده خارجی، اشیای SelectionItem ایستا را مشخص کنید.

کد زیر منو کرکره‌ای را نشان می‌دهد که موارد را از منبع داده خارجی پُرسمان و تکمیل می‌کند:

(قالب) JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "data_source_configs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "min_characters_trigger": 2
              }
            ],
            "items": [
              {
                "text": "Suggested Lead 1",
                "value": "lead-1"
              }
            ]
          }
        }
      ]
    }
  ]
}

برای دیدن مثال کاملی که نشان می‌دهد چگونه موارد پیشنهادی را برگردانید، بخش پیشنهاد دادن موارد انتخابی را ببینید.

افزودن منو چندانتخابی

برای سفارشی‌سازی کردن موارد انتخابی یا اجازه دادن به کاربران برای انتخاب موارد از منبع داده پویا، برنامه‌های Chat می‌توانند از منوهای چندانتخابی استفاده کنند که نوعی ابزارک SelectionInput است. برای مثال، کارت زیر منو چندانتخابی را نمایش می‌دهد که در آن کاربران می‌توانند به‌صورت پویا از فهرست مخاطبین انتخاب کنند:

می‌توانید موارد را برای منو چندانتخابی از منابع داده زیر تکمیل کنید:

  • داده‌های Google Workspace، که شامل کاربران یا فضاهای Chat می‌شود که کاربر عضو آن‌ها است. منو فقط موارد را از سازمان Google Workspace یکسان تکمیل می‌کند.
  • منابع داده خارجی، مانند پایگاه داده رابطه‌ای. برای مثال، می‌توانید از منوهای چندانتخابی استفاده کنید تا به کاربر کمک کنید از فهرست مشتریان بالقوه فروش در سیستم مدیریت ارتباط با مشتری (CRM) انتخاب کند.

پر کردن موارد از منبع داده Google Workspace

برای استفاده از منابع داده Google Workspace، platformDataSource فیلد را در ابزارک SelectionInput مشخص کنید. برخلاف دیگر انواع ورودی انتخاب، شما SelectionItem اشیا را حذف می‌کنید، زیرا این موارد انتخاب به‌صورت پویا از Google Workspace منبع‌یابی می‌شوند.

کد زیر منو چندانتخابی کاربران Google Workspace را نشان می‌دهد. برای پر کردن کاربران، ورودی انتخاب commonDataSource را روی USER تنظیم می‌کند:

(قالب) JSON

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 5,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "commonDataSource": "USER"
    }
  }
}

کد زیر منو چندانتخابی فضاهای Chat را نشان می‌دهد. برای پر کردن فضاها، ورودی انتخاب فیلد hostAppDataSource را مشخص می‌کند. منو انتخاب چندگانه همچنین defaultToCurrentSpace را روی true تنظیم می‌کند، که باعث می‌شود فضای کنونی به‌عنوان انتخاب پیش‌فرض در منو تعیین شود:

(قالب) JSON

{
  "selectionInput": {
    "name": "spaces",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "platformDataSource": {
      "hostAppDataSource": {
        "chatDataSource": {
          "spaceDataSource": {
            "defaultToCurrentSpace": true
          }
        }
      }
    }
  }
}

پر کردن موارد از منبع داده خارجی

منوهای چندانتخابی همچنین می‌توانند موارد را از منبع داده طرف سوم یا خارجی پر کنند. برای استفاده از منبع داده خارجی، فیلد externalDataSource را در ابزارک SelectionInput که حاوی تابعی است که موارد را از منبع داده پُرسمان و برمی‌گرداند مشخص می‌کنید.

برای کاهش درخواست‌ها به منبع داده خارجی، می‌توانید موارد پیشنهادی را که در منو چندانتخابی ظاهر می‌شوند قبل‌از اینکه کاربران در منو تایپ کنند اضافه کنید. برای مثال، می‌توانید مخاطبینی را که اخیراً برای کاربر جستجو شده‌اند تکمیل کنید. برای پر کردن موارد پیشنهادی از منبع داده خارجی، اشیای SelectionItem ایستا را مشخص کنید.

نمونه کد زیر منو چندانتخابی را نشان می‌دهد که موارد را از منبع داده خارجی پُرسمان و تکمیل می‌کند:

Node.js

node/chat/selection-input/index.js
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: FUNCTION_URL },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

Python

python/chat/selection-input/main.py
'selectionInput': {
  'name': "contacts",
  'type': "MULTI_SELECT",
  'label': "Selected contacts",
  'multiSelectMaxSelectedItems': 3,
  'multiSelectMinQueryLength': 1,
  'externalDataSource': { 'function': FUNCTION_URL },
  # Suggested items loaded by default.
  # The list is static here but it could be dynamic.
  'items': [get_suggested_contact("3")]
}

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

جاوا

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
.setSelectionInput(new GoogleAppsCardV1SelectionInput()
  .setName("contacts")
  .setType("MULTI_SELECT")
  .setLabel("Selected contacts")
  .setMultiSelectMaxSelectedItems(3)
  .setMultiSelectMinQueryLength(1)
  .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  .setItems(List.of(getSuggestedContact("3")))))))))));

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/chat/selection-input/selection-input.gs
selectionInput: {
  name: "contacts",
  type: "MULTI_SELECT",
  label: "Selected contacts",
  multiSelectMaxSelectedItems: 3,
  multiSelectMinQueryLength: 1,
  externalDataSource: { function: "queryContacts" },
  // Suggested items loaded by default.
  // The list is static here but it could be dynamic.
  items: [getSuggestedContact("3")]
}

برای دیدن مثال کاملی که نشان می‌دهد چگونه موارد پیشنهادی را برگردانید، بخش پیشنهاد دادن موارد انتخابی را ببینید.

دریافت داده از ابزارک‌های تعاملی

هرگاه کاربران روی دکمه‌ای کلیک کنند، کنش برنامه‌های Chat آن با اطلاعات مربوط به تعامل راه‌اندازی می‌شود. در commonEventObject پایه‌بار رویداد، شیء formInputs حاوی هر مقداری است که کاربر وارد می‌کند.

می‌توانید مقادیر را از شیء event.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 داده‌ها را دریافت کرد، می‌تواند هریک از موارد زیر را انجام دهد:

پیشنهاد دادن موارد انتخاب

اگر کارتی حاوی منو چندانتخابی یا منو کرکره‌ای باشد که موارد را از منبع داده خارجی تکمیل می‌کند، برنامه Chat می‌تواند براساس آنچه کاربران در منو تایپ می‌کنند، موارد پیشنهادی برگرداند. برای مثال، اگر کاربری برای منویی که شهرهای ایالات متحده را فهرست می‌کند شروع به تایپ کردن Atl کند، برنامه Chat شما می‌تواند قبل‌از اینکه کاربر تایپ کردن را تمام کند، Atlanta را به‌طور خودکار پیشنهاد دهد. برنامه Chat می‌تواند حداکثر ۱۰۰ مورد را پیشنهاد دهد.

برای پیشنهاد دادن و به‌طور پویا پر کردن موارد در ورودی انتخاب، ابزارک SelectionInput در کارت باید تابعی را مشخص کند که منبع داده خارجی را پُرسمان می‌کند. برای منوهای چندانتخابی، externalDataSource فیلد را مشخص می‌کنید. برای منوهای کرکره‌ای، remoteDataSource فیلد را در DataSourceConfig شیء مشخص می‌کنید.

همچنین می‌توانید تعداد نویسه‌هایی را که کاربر قبل‌از اینکه منو پیشنهادها را برگرداند تایپ می‌کند پیکربندی کنید. برای منوهای چندانتخابی، فیلد multiSelectMinQueryLength را تنظیم کنید. برای منوهای کرکره‌ای، فیلد min_characters_trigger را در DataSourceConfig تنظیم کنید.

برای برگرداندن موارد پیشنهادی، تابع باید کارهای زیر را انجام دهد:

  1. یک شیء رویداد را مدیریت کنید، که برنامه Chat وقتی کاربران در منو تایپ می‌کنند دریافت می‌کند.
  2. از شیء رویداد، مقداری را که کاربر تایپ می‌کند دریافت کنید، که در فیلد event.commonEventObject.parameters["autocomplete_widget_query"] نشان داده می‌شود.
  3. بااستفاده از مقدار ورودی کاربر، منبع داده را پُرسمان کنید تا یک یا چند SelectionItems برای پیشنهاد به کاربر دریافت کنید.
  4. با برگرداندن کنش RenderActions با modifyCard شیء، موارد پیشنهادی را برگردانید.

نمونه کد زیر نشان می‌دهد که چگونه یک برنامه Chat به‌صورت پویا مواردی را در منو چندانتخابی در کارت پیشنهاد می‌دهد. وقتی کاربر در منو تایپ می‌کند، تابع یا نقطه پایانی که در فیلد externalDataSource ابزارک ارائه شده است از منبع داده خارجی پُرسمان می‌کند و مواردی را پیشنهاد می‌دهد که کاربر می‌تواند انتخاب کند.

Node.js

node/chat/selection-input/index.js
/**
 * Web app that responds to events sent from a Google Chat space.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
app.post('/', async (req, res) => {
  // Stores the Google Chat event
  const chatEvent = req.body.chat;

  // Handle user interaction with multiselect.
  if(chatEvent.widgetUpdatedPayload) {
    return res.json(queryContacts(req.body));
  }

  // Replies with a card that contains the multiselect menu.
  return res.json({ hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: FUNCTION_URL },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}});
});

/**
 * Get contact suggestions based on text typed by users.
 *
 * @param {Object} event the event object that contains the user's query
 * @return {Object} suggestions
 */
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
 * Generate a suggested contact given an ID.
 *
 * @param {String} id The ID of the contact to return.
 * @return {Object} The contact formatted as a selection item in the menu.
 */
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

Python

python/chat/selection-input/main.py
@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: The response
  """
  # Stores the Google Chat event
  chatEvent = request.get_json().get('chat')

  # Handle user interaction with multiselect.
  if chatEvent.get('widgetUpdatedPayload') is not None:
    return json.jsonify(query_contacts(request.get_json()))

  # Replies with a card that contains the multiselect menu.
  return json.jsonify({ 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': {
    'message': { 'cardsV2': [{
      'cardId': "contactSelector",
      'card': { 'sections':[{ 'widgets': [{
        'selectionInput': {
          'name': "contacts",
          'type': "MULTI_SELECT",
          'label': "Selected contacts",
          'multiSelectMaxSelectedItems': 3,
          'multiSelectMinQueryLength': 1,
          'externalDataSource': { 'function': FUNCTION_URL },
          # Suggested items loaded by default.
          # The list is static here but it could be dynamic.
          'items': [get_suggested_contact("3")]
        }
      }]}]}
    }]}
  }}}})


def query_contacts(event: dict) -> dict:
  """Get contact suggestions based on text typed by users.

  Args:
      event (Mapping[str, Any]): The event object that contains the user's query

  Returns:
      Mapping[str, Any]: The response with contact suggestions.
  """
  query = event.get("commonEventObject").get("parameters").get("autocomplete_widget_query")
  return { 'action': { 'modifyOperations': [{ 'updateWidget': { 'selectionInputWidgetSuggestions': { 'suggestions': list(
    filter(lambda e: query is None or query in e["text"], [
      # The list is static here but it could be dynamic.
      get_suggested_contact("1"), get_suggested_contact("2"), get_suggested_contact("3"), get_suggested_contact("4"), get_suggested_contact("5")
    # Only return items based on the query from the user
    ])
  )}}}]}}


def get_suggested_contact(id: str) -> dict:
  """Generate a suggested contact given an ID.

  Args:
      id (str): The ID of the contact to return.

  Returns:
      Mapping[str, Any]: The contact formatted as a selection item in the menu.
  """
  return {
    'value': id,
    'startIconUri': "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    'text': "Contact " + id
  }

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

جاوا

java/chat/selection-input/src/main/java/com/google/chat/selectionInput/App.java
@SpringBootApplication
@RestController
// Web app that responds to events sent from a Google Chat space.
public class App {
  private static final String FUNCTION_URL = "your-function-url";

  public static void main(String[] args) {
    SpringApplication.run(App.class, args);
  }

  /**
   * Handle requests from Google Chat
   * 
   * @param event the event object sent by Google Chat
   * @return The response to be sent back to Google Chat
   */
  @PostMapping("/")
  @ResponseBody
  public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
    // Stores the Google Chat event
    JsonNode chatEvent = event.at("/chat");

    // Handle user interaction with multiselect.
    if (!chatEvent.at("/widgetUpdatedPayload").isEmpty()) {
      return queryContacts(event);
    }

    // Replies with a card that contains the multiselect menu.
    Message message = new Message().setCardsV2(List.of(new CardWithId()
      .setCardId("contactSelector")
      .setCard(new GoogleAppsCardV1Card()
        .setSections(List.of(new GoogleAppsCardV1Section().setWidgets(List.of(new GoogleAppsCardV1Widget()
          .setSelectionInput(new GoogleAppsCardV1SelectionInput()
            .setName("contacts")
            .setType("MULTI_SELECT")
            .setLabel("Selected contacts")
            .setMultiSelectMaxSelectedItems(3)
            .setMultiSelectMinQueryLength(1)
            .setExternalDataSource(new GoogleAppsCardV1Action().setFunction(FUNCTION_URL))
            // Suggested items loaded by default.
            // The list is static here but it could be dynamic.
            .setItems(List.of(getSuggestedContact("3")))))))))));

    return new GenericJson() {{
      put("hostAppDataAction", new GenericJson() {{
        put("chatDataAction", new GenericJson() {{
          put("createMessageAction", new GenericJson() {{
            put("message", message);
          }});
        }});
      }});
    }};
  }

  /**
   * Get contact suggestions based on text typed by users.
   *
   * @param event the event object that contains the user's query.
   * @return The response with contact suggestions.
   */
  GenericJson queryContacts(JsonNode event) throws Exception {
    String query = event.at("/commonEventObject/parameters/autocomplete_widget_query").asText();
    List<GoogleAppsCardV1SelectionItem> suggestions = List.of(
      // The list is static here but it could be dynamic.
      getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
    // Only return items based on the query from the user
    ).stream().filter(e -> query == null || e.getText().indexOf(query) > -1).toList();

    return new GenericJson() {{
      put("action", new GenericJson() {{
        put("modifyOperations", List.of(new GenericJson() {{
          put("updateWidget", new GenericJson() {{
            put("selectionInputWidgetSuggestions", new GenericJson() {{
              put("suggestions", suggestions);
            }});
          }});
        }}));
      }});
    }};
  }

  /**
   * Generate a suggested contact given an ID.
   * 
   * @param id The ID of the contact to return.
   * @return The contact formatted as a selection item in the menu.
   */
  GoogleAppsCardV1SelectionItem getSuggestedContact(String id) {
    return new GoogleAppsCardV1SelectionItem()
      .setValue(id)
      .setStartIconUri("https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png")
      .setText("Contact " + id);
  }
}

FUNCTION_URL را با نقطه پایانی HTTP که منبع داده خارجی را پُرسمان می‌کند جایگزین کنید.

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/chat/selection-input/selection-input.gs
/**
* Responds to a Message trigger in Google Chat.
*
* @param {Object} event the event object from Google Chat
* @return {Object} Response from the Chat app.
*/
function onMessage(event) {
  // Replies with a card that contains the multiselect menu.
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    cardsV2: [{
      cardId: "contactSelector",
      card: { sections:[{ widgets: [{
        selectionInput: {
          name: "contacts",
          type: "MULTI_SELECT",
          label: "Selected contacts",
          multiSelectMaxSelectedItems: 3,
          multiSelectMinQueryLength: 1,
          externalDataSource: { function: "queryContacts" },
          // Suggested items loaded by default.
          // The list is static here but it could be dynamic.
          items: [getSuggestedContact("3")]
        }
      }]}]}
    }]
  }}}}};
}

/**
* Get contact suggestions based on text typed by users.
*
* @param {Object} event the event object that contains the user's query
* @return {Object} suggestions
*/
function queryContacts(event) {
  const query = event.commonEventObject.parameters["autocomplete_widget_query"];
  return { action: { modifyOperations: [{ updateWidget: { selectionInputWidgetSuggestions: { suggestions: [
    // The list is static here but it could be dynamic.
    getSuggestedContact("1"), getSuggestedContact("2"), getSuggestedContact("3"), getSuggestedContact("4"), getSuggestedContact("5")
  // Only return items based on the query from the user.
  ].filter(e => !query || e.text.includes(query)) }}}]}};
}

/**
* Generate a suggested contact given an ID.
*
* @param {String} id The ID of the contact to return.
* @return {Object} The contact formatted as a selection item in the menu.
*/
function getSuggestedContact(id) {
  return {
    value: id,
    startIconUri: "https://www.gstatic.com/images/branding/product/2x/contacts_48dp.png",
    text: "Contact " + id
  };
}

انتقال داده‌ها به کارتی دیگر

پس‌از اینکه کاربر اطلاعاتی را از کارت ارسال کرد، ممکن است لازم باشد کارت‌های دیگری را برای انجام هریک از موارد زیر برگردانید:

  • با ایجاد بخش‌های متمایز، به کاربران کمک کنید فرم‌های طولانی‌تر را تکمیل کنند.
  • به کاربران اجازه دهید اطلاعات کارت اولیه را پیش‌نمایش و تأیید کنند تا بتوانند پاسخ‌هایشان را قبل‌از ارسال کردن بررسی کنند.
  • بخش‌های باقی‌مانده فرم را به‌صورت پویا تکمیل کنید. برای مثال، برای ترغیب کاربران به ایجاد قرار، برنامه Chat می‌تواند کارت اولیه‌ای نمایش دهد که دلیل قرار را درخواست می‌کند، و سپس کارت دیگری را تکمیل کند که زمان‌های دردسترس را براساس نوع قرار ارائه می‌دهد.

برای انتقال ورودی داده از کارت اولیه، می‌توانید button ابزاره را با actionParameters بسازید که حاوی name ابزاره و مقداری است که کاربر وارد می‌کند، همان‌طور که در مثال زیر نشان داده شده است:

Node.js

node/chat/contact-form-app/index.js
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: FUNCTION_URL,
    parameters: [
      { key: "actionName", value: "submitDialog" },
      // Pass input values as parameters for last dialog step (submission)
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

‫FUNCTION_URL را با نقطه پایانی HTTP که کلیک‌های دکمه را مدیریت می‌کند جایگزین کنید.

Python

python/chat/contact-form-app/main.py
{ 'buttonList': { 'buttons': [{
  'text': "SUBMIT",
  'onClick': { 'action': {
    'function': FUNCTION_URL,
    'parameters': [
      { 'key': "actionName", 'value': "submitDialog" },
      # Pass input values as parameters for last dialog step (submission)
      { 'key': "contactName", 'value': name },
      { 'key': "contactBirthdate", 'value': birthdate },
      { 'key': "contactType", 'value': type }
    ]
  }}
}]}}

‫FUNCTION_URL را با نقطه پایانی HTTP که کلیک‌های دکمه را مدیریت می‌کند جایگزین کنید.

جاوا

java/chat/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(
  new GoogleAppsCardV1Button()
    .setText("SUBMIT")
    .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
      .setFunction(FUNCTION_URL)
      .setParameters(List.of(
        new GoogleAppsCardV1ActionParameter().setKey("actionName").setValue("submitDialog"),
        // Pass input values as parameters for last dialog step (submission)
        new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
        new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
        new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))))));

‫FUNCTION_URL را با نقطه پایانی HTTP که کلیک‌های دکمه را مدیریت می‌کند جایگزین کنید.

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/chat/contact-form-app/Code.gs
{ buttonList: { buttons: [{
  text: "SUBMIT",
  onClick: { action: {
    function: "submitDialog",
    // Pass input values as parameters for last dialog step (submission)
    parameters: [
      { key: "contactName", value: name },
      { key: "contactBirthdate", value: birthdate },
      { key: "contactType", value: type }
    ]
  }}
}]}}

وقتی کاربری روی دکمه کلیک می‌کند، برنامه Chat شما شیء رویدادی دریافت می‌کند که می‌توانید از آن داده دریافت کنید.

پاسخ دادن به ارسال فرم

پس‌از دریافت داده‌ها از پیام کارت یا کادر گفتگو، برنامه Chat با تأیید دریافت یا برگرداندن خطا پاسخ می‌دهد.

در مثال زیر، برنامه Chat پیامکی ارسال می‌کند تا تأیید کند که فرم ارسالی از پیام کارت را باموفقیت دریافت کرده است.

Node.js

node/chat/contact-form-app/index.js
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
}}}}};

Python

python/chat/contact-form-app/main.py
return { 'hostAppDataAction': { 'chatDataAction': { 'createMessageAction': { 'message': {
  'text': "✅ " + event.get('commonEventObject').get('parameters')["contactName"] + " has been added to your contacts."
}}}}}

جاوا

java/chat/contact-form-app/src/main/java/com/google/chat/contact/App.java
return new GenericJson() {{
  put("hostAppDataAction", new GenericJson() {{
    put("chatDataAction", new GenericJson() {{
      put("createMessageAction", new GenericJson() {{
        put("message", new Message()
          .setText( "✅ " + event.at("/commonEventObject/parameters/contactName").asText() +
                    " has been added to your contacts."));
      }});
    }});
  }});
}};

Apps Script

این مثال با برگرداندن JSON کارت، پیام کارت ارسال می‌کند. همچنین می‌توانید از خدمات کارت Apps Script استفاده کنید.

apps-script/chat/contact-form-app/Code.gs
return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
  text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
}}}}};

برای پردازش و بستن کادر گفتگو، RenderActions شیئی برمی‌گردانید که مشخص می‌کند آیا می‌خواهید پیام تأیید ارسال کنید، پیام یا کارت اصلی را به‌روز کنید، یا فقط کادر گفتگو را ببندید. برای اطلاع از مراحل، به بستن کادر گفتگو مراجعه کنید.

عیب‌یابی

این بخش مراحل عیب‌یابی را برای کدهای خطای خاص و رفتارهای زمان اجرا هنگام تعامل با چارگوش‌های گفتگو در Chat ارائه می‌دهد.

تعامل‌های کادر گفتگو خطای «خطای نامشخص که برافزا را فرا می‌خواند» را برمی‌گرداند

هنگام تعامل با یک چارگوش گفتگو، اگر گزارش‌های خطا با پیام «خطای نامشخصی هنگام فراخوانی برافزا رخ داد.» و کد ۱۳ را مشاهده کردید، معمولاً نشان‌دهنده خطای داخلی یا این است که نقطه پایانی HTTP برنامه Chat نتوانسته است درخواست را پردازش کند یا پاسخ معتبری برگرداند.

برای عیب‌یابی کردن این خطا:

  • گزارش‌های نقطه پایانی HTTP خود را ازنظر وجود هرگونه استثنا یا خرابی مدیریت‌نشده بررسی کنید.
  • تأیید کنید که نقطه پایانی شما ظرف ۳۰ ثانیه به درخواست‌ها پاسخ می‌دهد. اگر اجرای نقطه پایانی بیشتر از ۳۰ ثانیه طول بکشد، Chat نمی‌تواند پاسخ را پردازش کند و تعامل ناموفق خواهد بود. برای جزئیات، به محدودیت‌های نرخ و روال‌های مطلوب مراجعه کنید.
  • مطمئن شوید که نقطه پایانی‌تان پاسخ معتبری برمی‌گرداند. برای ارسال‌های کادر گفتگو، نقطه پایانی باید RenderActions هدف را در قالب JSON صحیح برگرداند. اگر پاسخ قالب نادرستی داشته باشد یا فیلدهای الزامی را نداشته باشد، تعامل با کادر گفتگو ممکن است ناموفق باشد.

وقتی برنامه یا کارت Google Chat خطایی برمی‌گرداند، میانای Chat پیامی را نشان می‌دهد که می‌گوید «مشکلی پیش آمد». یا «نمی‌توانیم درخواستتان را پردازش کنیم.» گاهی‌اوقات «میانای کاربری Chat» هیچ پیام خطایی نمایش نمی‌دهد، اما برنامه Chat یا کارت نتیجه غیرمنتظره‌ای تولید می‌کند؛ برای مثال، ممکن است پیام کارت ظاهر نشود.

اگرچه ممکن است پیام خطا در واسط کاربر Chat نمایش داده نشود، پیام‌های خطای توصیفی و داده‌های گزارش برای کمک به شما در رفع خطاها وقتی گزارش خطا برای برنامه‌های Chat روشن باشد دردسترس است. برای دریافت راهنمایی درباره مشاهده، اشکال‌زدایی، و رفع خطاها، عیب‌یابی و رفع خطاهای Google Chat را ببینید.

برنامه‌های گپی که برافزا نیستند: خواندن داده‌های فرم واردشده توسط کاربران در کارت‌ها

اسناد زیر برای برنامه‌های Chat که برافزاهای Google Workspace نیستند اعمال می‌شود. برای انتقال برنامه Chat که برافزا نیست، تبدیل برنامه Google Chat به برافزای Google Workspace را ببینید.

ساختن فرم بااستفاده از کارت‌ها

برای نمونه‌ای از برنامه Chat که برافزایی نیست و از فرم مخاطب با ورودی نوشتار، انتخابگر تاریخ و زمان، و ورودی انتخاب استفاده می‌کند، کد زیر را ببینید:

Node.js

node/contact-form-app/index.js
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

Python

python/contact-form-app/main.py
# The section of the contact card that contains the form input widgets. Used in a dialog and card message.
# To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": False
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": False
        }
      ]
    }
  }
]

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
// The section of the contact card that contains the form input widgets. Used in a dialog and card message.
// To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
final static private List<GoogleAppsCardV1Widget> CONTACT_FORM_WIDGETS = List.of(
  new GoogleAppsCardV1Widget().setTextInput(new GoogleAppsCardV1TextInput()
    .setName("contactName")
    .setLabel("First and last name")
    .setType("SINGLE_LINE")),
  new GoogleAppsCardV1Widget().setDateTimePicker(new GoogleAppsCardV1DateTimePicker()
    .setName("contactBirthdate")
    .setLabel("Birthdate")
    .setType("DATE_ONLY")),
  new GoogleAppsCardV1Widget().setSelectionInput(new GoogleAppsCardV1SelectionInput()
    .setName("contactType")
    .setLabel("Contact type")
    .setType("RADIO_BUTTON")
    .setItems(List.of(
      new GoogleAppsCardV1SelectionItem()
        .setText("Work")
        .setValue("Work")
        .setSelected(false),
      new GoogleAppsCardV1SelectionItem()
        .setText("Personal")
        .setValue("Personal")
        .setSelected(false)))));

Apps Script

apps-script/contact-form-app/contactForm.gs
/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];

دریافت داده از ابزارک‌های تعاملی

هرگاه کاربران روی دکمه‌ای کلیک کنند، برنامه‌های Chat که برافزا نیستند رویداد تعاملی دریافت می‌کنند که به مکان دکمه بستگی دارد:

  • اگر دکمه در پیام یا چارگوش گفتگویی باشد، برنامه‌های Chat که برافزا نیستند رویداد تعاملی CARD_CLICKED دریافت می‌کنند که حاوی اطلاعاتی درباره تعامل است. پایه‌بار رویدادهای تعامل CARD_CLICKED حاوی common.formInputs شیء (event.common.formInputs) با هر مقداری است که کاربر وارد می‌کند.

    می‌توانید مقادیر را از شیء common.formInputs.WIDGET_NAME بازیابی کنید، که در آن WIDGET_NAME فیلد name است که برای ابزاره مشخص کرده‌اید. مقادیر به‌عنوان نوع داده خاصی برای ابزارک برگردانده می‌شوند (به‌صورت شیء Inputs نشان داده می‌شوند).

    در زیر بخشی از رویداد تعامل CARD_CLICKED نشان داده شده است که در آن کاربر برای هر ابزارک مقادیری وارد کرده است:

    HTTP

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

    Apps Script

    {
      "type": "CARD_CLICKED",
      "common": { "formInputs": {
        "contactName": { "": { "stringInputs": {
          "value": ["Kai 0"]
        }}},
        "contactBirthdate": { "": { "dateInput": {
          "msSinceEpoch": 1000425600000
        }}},
          "contactType": { "": { "stringInputs": {
          "value": ["Personal"]
        }}}
      }}
    }
    
  • اگر دکمه در صفحه اصلی باشد، برنامه‌های Chat که برافزا نیستند SUBMIT_FORM رویداد تعاملی دریافت می‌کنند. بار تعامل رویداد حاوی commonEventObject.formInputs شیء (event.commonEventObject.formInputs) با هر مقداری است که کاربر وارد می‌کند.

    می‌توانید مقادیر را از شیء commonEventObject.formInputs.WIDGET_NAME بازیابی کنید، که در آن WIDGET_NAME فیلد name است که برای ابزاره مشخص کرده‌اید. مقادیر به‌عنوان نوع داده خاصی برای ابزارک برگردانده می‌شوند (به‌صورت شیء Inputs نشان داده می‌شوند).

    در زیر بخشی از رویداد تعامل SUBMIT_FORM نشان داده شده است که در آن کاربر برای هر ابزارک مقادیری وارد کرده است:

    HTTP

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

    Apps Script

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

برای دریافت داده‌ها، برنامه Chat که برافزا نیست رویداد تعامل را مدیریت می‌کند تا مقادیر واردشده توسط کاربران در ابزارک‌ها را دریافت کند. جدول زیر نحوه دریافت مقدار برای ابزارک ورودی فرم داده‌شده را نشان می‌دهد. برای هر ابزارک، جدول نوع داده‌ای را که ابزارک می‌پذیرد، محل ذخیره مقدار در رویداد تعامل، و مقدار نمونه را نشان می‌دهد.

ابزاره ورودی فرم نوع داده‌های ورودی مقدار ورودی از رویداد تعامل مقدار نمونه
textInput stringInputs event.common.formInputs.contactName.stringInputs.value[0] Kai O
selectionInput stringInputs برای دریافت اولین یا تنها مقدار، event.common.formInputs.contactType.stringInputs.value[0] Personal
dateTimePicker که فقط تاریخ می‌پذیرد. dateInput event.common.formInputs.contactBirthdate.dateInput.msSinceEpoch. 1000425600000

انتقال داده‌ها به کارتی دیگر

برای انتقال ورودی داده از کارت اولیه در برنامه «گپ» که برافزا نیست، ابزاره button را با actionParameters بسازید که حاوی name ابزاره و مقدار ورودی کاربر باشد، همان‌طور که در مثال زیر نشان داده شده است:

Node.js

node/contact-form-app/index.js
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

Python

python/contact-form-app/main.py
'buttonList': { 'buttons': [{
  'text': "Submit",
  'onClick': { 'action': {
    'function': "submitForm",
    'parameters': [{
      'key': "contactName", 'value': name }, {
      'key': "contactBirthdate", 'value': birthdate }, {
      'key': "contactType", 'value': type
    }]
  }}
}]}

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
new GoogleAppsCardV1Widget().setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
  .setText("Submit")
  .setOnClick(new GoogleAppsCardV1OnClick().setAction(new GoogleAppsCardV1Action()
    .setFunction("submitForm")
    .setParameters(List.of(
      new GoogleAppsCardV1ActionParameter().setKey("contactName").setValue(name),
      new GoogleAppsCardV1ActionParameter().setKey("contactBirthdate").setValue(birthdate),
      new GoogleAppsCardV1ActionParameter().setKey("contactType").setValue(type))))))))));

Apps Script

apps-script/contact-form-app/main.gs
buttonList: { buttons: [{
  text: "Submit",
  onClick: { action: {
    function: "submitForm",
    parameters: [{
      key: "contactName", value: name }, {
      key: "contactBirthdate", value: birthdate }, {
      key: "contactType", value: type
    }]
  }}
}]}

وقتی کاربر روی دکمه کلیک می‌کند، برنامه Chat که برافزا نیست یک رویداد تعامل CARD_CLICKED دریافت می‌کند که از آن می‌توانید داده دریافت کنید.

پاسخ دادن به ارسال فرم

در مثال زیر، برنامه Chat که برافزا نیست پیامکی ارسال می‌کند تا تأیید کند که فرم ارسال‌شده از کادر گفتگو یا پیام کارت را باموفقیت دریافت کرده است:

Node.js

node/contact-form-app/index.js
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

Python

python/contact-form-app/main.py
contact_name = event.get('common').get('parameters')["contactName"]
# Checks to make sure the user entered a contact name.
# If no name value detected, returns an error message.
error_message = "Don't forget to name your new contact!"
if contact_name == "" and "SUBMIT_DIALOG" == event.get('dialogEventType'):
  return { 'actionResponse': {
    'type': "DIALOG",
    'dialogAction': { 'actionStatus': {
      'statusCode': "INVALID_ARGUMENT",
      'userFacingMessage': error_message
    }}
  }}

جاوا

java/contact-form-app/src/main/java/com/google/chat/contact/App.java
String contactName = event.at("/common/parameters/contactName").asText();
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
String errorMessage = "Don't forget to name your new contact!";
if (contactName.isEmpty() && event.at("/dialogEventType") != null && "SUBMIT_DIALOG".equals(event.at("/dialogEventType").asText())) {
  return new Message().setActionResponse(new ActionResponse()
    .setType("DIALOG")
    .setDialogAction(new DialogAction().setActionStatus(new ActionStatus()
      .setStatusCode("INVALID_ARGUMENT")
      .setUserFacingMessage(errorMessage))));
}

Apps Script

apps-script/contact-form-app/main.gs
const contactName = event.common.parameters["contactName"];
// Checks to make sure the user entered a contact name.
// If no name value detected, returns an error message.
const errorMessage = "Don't forget to name your new contact!";
if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { actionStatus: {
      statusCode: "INVALID_ARGUMENT",
      userFacingMessage: errorMessage
    }}
  }};
}

برای پردازش و بستن کادر گفتگویی در برنامه Chat که برافزا نیست، شیء ActionResponse را برگردانید که مشخص می‌کند آیا می‌خواهید پیام تأییدی ارسال کنید، پیام یا کارت اصلی را به‌روزرسانی کنید، یا فقط کادر گفتگو را ببندید. برای اطلاع از مراحل، به بستن کادر گفتگو مراجعه کنید.