דף זה תורגם על ידי Cloud Translation API.

יצירת תיבת דו-שיח אינטראקטיבית

בדף הזה נסביר איך אפליקציית Google Chat יכולה לפתוח תיבת דו-שיח כדי להציג ממשקי משתמש (UI) ולהגיב למשתמשים.

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

Dialogs הם ממשקים מבוססי כרטיסים בחלון שנפתחים מהודעה או ממרחבים משותפים ב-Chat. תיבת הדו-שיח והתוכן שלה גלויים רק למשתמש שפתח אותה.

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

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

HTTP

תוסף ל-Google Workspace שמרחיב את Google Chat. כדי ליצור שירות כזה, תוכלו להיעזר במדריך למתחילים בנושא HTTP.

Apps Script

תוסף ל-Google Workspace שמרחיב את Google Chat. כדי ליצור אחד, תוכלו להיעזר במדריך למתחילים ב-Apps Script.

פתיחת תיבת דו-שיח

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

**איור 1**: אפליקציית Chat שפותחת תיבת דו-שיח לאיסוף פרטי התקשרות.

בקטע הזה נסביר איך להשיב ולהגדיר שיחה:

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

הפעלת בקשה לתיבת דו-שיח

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

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

תגובה לפקודה כדי להפעיל את הבקשה מפקודה, צריך לסמן את התיבה Opens a dialog בזמן הגדרת הפקודה.
לענות ללחיצה על לחצן בהודעה, כחלק מכרטיס או בתחתית ההודעה. כדי להפעיל את הבקשה באמצעות לחצן בהודעה, מגדירים את הפעולה onClick של הלחצן על ידי הגדרת interaction ל-OPEN_DIALOG.

כפתור שמפעיל תיבת דו-שיח — **איור 2**: אפליקציית Chat שולחת הודעה שמבקשת מהמשתמשים להשתמש בפקודה `/addContact`.
ההודעה כוללת גם לחצן שהמשתמשים יכולים ללחוץ עליו כדי להפעיל את הפקודה.

הקוד הבא בפורמט JSON מראה איך להפעיל בקשת תיבת דו-שיח מלחצן בהודעה בכרטיס. כדי לפתוח את תיבת הדו-שיח, מגדירים את השדה onClick.action.interaction של הלחצן לערך OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "ACTION_FUNCTION",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

כאשר BUTTON_TEXT הוא הטקסט שמוצג בכפתור ו-ACTION_FUNCTION היא הפונקציה שפועלת כדי לפתוח את תיבת הדו-שיח הראשונית.

פתיחת תיבת הדו-שיח הראשונית

כשמשתמש מפעיל בקשה לתיבת דו-שיח, אפליקציית Chat מקבלת אובייקט אירוע עם עומס נתונים שמציין שאובייקט dialogEventType הוא REQUEST_DIALOG.

כדי לפתוח תיבת דו-שיח, אפליקציית Chat יכולה להשיב לבקשה על ידי החזרת אובייקט RenderActions עם רכיב הניווט pushCard כדי להציג כרטיס. הכרטיס צריך להכיל כל רכיב של ממשק משתמש (UI), כולל sections[] אחד או יותר של ווידג'טים. כדי לאסוף מידע ממשתמשים, אפשר לציין ווידג'טים להזנת נתונים בטופס וווידג'ט של לחצן. מידע נוסף על תכנון של רכיבי קלט בטופס זמין במאמר איסוף ועיבוד מידע ממשתמשים.

קובץ ה-JSON הבא מראה איך אפליקציית Chat מחזירה תגובה שפותחת תיבת דו-שיח:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

כאשר BUTTON_TEXT הוא הטקסט שמוצג בלחצן (למשל Next או Submit), WIDGETS מייצג ווידג'טים של קלט בטופס אחד או יותר, ו-ACTION_FUNCTION הוא פונקציית ה-callback של הפעולה שפועלת כשמשתמשים לוחצים על לחצן.

טיפול בשליחת תיבת הדו-שיח

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

אפליקציית Chat צריכה להגיב לאובייקט האירוע באחת מהדרכים הבאות:

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

אופציונלי: הצגת תיבת דו-שיח אחרת

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

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

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

בדוגמה הזו, אפליקציית Chat פותחת תיבת דו-שיח ראשונית שמובילה לתיבת דו-שיח שנייה לאישור לפני שליחה:

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Apps Script

בדוגמה הזו, ההודעה על הכרטיס נשלחת על ידי החזרת card JSON. אפשר גם להשתמש בשירות הכרטיסים של Apps Script.

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

כאשר WIDGETS מייצג כל ווידג'טים אחרים של קלט טפסים.

סגור את תיבת הדו-שיח

כשמשתמשים לוחצים על לחצן שליחה בתיבת דו-שיח, אפליקציית Chat מבצעת את הפעולה המשויכת ומספקת את אובייקט האירוע עם buttonClickedPayload שמוגדר כך:

isDialogEvent היא true.
dialogEventType היא SUBMIT_DIALOG.

אפליקציית Chat אמורה להחזיר אובייקט RenderActions עם הערך CLOSE_DIALOG ב-EndNavigation.

אופציונלי: הצגת התראה זמנית

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

כדי להציג התראה, מחזירים את האובייקט RenderActions עם השדה notification מוגדר.

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

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

פרטים על העברת פרמטרים בין תיבת דו-שיח מופיעים במאמר העברת נתונים לכרטיס אחר.

אם רוצים, שולחים הודעת אישור ב-Chat

כשסוגרים את תיבת הדו-שיח, אפשר גם לשלוח הודעה חדשה ב-Chat או לעדכן הודעה קיימת.

כדי לשלוח הודעה חדשה, מחזירים אובייקט DataActions שבו השדה CreateMessageAction מוגדר להודעה החדשה. לדוגמה, כדי לסגור את תיבת הדו-שיח ולשלוח הודעת טקסט, מחזירים את הערך הבא:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

כדי לעדכן הודעה אחרי שהמשתמש שולח תיבת דו-שיח, מחזירים אובייקט DataActions שמכיל אחת מהפעולות הבאות:

UpdateMessageAction: עדכון של הודעה שנשלחה על ידי אפליקציית Chat, למשל ההודעה שממנה המשתמש ביקש את תיבת הדו-שיח.
UpdateInlinePreviewAction: מעדכן את הכרטיס מתצוגה מקדימה של קישור.

פתרון בעיות

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

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

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

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

HTTP

Apps Script

פתיחת תיבת דו-שיח

הפעלת בקשה לתיבת דו-שיח

פתיחת תיבת הדו-שיח הראשונית

טיפול בשליחת תיבת הדו-שיח

אופציונלי: הצגת תיבת דו-שיח אחרת

Node.js

Apps Script

סגור את תיבת הדו-שיח

אופציונלי: הצגת התראה זמנית

Node.js

Apps Script

אם רוצים, שולחים הודעת אישור ב-Chat

פתרון בעיות

יצירת תיבת דו-שיח אינטראקטיבית