Google Chat mesajlarındaki bağlantıları önizleme

Kullanıcılar Google Chat'te bağlantı paylaştığında bağlam geçişini önlemek için Chat uygulamanız, mesajlarına daha fazla bilgi veren ve kullanıcıların doğrudan Google Chat'ten işlem yapmasına olanak tanıyan bir kart ekleyerek bağlantıyı önizleyebilir.

Google Chat'te eklentiler kullanıcılara Google Chat uygulamaları olarak görünür. Daha fazla bilgi edinmek için Google Chat'i genişletme başlıklı makaleyi inceleyin.

Örneğin, bir şirketin tüm müşteri hizmetleri temsilcilerini ve "Casey" adlı bir Chat uygulamasını içeren bir Google Chat alanı düşünün. Temsilciler, Chat alanında sık sık müşteri hizmetleri destek kaydının bağlantılarını paylaşır. Her seferinde iş arkadaşları, atanmış kişi, durum ve konu gibi ayrıntıları görmek için destek kaydı bağlantısını açmak zorunda kalır. Benzer şekilde, bir destek kaydının sahipliğini almak veya durumunu değiştirmek isteyen kullanıcıların bağlantıyı açması gerekir.

Bağlantı önizlemesi, alan adının yerleşik Chat uygulaması olan Case-y'nin, bir kullanıcı destek kaydı bağlantısı paylaştığı her seferinde atananı, durumu ve konuyu gösteren bir kart eklemesini sağlar. Karttaki düğmeler, temsilcilerin destek kaydının sahipliğini almasına ve durumu doğrudan sohbet akışından değiştirmesine olanak tanır.

Bir kullanıcı mesajına bağlantı eklediğinde, Chat uygulamasının bağlantıyı önizleyebileceğini belirten bir çip gösterilir.

Bir Chat uygulamasının bağlantıyı önizleyebileceğini belirten çip

İleti gönderildikten sonra bağlantı Chat uygulamasına gönderilir. Uygulama, kartı oluşturup kullanıcının mesajına ekler.

Mesaja kart ekleyerek bağlantıyı önizleyen Chat uygulaması

Kartta, bağlantının yanı sıra düğmeler gibi etkileşimli öğeler de dahil olmak üzere bağlantıyla ilgili ek bilgiler sağlanır. Sohbet uygulamanız, kullanıcı etkileşimlerine (ör. düğme tıklamaları) yanıt olarak ekli kartı güncelleyebilir.

Chat uygulamasının, mesajına kart ekleyerek bağlantısını önizlemesini istemeyen kullanıcılar, önizleme çipindeki simgesini tıklayarak önizlemeyi engelleyebilir. Kullanıcılar Önizlemeyi kaldır'ı tıklayarak ekli kartı istedikleri zaman kaldırabilir.

Ön koşullar

Node.js

Google Chat'i genişleten bir Google Workspace eklentisi. Bir tane oluşturmak için HTTP hızlı başlangıç kılavuzunu tamamlayın.

Apps Komut Dosyası

Google Chat'i genişleten bir Google Workspace eklentisi. Oluşturmak için Apps Komut Dosyası hızlı başlangıç kılavuzunu tamamlayın.

Chat uygulamanızın Google Cloud Console'daki yapılandırma sayfasında example.com, support.example.com ve support.example.com/cases/ gibi belirli bağlantıları URL kalıpları olarak kaydedin. Böylece Chat uygulamanız bu bağlantıları önizleyebilir.

