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

תצוגה מקדימה של הקישורים

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

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

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

איך פועלת התצוגה המקדימה של הקישור

כשמישהו מוסיף קישור להודעה שלו, מופיע צ'יפ שמיידע אותו שאפליקציית Chat עשויה להציג תצוגה מקדימה של הקישור.

שבב שמציין שאפליקציית Chat עשויה להציג תצוגה מקדימה של קישור

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

אפליקציית Chat מציגה תצוגה מקדימה של הקישור על ידי צירוף כרטיס להודעה

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

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

הגדרת תצוגות מקדימות של קישורים

אפשר לרשום קישורים ספציפיים – כמו example.com, support.example.com ו-support.example.com/cases/ – כדפוסי כתובות URL בדף התצורה של אפליקציית Chat, במסוף Google Cloud כדי שאפליקציית Chat תוכל לראות אותם בתצוגה מקדימה.

תפריט הגדרת תצוגה מקדימה של קישורים

פותחים את מסוף Google Cloud.
ליד Google Cloud, לוחצים על החץ הפונה למטה ופותחים את הפרויקט באפליקציית Chat.
בשדה החיפוש, מקלידים Google Chat API ולוחצים על Google Chat API.
לוחצים על ניהול > הגדרה.
בקטע 'תצוגה מקדימה של קישור', מוסיפים תבנית URL או עורכים אותה.
1. כדי להגדיר תצוגה מקדימה של קישורים לתבנית URL חדשה, לוחצים על הוספת תבנית URL.
2. כדי לערוך את ההגדרות של תבנית URL קיימת, לוחצים על החץ למטה .
בשדה דפוס מארח, מזינים את הדומיין של תבנית ה-URL. אפליקציית Chat תציג תצוגה מקדימה של הקישורים לדומיין הזה.

כדי שקישורים של אפליקציות הצ'אט יוצגו בתצוגה מקדימה של תת-דומיין מסוים, כמו subdomain.example.com, צריך לכלול את תת-הדומיין.

כדי שאפליקציית Chat תציג קישורים לתצוגה מקדימה של הדומיין כולו, צריך לציין תו כללי לחיפוש עם כוכבית (*) בתור תת-הדומיין. לדוגמה, *.example.com תואם ל-subdomain.example.com ול-any.number.of.subdomains.example.com.
בשדה קידומת נתיב, מזינים נתיב לצירוף לדומיין של דפוס המארח.

כדי להתאים לכל כתובות ה-URL בדומיין של תבנית האירוח, משאירים את קידומת הנתיב ריקה.

לדוגמה, אם תבנית המארח היא support.example.com, יש להזין cases/ כדי להתאים כתובות URL עבור בקשות שמתארחות ב-support.example.com/cases/.
לוחצים על סיום.
לוחצים על שמירה.

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

תצוגה מקדימה של קישור

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

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

JSON

message {

  . . . // other message attributes redacted

  "matchedUrl": {
     "url": "https://support.example.com/cases/case123"
   },

  . . . // other message attributes redacted

}

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

מענה באמצעות הודעת טקסט

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

Node.js

צומת/תצוגה מקדימה-קישור/פשוט-טקסט-הודעה.js

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Checks for the presence of event.message.matchedUrl and responds with a
  // text message if present
  if (req.body.message.matchedUrl) {
    res.json({
      'text': 'req.body.message.matchedUrl.url: ' +
        req.body.message.matchedUrl.url,
    });
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  res.json({'text': 'No matchedUrl detected.'});
};

Apps Script

