پیش نمایش لینک ها

برای جلوگیری از تغییر بافت زمانی که کاربران پیوندی را در چت Google به اشتراک می‌گذارند، برنامه چت شما می‌تواند با پیوست کردن کارتی به پیام آنها پیوند را پیش‌نمایش کند که اطلاعات بیشتری را ارائه می‌دهد و به افراد امکان می‌دهد مستقیماً از چت Google اقدام کنند.

به عنوان مثال، یک فضای چت Google را تصور کنید که شامل تمام نمایندگان خدمات مشتری یک شرکت به علاوه یک برنامه چت به نام Case-y است. نمایندگان اغلب پیوندهایی را به پرونده های خدمات مشتری در فضای چت به اشتراک می گذارند، و هر بار که این کار را انجام می دهند، همکارانشان باید پیوند پرونده را باز کنند تا جزئیاتی مانند گیرنده، وضعیت و موضوع را ببینند. به همین ترتیب، اگر کسی بخواهد مالکیت یک پرونده را در اختیار بگیرد یا وضعیت را تغییر دهد، باید پیوند را باز کند.

پیش‌نمایش پیوند، برنامه چت ساکن در فضا، Case-y، را قادر می‌سازد تا هر زمان که شخصی پیوند موردی را به اشتراک می‌گذارد، کارتی را که مأمور، وضعیت و موضوع را نشان می‌دهد، ضمیمه کند. دکمه های روی کارت به نمایندگان اجازه می دهد تا مالکیت پرونده را در دست بگیرند و وضعیت را مستقیماً از جریان چت تغییر دهند.

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

تراشه ای که نشان می دهد برنامه چت ممکن است یک پیوند را پیش نمایش کند

پس از ارسال پیام، لینک به برنامه چت ارسال می شود که سپس کارت را تولید کرده و به پیام کاربر متصل می کند.

برنامه چت در حال پیش‌نمایش پیوند با پیوست کردن کارتی به پیام

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

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

پیش نیازها

Node.js

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی با استفاده از سرویس HTTP، این شروع سریع را کامل کنید.

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

یک برنامه Google Chat که برای ویژگی‌های تعاملی فعال است. برای ایجاد یک برنامه چت تعاملی در Apps Script، این شروع سریع را کامل کنید.

پیوندهای خاص - مانند example.com ، support.example.com و support.example.com/cases/ - را به عنوان الگوهای URL در صفحه پیکربندی برنامه Chat خود در کنسول Google Cloud ثبت کنید تا برنامه Chat شما بتواند آنها را پیش نمایش کند.

منوی پیکربندی پیش نمایش پیوند

  1. کنسول Google Cloud را باز کنید.
  2. در کنار «Google Cloud»، روی پیکان رو به پایین کلیک کنید و پروژه برنامه چت خود را باز کنید.
  3. در قسمت جستجو، Google Chat API را تایپ کنید و Google Chat API را کلیک کنید.
  4. روی Manage > Configuration کلیک کنید.
  5. در بخش پیش‌نمایش‌های پیوند، یک الگوی URL را اضافه یا ویرایش کنید.
    1. برای پیکربندی پیش‌نمایش پیوندها برای الگوی URL جدید، روی افزودن الگوی URL کلیک کنید.
    2. برای ویرایش پیکربندی الگوی URL موجود، روی پیکان رو به پایین کلیک کنید.
  6. در قسمت Host pattern ، دامنه الگوی URL را وارد کنید. برنامه چت پیوندهای این دامنه را پیش‌نمایش خواهد کرد.

    برای داشتن پیوندهای پیش‌نمایش برنامه گپ برای یک زیر دامنه خاص، مانند subdomain.example.com ، زیردامنه را نیز اضافه کنید.

    برای داشتن پیوندهای پیش‌نمایش برنامه چت برای کل دامنه، یک کاراکتر عام با ستاره (*) را به عنوان زیر دامنه مشخص کنید. برای مثال، *.example.com با subdomain.example.com و any.number.of.subdomains.example.com مطابقت دارد.

  7. در قسمت پیشوند مسیر ، مسیری را وارد کنید تا به دامنه الگوی میزبان اضافه شود.

    برای مطابقت با همه URL ها در دامنه الگوی میزبان، پیشوند مسیر را خالی بگذارید.

    به عنوان مثال، اگر الگوی میزبان support.example.com باشد، برای مطابقت با نشانی‌های وب برای موارد میزبانی شده در support.example.com/cases/ ، cases/ وارد کنید.

  8. روی Done کلیک کنید.

  9. روی ذخیره کلیک کنید.

اکنون، هر زمان که فردی پیوندی را وارد کند که با الگوی URL پیش‌نمایش پیوند با پیامی در فضای چت که شامل برنامه چت شما است مطابقت دارد، برنامه شما پیوند را پیش‌نمایش می‌کند.

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

در داخل فضاهای چت که شامل برنامه چت شما می‌شود، وقتی پیام شخصی حاوی پیوندی است که با الگوی URL پیش‌نمایش پیوند مطابقت دارد، برنامه گپ شما یک رویداد تعاملی MESSAGE را دریافت می‌کند. بار JSON برای رویداد تعامل حاوی فیلد matchedUrl است:

JSON

"message": {

  . . . // other message attributes redacted

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

  . . . // other message attributes redacted

}

با بررسی وجود فیلد matchedUrl در محموله رویداد MESSAGE ، برنامه چت شما می‌تواند اطلاعاتی را با پیوند پیش‌نمایش‌شده به پیام اضافه کند. برنامه چت شما می تواند با یک پیام متنی ساده پاسخ دهد یا کارتی را پیوست کند.

با پیامک پاسخ دهید

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

Node.js