Bağlantı önizlemeleri yapılandırma menüsü

  1. Google Cloud Console'u açın.
  2. "Google Cloud"ın yanındaki aşağı oku tıklayın ve Chat uygulamanızın projesini açın.
  3. Arama alanına Google Chat API yazın ve Google Chat API'yi tıklayın.
  4. Yönet > Yapılandırma'yı tıklayın.
  5. Bağlantı önizlemeleri bölümünde bir URL kalıbı ekleyin veya düzenleyin.
    1. Yeni bir URL kalıbı için bağlantı önizlemelerini yapılandırmak üzere URL Kalıp Ekle'yi tıklayın.
    2. Mevcut bir URL kalıbının yapılandırmasını düzenlemek için aşağı oku tıklayın.

  6. Ana makine kalıbı alanına URL kalıbının alanını girin. Chat uygulaması, bu alan adının bağlantılarını önizler.

    Chat uygulamasının subdomain.example.com gibi belirli bir alt alan adının bağlantılarını önizlemesi için alt alan adını ekleyin.

    Chat uygulamasının, alanın tamamı için bağlantıları önizlemesini istiyorsanız alt alan adı olarak yıldız (*) içeren bir joker karakter belirtin. Örneğin, *.example.com, subdomain.example.com ve any.number.of.subdomains.example.com ile eşleşir.

  7. Yol ön eki alanına, ana makine kalıbı alanına eklenecek bir yol girin.

    Ana makine kalıbı alanındaki tüm URL'lerle eşleştirme yapmak için Yol ön eki'ni boş bırakın.

    Örneğin, barındırıcı kalıbı support.example.com ise support.example.com/cases/ adresinde barındırılan destek kayıtlarının URL'lerini eşleştirmek için cases/ değerini girin.

  8. Bitti'yi tıklayın.

  9. Kaydet'i tıklayın.

Artık bir kullanıcı, Chat uygulamanızı içeren bir Chat alanındaki bir mesaja bağlantı önizleme URL'si kalıbıyla eşleşen bir bağlantı eklediğinde uygulamanız bağlantıyı önizler.

Belirli bir bağlantı için bağlantı önizlemeyi yapılandırdıktan sonra Chat uygulamanız, bağlantıya daha fazla bilgi ekleyerek bağlantıyı tanıyabilir ve önizleyebilir.

Chat uygulamanızı içeren Chat alanlarında, bir kullanıcının mesajı bağlantı önizleme URL'si kalıbıyla eşleşen bir bağlantı içerdiğinde Chat uygulamanız MessagePayload içeren bir etkinlik nesnesi alır. Yükte, message.matchedUrl nesnesi kullanıcının iletiye eklediği bağlantıyı içerir:

JSON

message: {
  matchedUrl: {
    url: "https://support.example.com/cases/case123"
  },
  ... // other message attributes redacted
}

Chat uygulamanız, MESSAGE etkinlik yükü içinde matchedUrl alanının bulunup bulunmadığını kontrol ederek önizlenen bağlantıyı içeren mesaja bilgi ekleyebilir. Chat uygulamanız, basit bir metin mesajıyla yanıt verebilir veya kart ekleyebilir.

Kısa mesajla yanıtlama

Chat uygulamanız, temel yanıtlar için bir bağlantıyı kısa mesajla yanıtlayarak bağlantıyı önizleyebilir. Bu örnekte, bir bağlantı önizleme URL'si kalıbıyla eşleşen bağlantı URL'sini tekrarlayan bir mesaj eklenmiştir.

Node.js

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to messages that have links whose URLs match URL patterns configured
 * for link previewing.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Response to send back depending on the matched URL.
 */
function handlePreviewLink(chatMessage) {
  // If the Chat app does not detect a link preview URL pattern, reply
  // with a text message that says so.
  if (!chatMessage.matchedUrl) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'No matchedUrl detected.'
    }}}}};
  }

  // Reply with a text message for URLs of the subdomain "text"
  if (chatMessage.matchedUrl.url.includes("text.example.com")) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'event.chat.messagePayload.message.matchedUrl.url: ' + chatMessage.matchedUrl.url
    }}}}};
  }
}

Apps Komut Dosyası

/**
 * Reply to messages that have links whose URLs match the pattern
 * "text.example.com" configured for link previewing.
 *
 * @param {Object} event The event object from Google Workspace Add-on.
 *
 * @return {Object} The action response.
 */
function onMessage(event) {
  // Stores the Google Chat event as a variable.
  const chatMessage = event.chat.messagePayload.message;

  // If the Chat app doesn't detect a link preview URL pattern, reply
  // with a text message that says so.
  if (!chatMessage.matchedUrl) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'No matchedUrl detected.'
    }}}}};
  }

  // Reply with a text message for URLs of the subdomain "text".
  if (chatMessage.matchedUrl.url.includes("text.example.com")) {
    return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
      text: 'event.chat.messagePayload.message.matchedUrl.url: ' + chatMessage.matchedUrl.url
    }}}}};
  }
}

Önizlenen bir bağlantıya kart eklemek için DataActions işlemini UpdateInlinePreviewAction türündeki ChatDataActionMarkup nesnesi ile döndürün.

Aşağıdaki örnekte, bir Chat uygulaması support.example.com URL kalıbını içeren mesajlara bir önizleme kartı ekler.

