, który zapewnia wcześniejszy dostęp do niektórych funkcji.
Aby zapobiec przełączaniu kontekstu podczas udostępniania linku w Google Chat, aplikacja Google Chat może podać podgląd linku, dołączając do wiadomości kartę z dodatkowymi informacjami i umożliwiając użytkownikom podejmowanie działań bezpośrednio w Google Chat.
W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Więcej informacji o rozszerzaniu Google Chat .
Wyobraź sobie na przykład pokój Google Chat, który obejmuje wszystkich pracowników obsługi klienta firmy oraz aplikację Google Chat o nazwie Case-y.
Pracownicy obsługi klienta często udostępniają linki do zgłoszeń do zespołu obsługi klienta w pokoju Google Chat. Za każdym razem, gdy udostępniają link do zgłoszenia, ich współpracownicy muszą otworzyć ten link, aby zobaczyć szczegóły, takie jak osoba przypisana do zgłoszenia, jego stan i temat. Podobnie, jeśli ktoś chce przejąć zgłoszenie lub zmienić jego stan, musi otworzyć link.
Podgląd linków umożliwia aplikacji do obsługi czatu w ramach pokoju, czyli Case-y, dołączanie karty z przypisanym użytkownikiem, stanem i tematem za każdym razem, gdy ktoś udostępni link do zgłoszenia. Przyciski na karcie umożliwiają agentom przejęcie zgłoszenia i zmianę jego stanu bezpośrednio na czacie.
Jak działa podgląd linków
Gdy ktoś doda link do wiadomości, pojawi się element, który poinformuje go, że aplikacja do obsługi czatu może wyświetlić podgląd linku.
Po wysłaniu wiadomości link jest wysyłany do aplikacji Google Chat, która generuje i dołącza kartę do wiadomości użytkownika.
Oprócz linku karta zawiera dodatkowe informacje o nim, w tym elementy interaktywne, takie jak przyciski. Aplikacja Google Chat może aktualizować załączoną kartę w reakcji na interakcje użytkownika, np. kliknięcia przycisków.
Jeśli użytkownik nie chce, aby aplikacja Google Chat wyświetlała podgląd jego linku przez dołączenie karty do wiadomości, może temu zapobiec, klikając cancel na elemencie podglądu. Użytkownicy mogą w dowolnym momencie usunąć załączoną kartę, klikając Usuń podgląd .
Wymagania wstępne
Node.js Dodatek do Google Workspace, który rozszerza Google Chat. Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po HTTP .
Zarejestruj konkretne linki, takie jak example.com, support.example.com i support.example.com/cases/, jako wzorce adresów URL na stronie konfiguracji aplikacji Google Chat w konsoli Google Cloud, aby aplikacja mogła wyświetlać ich podgląd.
Otwórz konsolę Google Cloud .
Obok opcji „Google Cloud” kliknij strzałkę w dół arrow_drop_down i otwórz projekt aplikacji Google Chat.
W polu wyszukiwania wpisz Google Chat API i kliknij Interfejs API Google Chat .
Kliknij Zarządzaj > Konfiguracja .
W sekcji Podgląd linków dodaj lub zmień wzorzec adresu URL.
Aby skonfigurować podgląd linku dla nowego wzorca adresu URL, kliknij Dodaj wzorzec adresu URL .
Aby edytować konfigurację istniejącego wzorca adresu URL, kliknij strzałkę w dół expand_more .
W polu Wzorzec hosta wpisz domenę wzorca adresu URL. Aplikacja Czat będzie wyświetlać podgląd linków do tej domeny.
Aby aplikacja Google Chat wyświetlała podgląd linków do konkretnej subdomeny, np. subdomain.example.com, dodaj tę subdomenę.
Aby aplikacja Czat wyświetlała podgląd linków do całej domeny, jako subdomenę podaj symbol wieloznaczny w postaci gwiazdki (*).
Na przykład *.example.com jest zgodne z subdomain.example.com i any.number.of.subdomains.example.com.
W polu Ścieżka prefiksu wpisz ścieżkę, którą chcesz dołączyć do domeny wzorca hosta.
Aby dopasować wszystkie adresy URL w domenie wzorca hosta, pozostaw pole Prefiks ścieżki puste.
Jeśli na przykład wzór hosta to support.example.com, aby dopasować adresy URL przypadków hostowanych pod adresem support.example.com/cases/, wpisz cases/.
Kliknij Gotowe .
Kliknij Zapisz .
Teraz, gdy ktoś doda link, który pasuje do wzorca adresu URL podglądu linku, w wiadomości w pokoju czatu, który zawiera Twoją aplikację Google Chat, aplikacja wyświetli podgląd linku.
Podgląd linku
Gdy skonfigurujesz podgląd linku dla danego linku, aplikacja Google Chat będzie mogła go rozpoznać i wyświetlić podgląd, dołączając do niego więcej informacji.
W pokojach czatu, które zawierają Twoją aplikację do obsługi czatu, gdy wiadomość zawiera link, który pasuje do wzorca adresu URL podglądu linku, aplikacja do obsługi czatu otrzymuje obiekt zdarzenia z MessagePayload. W ładunku obiekt message.matchedUrl
JSON message: {
matchedUrl: {
url: "https://support.example.com/cases/case123"
},
... // other message attributes redacted
}
Sprawdzając obecność pola matchedUrl w MESSAGE, aplikacja Google Chat może dodać informacje do wiadomości z linkiem do podglądu. Aplikacja Google Chat może odpowiedzieć podstawowym SMS-em lub załączyć kartę.
Odpowiedz za pomocą SMS-a
W przypadku podstawowych odpowiedzi aplikacja Google Chat może wyświetlić podgląd linku, odpowiadając na niego wiadomością tekstową zawierającą link. W tym przykładzie załączam wiadomość, która powtarza adres URL linku, który pasuje do wzorca adresu URL podglądu linku.
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
}}}}};
}
}
Google Apps Script /**
* 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
}}}}};
}
}
Dołącz kartę z podglądem linku
Aby dołączyć kartę do linku z podglądem, zwracaj działanie DataActionsChatDataActionMarkup typu UpdateInlinePreviewAction
W tym przykładzie aplikacja do czatu dodaje kartę podglądu do wiadomości zawierających wzór adresu URL support.example.com.
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 }}
}]}}
]}]
}
}]}}}};
}
}
Google Apps Script
W tym przykładzie wysyłamy wiadomość z karty, zwracając obiekt JSON karty .
Możesz też użyć usługi karty w Apps Script .
/**
* 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'}}
}]}}
]}]
}
}]}}}};
}
}
Aktualizowanie karty podglądu linku
Aplikacja Google Chat może aktualizować kartę podglądu linku, gdy użytkownicy będą z nią wchodzić w interakcję, np. klikając przycisk na karcie.
Aby zaktualizować kartę, aplikacja Google Chat musi zwrócić działanie DataActionsChatDataActionMarkup:
Aby określić, kto wysłał wiadomość, użyj danych zdarzenia (buttonClickedPayloadmessage.sender.type) ma wartość HUMAN (użytkownik) czy BOT (aplikacja do czatu).
Ten przykład pokazuje, jak aplikacja do czatu aktualizuje podgląd linku, gdy użytkownik kliknie przycisk Przypisz do mnie , aktualizując pole Przypisany na karcie i wyłączając przycisk.
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 }}};
}
}
Google Apps Script
W tym przykładzie wysyłamy wiadomość z karty, zwracając obiekt JSON karty .
Możesz też użyć usługi karty w Apps Script .
/**
* 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 }}};
}
}
Ograniczenia i uwagi
Podczas konfigurowania podglądu linków w aplikacji Google Chat weź pod uwagę te limity i zagadnienia:
Każda aplikacja do obsługi czatu obsługuje podglądy linków dla maksymalnie 5 wzorców adresów URL.
Aplikacje do czatu wyświetlają podgląd jednego linku na wiadomość. Jeśli w jednej wiadomości znajduje się kilka linków, które można wyświetlić w podglądzie, wyświetlany jest tylko pierwszy z nich.
Aplikacje do czatu wyświetlają podgląd tylko linków, które zaczynają się od https://, więc https://support.example.com/cases/ wyświetla podgląd, ale support.example.com/cases/ nie.
O ile wiadomość nie zawiera innych informacji, które są wysyłane do aplikacji Google Chat, takich jak polecenie z ukośnikiem , podgląd linku wysyła do aplikacji Google Chat tylko adres URL linku.
Jeśli użytkownik udostępni link, aplikacja Google Chat może zaktualizować kartę podglądu linku tylko wtedy, gdy użytkownicy wejdą z nią w interakcję, np. klikną przycisk. Nie możesz wywołać metody update() interfejsu Chat API w zasobie Message, aby asynchronicznie zaktualizować wiadomość użytkownika.
Aplikacje do czatu muszą wyświetlać podgląd linków wszystkim użytkownikom w pokoju, dlatego wiadomość nie może zawierać pola privateMessageViewer.
Debugowanie podglądów linków
Podczas wdrażania podglądów linków może być konieczne debugowanie aplikacji Google Chat przez odczytanie jej dzienników. Aby odczytać logi, otwórz Eksploratora logów w konsoli Google Cloud.
