معاينة الروابط

لمنع تبديل السياق عندما يشارك المستخدمون رابطًا في Google Chat، يمكن لتطبيق Chat معاينة الرابط من خلال إرفاق بطاقة برسالتهم، تقدّم معلومات إضافية وتتيح للمستخدمين اتّخاذ إجراء من Google Chat مباشرةً.

على سبيل المثال، تخيَّل مساحة في Google Chat تتضمّن جميع موظّفي خدمة العملاء في الشركة بالإضافة إلى تطبيق Chat باسم Case-y. يشارك موظّفو الدعم بشكل متكرر روابط تؤدي إلى حالات خدمة العملاء في مساحة Chat، وفي كل مرة يعملون فيها على مشاركة رابط الطلب، على زملائهم فتح رابط الطلب للاطّلاع على التفاصيل، مثل المسؤول عن الدعم الذي تم تكليفه به والحالة والموضوع. وبالمثل، إذا أراد أحد المستخدمين الحصول على ملكية طلب أو تغيير حالته، عليه فتح الرابط.

تتيح معاينة الرابط لتطبيق Chat، المقيم في المساحة، إرفاق بطاقة تعرض المستخدم الذي تم تعيين المهمة له والحالة والموضوع عندما يشارك مستخدم رابطًا لطلب الدعم. وتسمح الأزرار الظاهرة على البطاقة لموظّفي الدعم بامتلاك الطلب وتغيير الحالة مباشرةً من ساحة مشاركات المحادثة.

آلية عمل معاينة الرابط

عندما يضيف مستخدم رابطًا إلى رسالته، تظهر شريحة لإعلامه بأنّ تطبيق Chat قد يعاين الرابط.

بعد إرسال الرسالة، يتم إرسال الرابط إلى تطبيق Chat الذي ينشئ البطاقة ويرفقها في رسالة المستخدم.

إلى جانب الرابط، توفر البطاقة معلومات إضافية حول الرابط، بما في ذلك عناصر تفاعلية مثل الأزرار. يمكن لتطبيق Chat تعديل البطاقة المرفقة استجابةً لتفاعلات المستخدمين، مثل النقرات على الأزرار.

إذا لم يُرِد مستخدم من تطبيق Chat معاينة الرابط من خلال إرفاق بطاقة برسالته، يمكنه منع المعاينة من خلال النقر على في شريحة المعاينة. يمكن للمستخدمين إزالة البطاقة المرفقة في أي وقت من خلال النقر على إزالة المعاينة.

المتطلبات الأساسية

ملاحظة: بالنسبة إلى Node.js وPython، تتم كتابة عيّنات التعليمات البرمجية في هذا الدليل لتشغيلها. كوظيفة في Google Cloud.

Node.js

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat تفاعليًا باستخدام خدمة HTTP، أكمِل عملية البدء السريع هذه.

برمجة تطبيقات

تطبيق Google Chat مفعَّل للميزات التفاعلية لإنشاء تطبيق Chat التفاعلي في "برمجة تطبيقات Google"، أكمِل البدء السريع هذا.

ضبط معاينات الروابط

يمكنك تسجيل روابط محدّدة، مثل example.com وsupport.example.com وsupport.example.com/cases/، كأنماط عناوين URL في صفحة ضبط تطبيق Chat ضمن Google Cloud Console حتى يتمكّن تطبيق Chat من معاينتها.

1. افتح وحدة تحكُّم Google Cloud.
2. بجانب "Google Cloud"، انقر على السهم المتّجه للأسفل وافتح مشروع تطبيقك في Chat.
3. في حقل البحث، اكتب Google Chat API وانقر على Google Chat API.
4. انقر على إدارة > الإعداد.
5. ضمن معاينات الروابط، يمكنك إضافة نمط عنوان URL أو تعديله.
   1. لضبط معاينات الروابط لنمط عنوان URL جديد، انقر على إضافة نمط عنوان URL.
   2. لتعديل إعدادات نمط عنوان URL الحالي، انقر على السهم المتّجه للأسفل .

6. في الحقل نمط المضيف، أدخِل نطاق نمط عنوان URL. سيعاين تطبيق Chat الروابط المؤدية إلى هذا النطاق.

   لتضمين روابط معاينة تطبيق في Chat لنطاق فرعي محدّد، مثل subdomain.example.com، يجب تضمين النطاق الفرعي.

   لإتاحة روابط معاينة تطبيق Chat للنطاق بأكمله، حدِّد حرف بدل مع علامة النجمة (*) كنطاق فرعي. على سبيل المثال، تتطابق السمة *.example.com مع subdomain.example.com وany.number.of.subdomains.example.com.

