تمت ترجمة هذه الصفحة بواسطة 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 Console حتى يتمكّن تطبيق Chat من معاينتها.

قائمة إعدادات معاينات الروابط

افتح Google Cloud Console.
بجانب Google Cloud، انقر على السهم المتّجه للأسفل وافتَح مشروع تطبيق Chat.
في حقل البحث، اكتب Google Chat API وانقر على Google Chat API.
انقر على إدارة > الإعدادات.
ضمن معاينات الروابط، أضِف نمط عنوان URL أو عدِّله.
1. لضبط معاينات الروابط لنمط عنوان URL جديد، انقر على إضافة نمط عنوان URL.
2. لتعديل إعدادات نمط عنوان URL حالي، انقر على السهم المتّجه للأسفل .
في حقل نمط المضيف، أدخِل نطاق نمط عنوان URL. سيعمل تطبيق Chat على معاينة الروابط المؤدية إلى هذا النطاق.

للحصول على روابط معاينة تطبيق 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 التي تتضمن تطبيق 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 الرد إما باستخدام رسالة نصية بسيطة أو إرفاق بطاقة.

الرد باستخدام رسالة نصية

بالنسبة إلى الردود البسيطة، يمكن لتطبيق 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/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

العقدة/معاينة-رابط/إرفاق-بطاقة.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/preview-link/attachment-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

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) {
    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/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) {
    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/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

في ما يلي الرمز الكامل لتطبيق 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) {
    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/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 REST API. يمكنك الاطّلاع على تعديل بطاقة للتعرّف على المزيد من المعلومات.

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

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

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

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

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

معاينة رابط

JSON

الرد باستخدام رسالة نصية

Node.js

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

إرفاق بطاقة

Node.js

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

تعديل بطاقة

الخيار 1: التحقُّق من actionMethodName

JSON

Node.js

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

الخيار 2: التحقُّق من نوع المُرسِل

Node.js

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

مثال كامل: Case-y تطبيق خدمة العملاء Chat

Node.js

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

الحدود والاعتبارات

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

الخيار 1: التحقُّق من `actionMethodName`