app-script/Preview-link/Simple-text-message.gs

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} event The event object from Chat API.
 *
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and responds with a
  // text message if present
  if (event.message.matchedUrl) {
    return {
      'text': 'event.message.matchedUrl.url: ' + event.message.matchedUrl.url,
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

צירוף כרטיס

כדי לצרף כרטיס לקישור בתצוגה מקדימה, יש להחזיר ActionResponse מסוג UPDATE_USER_MESSAGE_CARDS. בדוגמה הזו מצורף כרטיס פשוט.

אפליקציית Chat מציגה תצוגה מקדימה של הקישור על ידי צירוף כרטיס להודעה

Node.js

בצומת/תצוגה מקדימה של קישור/קובץ מצורף

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (req.body.message.matchedUrl) {
    res.json({
      'actionResponse': {'type': 'UPDATE_USER_MESSAGE_CARDS'},
      'cardsV2': [
        {
          'cardId': 'attachCard',
          'card': {
            'header': {
              'title': 'Example Customer Service Case',
              'subtitle': 'Case basics',
            },
            'sections': [
              {
                'widgets': [
                  {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
                  {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
                  {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
                  {
                    'keyValue': {
                      'topLabel': 'Subject', 'content': 'It won"t turn on...',
                    }
                  },
                ],
              },
              {
                'widgets': [
                  {
                    'buttons': [
                      {
                        'textButton': {
                          'text': 'OPEN CASE',
                          'onClick': {
                            'openLink': {
                              'url': 'https://support.example.com/orders/case123',
                            },
                          },
                        },
                      },
                      {
                        'textButton': {
                          'text': 'RESOLVE CASE',
                          'onClick': {
                            'openLink': {
                              'url': 'https://support.example.com/orders/case123?resolved=y',
                            },
                          },
                        },
                      },
                      {
                        'textButton': {
                          'text': 'ASSIGN TO ME',
                          'onClick': {
                            'action': {
                              'actionMethodName': 'assign',
                            },
                          },
                        },
                      },
                    ],
                  },
                ],
              },
            ],
          },
        },
      ],
    });
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  res.json({'text': 'No matchedUrl detected.'});
};

Apps Script

app-script/Preview-link/attach-card.gs

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (event.message.matchedUrl) {
    return {
      'actionResponse': {
        'type': 'UPDATE_USER_MESSAGE_CARDS',
      },
      'cardsV2': [{
        'cardId': 'attachCard',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [{
            'widgets': [
              {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
              {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
              {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
              {
                'keyValue': {
                  'topLabel': 'Subject', 'content': 'It won\'t turn on...',
                },
              },
            ],
          },
          {
            'widgets': [{
              'buttons': [
                {
                  'textButton': {
                    'text': 'OPEN CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'RESOLVE CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123?resolved=y',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'ASSIGN TO ME',
                    'onClick': {'action': {'actionMethodName': 'assign'}},
                  },
                },
              ],
            }],
          }],
        },
      }],
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

עדכון כרטיס

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

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

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

אם המשתמש יצר את ההודעה, מגדירים את ActionResponse כ-UPDATE_USER_MESSAGE_CARDS.
אם אפליקציית Chat יצרה את ההודעה, עליכם להגדיר את ActionResponse ל-UPDATE_MESSAGE.

יש שתי דרכים לעשות זאת: לציין ולבדוק actionMethodName מותאם אישית כחלק מהנכס onclick של הכרטיס המצורף (שמזהה את ההודעה שנוצרה על ידי המשתמש) או לבדוק אם ההודעה נוצרה על ידי משתמש.

אפשרות 1: חיפוש `actionMethodName`

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

JSON

. . . // Preview card details
{
  "textButton": {
    "text": "ASSIGN TO ME",
    "onClick": {

      // actionMethodName identifies the button to help determine the
      // appropriate ActionResponse.
      "action": {
        "actionMethodName": "assign",
      }
    }
  }
}
. . . // Preview card details

בעזרת "actionMethodName": "assign" שמזהה את הלחצן כחלק מתצוגה מקדימה של קישור, אפשר להחזיר באופן דינמי את ActionResponse הנכון על ידי חיפוש actionMethodName תואם:

Node.js

בצומת/תצוגה מקדימה של עדכון/כרטיס

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks for the presence of "actionMethodName": "assign" and sets
    // actionResponse.type to "UPDATE_USER"MESSAGE_CARDS" if present or
    // "UPDATE_MESSAGE" if absent.
    const actionResponseType = req.body.action.actionMethodName === 'assign' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    if (req.body.action.actionMethodName === 'assign') {
      res.json({
        'actionResponse': {

          // Dynamically returns the correct actionResponse type.
          'type': actionResponseType,
        },

        // Preview card details
        'cardsV2': [{}],
      });
    }
  }
};

Apps Script

app-script/Preview-link/update-card.gs

הצגת הקוד ב-GitHub

/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks for the presence of "actionMethodName": "assign" and sets
  // actionResponse.type to "UPDATE_USER"MESSAGE_CARDS" if present or
  // "UPDATE_MESSAGE" if absent.
  const actionResponseType = event.action.actionMethodName === 'assign' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  if (event.action.actionMethodName === 'assign') {
    return assignCase(actionResponseType);
  }
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    // Preview card details
    'cardsV2': [{}],
  };
}

אפשרות 2: בודקים את סוג השולח

יש לבדוק אם message.sender.type הוא HUMAN או BOT. אם המדיניות HUMAN מוגדרת, יש להגדיר את ActionResponse כ-UPDATE_USER_MESSAGE_CARDS. אחרת, צריך להגדיר את ActionResponse ל-UPDATE_MESSAGE. לשם כך:

Node.js

בצומת/תצוגה מקדימה של קישור/sender-type.js

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks whether the message event originated from a human or a Chat app
    // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
    // "UPDATE_MESSAGE" if Chat app.
    const actionResponseType = req.body.action.actionMethodName === 'HUMAN' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    res.json({
      'actionResponse': {

        // Dynamically returns the correct actionResponse type.
        'type': actionResponseType,
      },

      // Preview card details
      'cardsV2': [{}],
    });
  }
};

Apps Script

app-script/Preview-link/sender-type.gs

הצגת הקוד ב-GitHub

/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks whether the message event originated from a human or a Chat app
  // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
  // "UPDATE_MESSAGE" if Chat app.
  const actionResponseType = event.message.sender.type === 'HUMAN' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  return assignCase(actionResponseType);
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    // Preview card details
    'cardsV2': [{}],
  };
}

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

דוגמה מלאה: אפליקציית צ'אט עם שירות לקוחות

כאן אפשר לקרוא את הקוד המלא של Case-y, אפליקציית צ'אט שבה אפשר לראות תצוגה מקדימה של קישורים לבקשות תמיכה במרחב המשותף ב-Chat.

Node.js

צומת/תצוגה מקדימה-קישור/תצוגה מקדימה-קישור.js

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previewing.
 *
 * @param {Object} req Request sent from Google Chat.
 * @param {Object} res Response to send back.
 */
exports.onMessage = (req, res) => {
  if (req.method === 'GET' || !req.body.message) {
    res.send(
      'Hello! This function is meant to be used in a Google Chat Space.');
  }

  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (req.body.message.matchedUrl) {
    res.json(createMessage());
  }

  // Respond to button clicks on attached cards
  if (req.body.type === 'CARD_CLICKED') {
    // Checks whether the message event originated from a human or a Chat app
    // and sets actionResponse.type to "UPDATE_USER_MESSAGE_CARDS if human or
    // "UPDATE_MESSAGE" if Chat app.
    const actionResponseType = req.body.action.actionMethodName === 'HUMAN' ?
      'UPDATE_USER_MESSAGE_CARDS' :
      'UPDATE_MESSAGE';

    if (req.body.action.actionMethodName === 'assign') {
      res.json(createMessage(actionResponseType, 'You'));
    }
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  res.json({'text': 'No matchedUrl detected.'});
};

/**
 * Message to create a card with the correct response type and assignee.
 *
 * @param {string} actionResponseType
 * @param {string} assignee
 * @return {Object} a card with URL preview
 */
function createMessage(
  actionResponseType = 'UPDATE_USER_MESSAGE_CARDS',
  assignee = 'Charlie'
) {
  return {
    'actionResponse': {'type': actionResponseType},
    'cardsV2': [
      {
        'cardId': 'previewLink',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [
            {
              'widgets': [
                {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
                {'keyValue': {'topLabel': 'Assignee', 'content': assignee}},
                {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
                {
                  'keyValue': {
                    'topLabel': 'Subject', 'content': 'It won"t turn on...',
                  },
                },
              ],
            },
            {
              'widgets': [
                {
                  'buttons': [
                    {
                      'textButton': {
                        'text': 'OPEN CASE',
                        'onClick': {
                          'openLink': {
                            'url': 'https://support.example.com/orders/case123',
                          },
                        },
                      },
                    },
                    {
                      'textButton': {
                        'text': 'RESOLVE CASE',
                        'onClick': {
                          'openLink': {
                            'url': 'https://support.example.com/orders/case123?resolved=y',
                          },
                        },
                      },
                    },
                    {
                      'textButton': {
                        'text': 'ASSIGN TO ME',
                        'onClick': {
                          'action': {
                            'actionMethodName': 'assign',
                          },
                        },
                      },
                    },
                  ],
                },
              ],
            },
          ],
        }
      },
    ],
  };
}

Apps Script

app-script/Preview-link/Preview-link.gs

הצגת הקוד ב-GitHub

/**
 * Responds to messages that have links whose URLs match URL patterns
 * configured for link previews.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app attached to the message with
 * the previewed link.
 */
function onMessage(event) {
  // Checks for the presence of event.message.matchedUrl and attaches a card
  // if present
  if (event.message.matchedUrl) {
    return {
      'actionResponse': {
        'type': 'UPDATE_USER_MESSAGE_CARDS',
      },
      'cardsV2': [{
        'cardId': 'previewLink',
        'card': {
          'header': {
            'title': 'Example Customer Service Case',
            'subtitle': 'Case basics',
          },
          'sections': [{
            'widgets': [
              {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
              {'keyValue': {'topLabel': 'Assignee', 'content': 'Charlie'}},
              {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
              {
                'keyValue': {
                  'topLabel': 'Subject', 'content': 'It won\'t turn on...',
                }
              },
            ],
          },
          {
            'widgets': [{
              'buttons': [
                {
                  'textButton': {
                    'text': 'OPEN CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'RESOLVE CASE',
                    'onClick': {
                      'openLink': {
                        'url': 'https://support.example.com/orders/case123?resolved=y',
                      },
                    },
                  },
                },
                {
                  'textButton': {
                    'text': 'ASSIGN TO ME',
                    'onClick': {'action': {'actionMethodName': 'assign'}}
                  },
                },
              ],
            }],
          }],
        },
      }],
    };
  }

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return {'text': 'No matchedUrl detected.'};
}

/**
 * Updates a card that was attached to a message with a previewed link.
 *
 * @param {Object} event The event object from Chat API.
 * @return {Object} Response from the Chat app. Either a new card attached to
 * the message with the previewed link, or an update to an existing card.
 */
function onCardClick(event) {
  // Checks whether the message event originated from a human or a Chat app
  // and sets actionResponse to "UPDATE_USER_MESSAGE_CARDS if human or
  // "UPDATE_MESSAGE" if Chat app.
  const actionResponseType = event.message.sender.type === 'HUMAN' ?
    'UPDATE_USER_MESSAGE_CARDS' :
    'UPDATE_MESSAGE';

  // To respond to the correct button, checks the button's actionMethodName.
  if (event.action.actionMethodName === 'assign') {
    return assignCase(actionResponseType);
  }
}

/**
 * Updates a card to say that "You" are the assignee after clicking the Assign
 * to Me button.
 *
 * @param {String} actionResponseType Which actionResponse the Chat app should
 * use to update the attached card based on who created the message.
 * @return {Object} Response from the Chat app. Updates the card attached to
 * the message with the previewed link.
 */
function assignCase(actionResponseType) {
  return {
    'actionResponse': {

      // Dynamically returns the correct actionResponse type.
      'type': actionResponseType,
    },
    'cardsV2': [{
      'cardId': 'assignCase',
      'card': {
        'header': {
          'title': 'Example Customer Service Case',
          'subtitle': 'Case basics',
        },
        'sections': [{
          'widgets': [
            {'keyValue': {'topLabel': 'Case ID', 'content': 'case123'}},
            {'keyValue': {'topLabel': 'Assignee', 'content': 'You'}},
            {'keyValue': {'topLabel': 'Status', 'content': 'Open'}},
            {
              'keyValue': {
                'topLabel': 'Subject', 'content': 'It won\'t turn on...',
              }
            },
          ],
        },
        {
          'widgets': [{
            'buttons': [
              {
                'textButton': {
                  'text': 'OPEN CASE',
                  'onClick': {
                    'openLink': {
                      'url': 'https://support.example.com/orders/case123',
                    },
                  },
                },
              },
              {
                'textButton': {
                  'text': 'RESOLVE CASE',
                  'onClick': {
                    'openLink': {
                      'url': 'https://support.example.com/orders/case123?resolved=y',
                    },
                  },
                },
              },
              {
                'textButton': {
                  'text': 'ASSIGN TO ME',
                  'onClick': {'action': {'actionMethodName': 'assign'}},
                },
              },
            ],
          }],
        }],
      },
    }],
  };
}

מגבלות ושיקולים

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

כל אפליקציית Chat תומכת בתצוגות מקדימות לקישור של עד 5 תבניות URL.
אפליקציות הצ'אט כוללות תצוגה מקדימה של קישור אחד לכל הודעה. אם בהודעה אחת יש כמה קישורים שניתן להציג בתצוגה מקדימה, רק התצוגה המקדימה הראשונה של הקישורים.
אפליקציות צ'אט כוללות רק תצוגה מקדימה של קישורים שמתחילים ב-https://, כך שהתצוגה המקדימה היא https://support.example.com/cases/, אבל support.example.com/cases/ לא.
אלא אם ההודעה כוללת מידע אחר שנשלח לאפליקציית Chat, כמו פקודת לוכסן, רק כתובת ה-URL של הקישור נשלחת לאפליקציית Chat באמצעות תצוגות מקדימות של קישורים.
כרטיסים שמצורפים לקישורים בתצוגה מקדימה תומכים רק בActionResponse מסוג UPDATE_USER_MESSAGE_CARDS, ורק בתגובה לבקשות סינכרוניות מאירועי צ'אט. אי אפשר להציג תצוגה מקדימה של קישורים ב-UPDATE_MESSAGE או בבקשות אסינכרוניות כדי לעדכן כרטיסים שמצורפים לקישור בתצוגה מקדימה דרך Chat REST API. מידע נוסף זמין במאמר עדכון כרטיס.

ניפוי באגים בתצוגות מקדימות של קישורים

כשמטמיעים תצוגה מקדימה של קישורים, יכול להיות שתצטרכו לקרוא את יומני האפליקציה כדי לנפות באגים באפליקציית Chat. לקריאת היומנים, יש להיכנס אל Logs Explorer במסוף Google Cloud.

תצוגה מקדימה של הקישורים

איך פועלת התצוגה המקדימה של הקישור

הגדרת תצוגות מקדימות של קישורים

תצוגה מקדימה של קישור

JSON

מענה באמצעות הודעת טקסט

Node.js

Apps Script

צירוף כרטיס

Node.js

Apps Script

עדכון כרטיס

אפשרות 1: חיפוש actionMethodName

JSON

Node.js

Apps Script

אפשרות 2: בודקים את סוג השולח

Node.js

Apps Script

דוגמה מלאה: אפליקציית צ'אט עם שירות לקוחות

Node.js

Apps Script

מגבלות ושיקולים

ניפוי באגים בתצוגות מקדימות של קישורים

אפשרות 1: חיפוש `actionMethodName`