اطلاعات کاربران چت گوگل را جمع آوری و پردازش کنید

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

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

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

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

پیش‌نیازها

اچ‌تی‌پی

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

اسکریپت برنامه‌ها

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

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

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

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

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

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

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

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

برای مثال‌های بیشتر از ویجت‌های تعاملی که می‌توانید برای جمع‌آوری اطلاعات استفاده کنید، به بخش «طراحی کارت یا کادر محاوره‌ای تعاملی» در مستندات Google Chat API مراجعه کنید.

اضافه کردن منوی چندگزینه‌ای

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

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

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

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

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

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

جی‌سون

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

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

جی‌سون

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

پر کردن آیتم‌ها از یک منبع داده خارجی

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

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

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

جی‌سون

{
  "selectionInput": {
    "name": "contacts",
    "type": "MULTI_SELECT",
    "label": "Selected contacts",
    "multiSelectMaxSelectedItems": 3,
    "multiSelectMinQueryLength": 1,
    "externalDataSource": { "function": "FUNCTION" },
    // Suggested items loaded by default.
    // The list is static here but it could be dynamic.
    "items": [FUNCTION]
  }
}

FUNCTION با آدرس HTTP URL یا نام تابع Apps Script که از پایگاه داده خارجی پرس و جو می‌کند، جایگزین کنید. برای مشاهده مثال کاملی که نحوه بازگرداندن موارد پیشنهادی را نشان می‌دهد، به بخش «پیشنهاد موارد چندگزینه‌ای» مراجعه کنید.

دریافت داده‌ها از ویجت‌های تعاملی

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

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

در زیر بخشی از یک شیء رویداد را نشان می‌دهد که در آن کاربر مقادیری را برای هر ویجت وارد کرده است:

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

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

ابزارک ورودی فرم نوع داده ورودی مقدار ورودی از شیء رویداد مقدار مثال
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

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

پیشنهاد موارد چندگزینه‌ای

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

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

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

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

نود جی اس

گره/چت/انتخاب-ورودی/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 که منبع داده خارجی را جستجو می‌کند، جایگزین کنید.

پایتون

پایتون/چت/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/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
  };
}

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

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

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

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

نود جی اس

{
  "buttonList": { "buttons": [{
    "text": "Submit",
    "onClick": { "action": {
      "function": "FUNCTION_URL", // Must be an `https` endpoint.
      "parameters": [
        {
          "key": "WIDGET_NAME",
          "value": "USER_INPUT_VALUE"
        },
        // Can specify multiple parameters
      ]
    }}
  }]}
}

اسکریپت برنامه‌ها

{
  "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 است.

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

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

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

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

نود جی اس

/**
 * 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 payloads in the event object
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(chatMessage, chatEvent.user));
  // Handle button clicks on the card
  } 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."
  }}}}};
}

اسکریپت برنامه‌ها

/**
 * 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 برمی‌گردانید که مشخص می‌کند آیا می‌خواهید یک پیام تأیید ارسال کنید، پیام یا کارت اصلی را به‌روزرسانی کنید یا فقط کادر محاوره‌ای را ببندید. برای مراحل، به بستن کادر محاوره‌ای مراجعه کنید.

عیب‌یابی

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

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