איסוף ועיבוד מידע ממשתמשים ב-Google Chat

במדריך הזה מוסבר איך אפליקציות ל-Google Chat יכולות לאסוף ולעבד מידע ממשתמשים באמצעות יצירת קלט של טפסים בממשקים שמבוססים על כרטיסים.

תיבת דו-שיח עם מגוון ווידג'טים שונים.
איור 1: אפליקציית Chat לדוגמה שפותחת תיבת דו-שיח לאיסוף פרטים ליצירת קשר.

האפליקציות ל-Chat יכולות לבקש מהמשתמשים מידע כדי לבצע פעולות ב-Chat או מחוץ לו, כולל בדרכים הבאות:

  • קובעים את ההגדרות. לדוגמה, כדי לאפשר למשתמשים להתאים אישית את הגדרות ההתראות או להגדיר ולהוסיף את האפליקציה ל-Chat למרחב אחד או יותר.
  • ליצור או לעדכן מידע באפליקציות אחרות של Google Workspace. לדוגמה, לאפשר למשתמשים ליצור אירוע ביומן Google.
  • לאפשר למשתמשים לגשת למשאבים באפליקציות או בשירותי אינטרנט אחרים ולעדכן אותם. לדוגמה, אפליקציה ל-Chat יכולה לעזור למשתמשים לעדכן את הסטטוס של כרטיס תמיכה ישירות ממרחב ב-Chat.

דרישות מוקדמות

HTTP

אפליקציה ל-Google Chat שמקבלת אינטראקציות של משתמשים ומגיבה להן. כדי ליצור פונקציה כזו, צריך להשלים את המדריך למתחילים בנושא HTTP.

Apps Script

אפליקציה ל-Google Chat שמקבלת אינטראקציות של משתמשים ומגיבה להן. כדי ליצור פרויקט, מבצעים את השלבים במדריך למתחילים של Apps Script.

יצירת טפסים באמצעות כרטיסים

כדי לאסוף מידע, אפליקציות ל-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",
            "dataSourceConfigs": [
              {
                "platformDataSource": {
                  "commonDataSource": "USER"
                },
                "minCharactersTrigger": 1
              }
            ]
          }
        }
      ]
    }
  ]
}

אכלוס פריטים ממקור נתונים חיצוני

תפריטים נפתחים יכולים גם לאכלס פריטים ממקור נתונים חיצוני או של צד שלישי. כדי להשתמש במקור נתונים חיצוני, מציינים את השדה remoteDataSource בתוך אובייקט DataSourceConfig שמכיל את הפונקציה ששולחת שאילתות ומחזירה פריטים ממקור הנתונים.

כדי לצמצם את הבקשות למקור נתונים חיצוני, אתם יכולים לכלול פריטים מוצעים שמופיעים בתפריט הנפתח לפני שהמשתמשים מקלידים בתפריט. כדי לאכלס פריטים מוצעים ממקור נתונים חיצוני, צריך לציין אובייקטים סטטיים מסוג SelectionItem.

הקוד הבא מציג תפריט נפתח ששולח שאילתה לפריטים ממקור נתונים חיצוני ומאכלס אותם:

JSON