node/preview-link/simple-text-message.js
/**
 * 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) {
    return 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) {
    return 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.
  return res.json({'text': 'No matchedUrl detected.'});
};

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

apps-script/preview-link/simple-text-message.gs
/**
 * 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 برگردانید. این مثال یک کارت ساده را پیوست می کند.

برنامه چت در حال پیش‌نمایش پیوند با پیوست کردن کارتی به پیام

Node.js

node/preview-link/attach-card.js
/**
 * 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) {
    return 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) {
    return 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.
  return res.json({'text': 'No matchedUrl detected.'});
};

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

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

apps-script/preview-link/attach-card.gs
/**
 * 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 API به‌روزرسانی کنند.

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

برای اطمینان از اینکه یک تابع هم کارت های ایجاد شده توسط کاربر و هم کارت های ایجاد شده توسط کاربر را در جریان گپ به روز می کند، ActionResponse به صورت پویا بر اساس اینکه برنامه چت یا کاربر پیام را ایجاد کرده است تنظیم کنید.

  • اگر کاربری پیام را ایجاد کرد، ActionResponse روی UPDATE_USER_MESSAGE_CARDS تنظیم کنید.
  • اگر یک برنامه چت پیام را ایجاد کرد، ActionResponse روی UPDATE_MESSAGE تنظیم کنید.

دو راه برای انجام این کار وجود دارد: تعیین و بررسی یک actionMethodName سفارشی به عنوان بخشی از ویژگی onclick کارت پیوست شده (که پیام را به عنوان ایجاد شده توسط کاربر شناسایی می کند) یا بررسی اینکه آیا پیام توسط کاربر ایجاد شده است.

گزینه 1: actionMethodName را بررسی کنید

برای استفاده از actionMethodName برای مدیریت مناسب رویدادهای تعاملی CARD_CLICKED در کارت‌های پیش‌نمایش‌شده، یک 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

node/preview-link/update-card.js
/**
 * 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) {
    return 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') {
      return res.json({
        'actionResponse': {

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

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

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

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

apps-script/preview-link/update-card.gs
/**
 * 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

node/preview-link/sender-type.js
/**
 * 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) {
    return 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';

    return res.json({
      'actionResponse': {

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

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

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

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

apps-script/preview-link/sender-type.gs
/**
 * 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': [{}],
  };
}

یک دلیل معمولی برای به روز رسانی کارت در پاسخ به کلیک یک دکمه است. دکمه Assign to Me را از بخش قبلی، Attach a card را به یاد بیاورید. مثال کامل زیر کارت را به‌روزرسانی می‌کند به طوری که می‌گوید پس از کلیک کاربر روی Assign to Me به «You» اختصاص داده می‌شود. مثال به صورت پویا ActionResponse را با بررسی نوع فرستنده تنظیم می کند.

مثال کامل: Case-y برنامه چت خدمات مشتری

در اینجا کد کامل Case-y، یک برنامه چت است که پیوندهای موارد به اشتراک گذاشته شده در فضای چت را که نمایندگان خدمات مشتری در آن همکاری می کنند، پیش نمایش می دهد.

Node.js

node/preview-link/preview-link.js
/**
 * 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) {
    return 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';

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

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

  // If the Chat app doesn’t detect a link preview URL pattern, it says so.
  return 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',
                          },
                        },
                      },
                    },
                  ],
                },
              ],
            },
          ],
        }
      },
    ],
  };
}

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

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

apps-script/preview-link/preview-link.gs
/**
 * 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'}},
                },
              },
            ],
          }],
        }],
      },
    }],
  };
}

محدودیت ها و ملاحظات

همانطور که پیش نمایش پیوندها را برای برنامه چت خود پیکربندی می کنید، به این محدودیت ها و ملاحظات توجه کنید:

  • هر برنامه چت از پیش نمایش پیوند برای حداکثر 5 الگوی URL پشتیبانی می کند.
  • برنامه‌های چت یک پیوند را در هر پیام پیش‌نمایش می‌کنند. اگر چندین پیوند قابل پیش‌نمایش در یک پیام وجود داشته باشد، تنها اولین پیوند قابل پیش‌نمایش پیش‌نمایش می‌شود.
  • برنامه‌های چت فقط پیوندهایی را پیش‌نمایش می‌کنند که با https:// شروع می‌شوند، بنابراین https://support.example.com/cases/ پیش‌نمایش می‌کند، اما support.example.com/cases/ این کار را نمی‌کند.
  • مگر اینکه پیام حاوی اطلاعات دیگری باشد که به برنامه چت ارسال می‌شود، مانند دستور اسلش ، فقط URL پیوند با پیش‌نمایش پیوند به برنامه چت ارسال می‌شود.
  • کارت‌های متصل به پیوندهای پیش‌نمایش‌شده فقط از ActionResponse از نوع UPDATE_USER_MESSAGE_CARDS پشتیبانی می‌کنند و فقط در پاسخ به رویداد تعامل برنامه‌های گپ . پیش‌نمایش‌های پیوند UPDATE_MESSAGE یا درخواست‌های ناهمزمان برای به‌روزرسانی کارت‌های متصل به پیوند پیش‌نمایش‌شده از طریق Chat API پشتیبانی نمی‌کنند. برای کسب اطلاعات بیشتر، به به‌روزرسانی کارت مراجعه کنید.
  • برنامه‌های چت باید پیوندها را برای همه افراد موجود در فضا پیش‌نمایش کنند، بنابراین پیام باید قسمت privateMessageViewer حذف کند.

همانطور که پیش‌نمایش پیوندها را پیاده‌سازی می‌کنید، ممکن است لازم باشد برنامه چت خود را با خواندن گزارش‌های برنامه اشکال‌زدایی کنید. برای خواندن گزارش‌ها، از Logs Explorer در کنسول Google Cloud دیدن کنید.