Mesaja kart ekleyerek bağlantıyı önizleyen Chat uygulaması

Node.js

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to messages that have links whose URLs match URL patterns configured
 * for link previewing.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Response to send back depending on the matched URL.
 */
function handlePreviewLink(chatMessage) {
  // Attach a card to the message for URLs of the subdomain "support"
  if (chatMessage.matchedUrl.url.includes("support.example.com")) {
    // A hard-coded card is used in this example. In a real-life scenario,
    // the case information would be fetched and used to build the card.
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: { cardsV2: [{
      cardId: 'attachCard',
      card: {
        header: {
          title: 'Example Customer Service Case',
          subtitle: 'Case basics',
        },
        sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        { decoratedText: { topLabel: 'Assignee', text: 'Charlie'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // Use runtime environment variable set with self URL
          onClick: { action: { function: process.env.BASE_URL }}
        }]}}
        ]}]
      }
    }]}}}};
  }
}

Apps Komut Dosyası

Bu örnek, kart JSON'unu döndürerek kart mesajı gönderir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz. 

/**
 * Attach a card to messages that have links whose URLs match the pattern
 * "support.example.com" configured for link previewing.
 *
 * @param {Object} event The event object from Google Workspace Add-on.
 *
 * @return {Object} The action response.
 */
function onMessage(event) {
  // Stores the Google Chat event as a variable.
  const chatMessage = event.chat.messagePayload.message;

  // Attach a card to the message for URLs of the subdomain "support".
  if (chatMessage.matchedUrl.url.includes("support.example.com")) {
    // A hard-coded card is used in this example. In a real-life scenario,
    // the case information would be fetched and used to build the card.
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: { cardsV2: [{
      cardId: 'attachCard',
      card: {
        header: {
          title: 'Example Customer Service Case',
          subtitle: 'Case summary',
        },
        sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        { decoratedText: { topLabel: 'Assignee', text: 'Charlie'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // Clicking this button triggers the execution of the function
          // "assign" from the Apps Script project.
          onClick: { action: { function: 'assign'}}
        }]}}
        ]}]
      }
    }]}}}};
  }
}

Chat uygulamanız, kullanıcılar bağlantı önizleme kartıyla etkileşimde bulunduğunda (ör. karttaki bir düğmeyi tıkladığında) bağlantı önizleme kartını güncelleyebilir.

Kartı güncellemek için Chat uygulamanızın, aşağıdaki ChatDataActionMarkup nesnelerinden biriyle birlikte DataActions işlemini döndürmesi gerekir:

Mesajın kim tarafından gönderildiğini belirlemek için etkinlik yükü (buttonClickedPayload) özelliğini kullanarak gönderenin (message.sender.type) HUMAN (kullanıcı) veya BOT (Chat uygulaması) olarak ayarlanıp ayarlanmadığını kontrol edin.

Aşağıdaki örnekte, bir Chat uygulamasının kullanıcı Bana Atayın düğmesini tıkladığında kartın Atanan alanını güncelleyerek ve düğmeyi devre dışı bırakarak bağlantı önizlemesini nasıl güncellediği gösterilmektedir.

Bir mesaja eklenen kartın güncellenmiş sürümünü içeren bağlantıyı önizleyen Chat uygulaması

Node.js

/**
 * Google Cloud Function that handles messages that have links whose
 * URLs match URL patterns configured for link previewing.
 *
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.previewLinks = function previewLinks(req, res) {
  const chatEvent = req.body.chat;

  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handlePreviewLink(chatEvent.messagePayload.message));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    return res.send(handleCardClick(chatEvent.buttonClickedPayload.message));
  }
};

/**
 * Respond to clicks by assigning user and updating the card that was attached to a
 * message with a previewed link.
 *
 * @param {Object} chatMessage The chat message object from Google Workspace Add On event.
 * @return {Object} Action response depending on the original message.
 */