{
  "sections": [
    {
      "header": "Section Header",
      "widgets": [
        {
          "selectionInput": {
            "name": "crm_leads",
            "type": "DROPDOWN",
            "label": "Select CRM Lead",
            "dataSourceConfigs": [
              {
                "remoteDataSource": {
                  "function": "getCrmLeads"
                },
                "minCharactersTrigger": 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

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 של המטען הייעודי (payload) של האירוע, האובייקט formInputs מכיל את הערכים שהמשתמש מזין.

אפשר לאחזר את הערכים מהאובייקט event.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

אחרי שהאפליקציה ל-Chat מקבלת את הנתונים, היא יכולה:

הצעת פריטים לבחירה

אם הכרטיס מכיל תפריט לבחירת כמה אפשרויות או תפריט נפתח שמאכלס פריטים ממקור נתונים חיצוני, אפליקציית Chat יכולה להציע פריטים על סמך מה שהמשתמשים מקלידים בתפריט. לדוגמה, אם משתמש מתחיל להקליד Atl בתפריט שמאכלס ערים בארצות הברית, האפליקציה ל-Chat יכולה להציע באופן אוטומטי את Atlanta לפני שהמשתמש מסיים להקליד. אפליקציית Chat יכולה להציע עד 100 פריטים.

כדי להציע ולאכלס באופן דינמי פריטים בשדה קלט לבחירה, הווידג'ט 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

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 בנקודת הקצה (endpoint) של 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 בנקודת הקצה (endpoint) של HTTP שמטפלת בלחיצות על הכפתורים.

Java

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 בנקודת הקצה (endpoint) של 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 שולחת הודעת טקסט כדי לאשר שהיא קיבלה בהצלחה טופס שנשלח מהודעה עם כרטיס.

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

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.

אינטראקציות בתיבת הדו-שיח מחזירות את השגיאה "שגיאה לא מזוהה מפעילה את התוסף"

כשמקיימים אינטראקציה עם תיבת דו-שיח, אם מופיעים יומני שגיאות עם ההודעה "שגיאה לא מזוהה בהפעלת התוסף" וקוד 13, בדרך כלל זה מצביע על שגיאה פנימית או על כך שנקודת הקצה ל-HTTP של אפליקציית הצ'אט לא הצליחה לעבד את הבקשה או להחזיר תשובה תקינה.

כדי לפתור את השגיאה:

  • בודקים אם יש ביומנים של נקודת הקצה ב-HTTP קריסות או חריגות שלא טופלו.
  • מוודאים שנקודת הקצה מגיבה לבקשות תוך 30 שניות. אם לוקח יותר מ-30 שניות להפעיל את נקודת הקצה, אפליקציית Chat לא יכולה לעבד את התשובה והאינטראקציה נכשלת. למידע נוסף, ראו מגבלות קצב ושיטות מומלצות.
  • מוודאים שנקודת הקצה (endpoint) מחזירה תשובה תקינה. כששולחים תיבת דו-שיח, נקודת הקצה צריכה להחזיר אובייקט RenderActions בפורמט JSON תקין. אם התשובה לא תקינה או לא מכילה את השדות הנדרשים, יכול להיות שהאינטראקציה עם תיבת הדו-שיח תיכשל.

כשמוחזרת שגיאה מאפליקציה ל-Google Chat או מכרטיס, בממשק של Chat מופיעה ההודעה "משהו השתבש". או "לא ניתן לעבד את הבקשה שלך". לפעמים לא מופיעה הודעת שגיאה בממשק המשתמש של Chat, אבל אפליקציית Chat או הכרטיס מניבים תוצאה לא צפויה. לדוגמה, יכול להיות שהודעה בכרטיס לא תופיע.

יכול להיות שלא תופיע הודעת שגיאה בממשק המשתמש של Chat, אבל אם הפעלתם את רישום השגיאות ביומן באפליקציות ל-Chat, תוכלו להיעזר בהודעות השגיאה המפורטות ובנתונים ביומן כדי לתקן את השגיאות. כדי לקבל עזרה בהצגה, בניפוי באגים ובתיקון שגיאות, אפשר לעיין במאמר פתרון בעיות ותיקון שגיאות ב-Google Chat.

אפליקציות ל-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

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 שמכיל מידע על האינטראקציה. המטען הייעודי (payload) של אירועי אינטראקציה מסוג 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. המטען הייעודי (payload) של אירוע האינטראקציה מכיל אובייקט 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

העברת נתונים לכרטיס אחר

כדי להעביר את הקלט של הנתונים מהכרטיס הראשוני באפליקציה ל-Chat שהיא לא תוסף, יוצרים את הווידג'ט 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

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

כשמשתמש לוחץ על הכפתור, אפליקציית הצ'אט שהיא לא תוסף מקבלת אירוע אינטראקציה מסוג 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

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 שמציין אם רוצים לשלוח הודעת אישור, לעדכן את ההודעה או הכרטיס המקוריים או פשוט לסגור את תיבת הדו-שיח. איך סוגרים תיבת דו-שיח