7. في الحقل بادئة المسار، أدخِل مسارًا لإلحاقه بنطاق نمط المضيف.

   لمطابقة جميع عناوين URL في نطاق نمط المضيف، اترك بادئة المسار فارغة.

   على سبيل المثال، إذا كان نمط المضيف هو support.example.com، لمطابقة عناوين URL للحالات المُستضافة على support.example.com/cases/، أدخِل cases/.

8. انقر على تم.

9. انقر على حفظ.

والآن، عندما يُضمِّن مستخدم رابطًا يتطابق مع نمط عنوان URL لمعاينة الرابط مع رسالة في مساحة Chat تتضمّن تطبيق Chat، يعاين تطبيقك الرابط.

معاينة رابط

بعد ضبط معاينة الرابط لرابط معيّن، بإمكان تطبيق Chat التعرّف على الرابط ومعاينته من خلال مع إرفاق المزيد من المعلومات بها.

مساحات Chat الداخلية التي تتضمّن تطبيق Chat، عندما تحتوي رسالة أحد المستخدمين على رابط تتطابق مع نمط عنوان URL لمعاينة الرابط، سيتطابق تطبيق Chat يتلقّى حدث تفاعل واحد (MESSAGE). JSON تحتوي حمولة حدث التفاعل على الحقل matchedUrl:

JSON

"message": {

  . . . // other message attributes redacted

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

  . . . // other message attributes redacted

}

من خلال التحقّق من توفّر الحقل matchedUrl في فعالية MESSAGE ، يمكن لتطبيق Chat إضافة معلومات إلى تحتوي على الرابط الذي تمت معاينته. يمكن لتطبيق Chat إما الرد برسالة نصية بسيطة أو إرفاق بطاقة.

الرد برسالة نصية

للحصول على ردود بسيطة، يمكن لتطبيق Chat معاينة رابط. عن طريق الرد باستخدام رسالة نصية بسيطة إلى رابط. يتم في هذا المثال إرفاق رسالة تكرّر عنوان URL للرابط يطابق نمط عنوان URL لمعاينة الرابط.

Node.js

node/preview-link/simple-text-message.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) {
    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

عرض على 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. يرفق هذا المثال بطاقة بسيطة.

Node.js

node/preview-link/attach-card.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) {
    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. يمكنك أيضًا استخدام صفحة خدمة بطاقة "برمجة تطبيقات Google"

apps-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 لا يمكن لتطبيقات Chat تعديل هذه البطاقات من خلال طلب البيانات من خلال Chat 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 للتعامل بشكل سليم مع أحداث تفاعل 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

عرض على 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) {
    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. يمكنك أيضًا استخدام صفحة خدمة بطاقة "برمجة تطبيقات Google"

apps-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

node/preview-link/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) {
    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. يمكنك أيضًا استخدام صفحة خدمة بطاقة "برمجة تطبيقات Google"

apps-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 ديناميكيًا من خلال التحقّق من نوع المُرسِل.

مثال كامل: تجربة تطبيق Chat لخدمة العملاء

في ما يلي الرمز الكامل لـ Case-y، وهو تطبيق في Chat يعاين روابط الطلبات التي تمت مشاركتها في مساحة Chat التي يتعاون فيها موظّفو خدمة العملاء.

Node.js

node/preview-link/preview-link.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) {
    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. يمكنك أيضًا استخدام صفحة خدمة بطاقة "برمجة تطبيقات Google"

apps-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.
• تعاين التطبيقات في Chat رابطًا واحدًا لكل رسالة. في حال توفّر عدة روابط قابلة للمعاينة في رسالة واحدة، سيتم فقط معاينة الرابط الأول القابل للمعاينة.
• لا تعاين تطبيقات Chat سوى الروابط التي تبدأ بـ https://، وبالتالي لا يعاين https://support.example.com/cases/ معاينات المحتوى support.example.com/cases/.
• ما لم تتضمّن الرسالة معلومات أخرى يتم إرسالها إلى تطبيق Chat، مثل أمر شرطة مائلة، لن يتم إرسال سوى عنوان URL للرابط إلى تطبيق Chat من خلال معاينات الرابط.
• تتوافق البطاقات المرفقة بالروابط التي تمت معاينتها مع ActionResponse من النوع UPDATE_USER_MESSAGE_CARDS فقط، وذلك استجابةً لحدث تفاعل مع تطبيق Chat. لا تتيح معاينات الروابط UPDATE_MESSAGE أو الطلبات غير المتزامنة لتعديل البطاقات المرفقة برابط معاين عبر Chat API. للمزيد من المعلومات، يمكنك الاطّلاع على مقالة تعديل بطاقة.

معاينات روابط تصحيح الأخطاء

أثناء تنفيذ معاينات الروابط، قد تحتاج إلى تصحيح أخطاء تطبيق Chat عن طريق قراءة سجلّات التطبيق. لقراءة السجلّات، يُرجى الانتقال إلى مستكشف السجلات في وحدة تحكُّم Google Cloud.