function handleCardClick(chatMessage) {
  // Creates the updated card that displays "You" for the assignee
  // and that disables the button.
  //
  // A hard-coded card is used in this example. In a real-life scenario,
  // an actual assign action would be performed before building the card.
  const message = { cardsV2: [{
    cardId: 'attachCard',
    card: {
      header: {
        title: 'Example Customer Service Case',
        subtitle: 'Case basics',
      },
      sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        // The assignee is now "You"
        { decoratedText: { topLabel: 'Assignee', text: 'You'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // The button is now disabled
          disabled: true,
          // Use runtime environment variable set with self URL
          onClick: { action: { function: process.env.BASE_URL }}
        }]}}
      ]}]
    }
  }]};

  // Checks whether the message event originated from a human or a Chat app
  // to return the adequate action response.
  if(chatMessage.sender.type === 'HUMAN') {
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: message }}};
  } else {
    return { hostAppDataAction: { chatDataAction: { updateMessageAction: message }}};
  }
}

Apps Komut Dosyası

Bu örnek, kart JSON'unu döndürerek kart mesajı gönderir. Apps Komut Dosyası kart hizmetini de kullanabilirsiniz. 

/**
 * Assigns and updates the card that's attached to a message with a
 * previewed link of the pattern "support.example.com".
 *
 * @param {Object} event The event object from the Google Workspace Add-on.
 *
 * @return {Object} Action response depending on the message author.
 */
function assign(event) {
  // Creates the updated card that displays "You" for the assignee
  // and that disables the button.
  //
  // A hard-coded card is used in this example. In a real-life scenario,
  // an actual assign action would be performed before building the card.
  const message = { cardsV2: [{
    cardId: 'attachCard',
    card: {
      header: {
        title: 'Example Customer Service Case',
        subtitle: 'Case summary',
      },
      sections: [{ widgets: [
        { decoratedText: { topLabel: 'Case ID', text: 'case123'}},
        // The assignee is now "You"
        { decoratedText: { topLabel: 'Assignee', text: 'You'}},
        { decoratedText: { topLabel: 'Status', text: 'Open'}},
        { decoratedText: { topLabel: 'Subject', text: 'It won\'t turn on...' }},
        { buttonList: { buttons: [{
          text: 'OPEN CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123'
          }},
        }, {
          text: 'RESOLVE CASE',
          onClick: { openLink: {
            url: 'https://support.example.com/orders/case123?resolved=y',
          }},
        }, {
          text: 'ASSIGN TO ME',
          // The button is now disabled
          disabled: true,
          onClick: { action: { function: 'assign'}}
        }]}}
      ]}]
    }
  }]};

  // Use the adequate action response type. It depends on whether the message
  // the preview link card is attached to was created by a human or a Chat app.
  if(event.chat.buttonClickedPayload.message.sender.type === 'HUMAN') {
    return { hostAppDataAction: { chatDataAction: { updateInlinePreviewAction: message }}};
  } else {
    return { hostAppDataAction: { chatDataAction: { updateMessageAction: message }}};
  }
}

Sınırlar ve dikkat edilmesi gereken hususlar

Chat uygulamanız için bağlantı önizlemelerini yapılandırırken aşağıdaki sınırlamalara ve hususlara dikkat edin:

  • Her Chat uygulaması, en fazla 5 URL kalıbı için bağlantı önizlemelerini destekler.
  • Chat uygulamaları, mesaj başına bir bağlantıyı önizler. Tek bir iletide birden fazla önizlenebilir bağlantı varsa yalnızca ilk önizlenebilir bağlantı önizlenir.
  • Chat uygulamaları yalnızca https:// ile başlayan bağlantıları önizler. Bu nedenle https://support.example.com/cases/ önizleme yapar ancak support.example.com/cases/ önizleme yapmaz.
  • İleti, Chat uygulamasına gönderilecek başka bilgiler (ör. eğik çizgi komutu) içermediği sürece bağlantı önizlemeleri yalnızca bağlantı URL'sini Chat uygulamasına gönderir.
  • Bir kullanıcı bağlantıyı yayınlarsa Chat uygulaması, bağlantı önizleme kartını yalnızca kullanıcılar kartla etkileşimde bulunduğunda (ör. düğme tıklayarak) güncelleyebilir. Bir kullanıcının mesajını asenkron olarak güncellemek için Chat API'nin Message kaynağındaki update() yöntemini çağıramazsınız.
  • Sohbet uygulamaları, bağlantıları alandaki herkes için önizlemelidir. Bu nedenle, mesajda privateMessageViewer alanı atlanmalıdır.

Bağlantı önizlemelerini uygularken uygulamanın günlüklerini okuyarak Chat uygulamanızda hata ayıklama yapmanız gerekebilir. Günlükleri okumak için Google Cloud Console'daki Günlük Gezgini'ni ziyaret edin.