Um zu verhindern, dass der Kontext wechselt, wenn Nutzer einen Link in Google Chat teilen, kann Ihre Chat-App eine Vorschau des Links anzeigen. Dazu wird der Nachricht eine Karte angehängt, die weitere Informationen enthält und Nutzer direkt in Google Chat Aktionen ausführen lässt.
In Google Chat werden Add-ons für Nutzer als Google Chat-Apps angezeigt. Weitere Informationen finden Sie unter Google Chat erweitern – Übersicht.
Stellen Sie sich beispielsweise einen Google Chat-Gruppenbereich vor, der alle Kundenservicemitarbeiter eines Unternehmens sowie eine Chat-App namens Case-y enthält. Kundenservicemitarbeiter teilen häufig Links zu Kundenservicefällen im Chatbereich. Jedes Mal müssen ihre Kollegen den Falllink öffnen, um Details wie den zugewiesenen Mitarbeiter, den Status und das Thema zu sehen. Wenn jemand die Zuständigkeit für einen Fall übernehmen oder den Status ändern möchte, muss er den Link öffnen.
Mit der Linkvorschau kann die Chat-App „Case-y“ des Gruppenbereichs eine Karte mit dem zugewiesenen Mitarbeiter, dem Status und dem Betreff anhängen, wenn jemand einen Falllink teilt. Über die Schaltflächen auf der Karte können Kundenservicemitarbeiter die Zuständigkeit für den Fall übernehmen und den Status direkt über den Chatstream ändern.
Funktionsweise der Linkvorschau
Wenn jemand seiner Nachricht einen Link hinzufügt, wird ein Chip angezeigt, der darauf hinweist, dass eine Chat-App möglicherweise eine Vorschau des Links anzeigt.
Nach dem Senden der Nachricht wird der Link an die Chat-App gesendet, die dann die Karte generiert und an die Nachricht des Nutzers anhängt.
Neben dem Link enthält die Karte zusätzliche Informationen dazu, einschließlich interaktiver Elemente wie Schaltflächen. Die Chat-App kann die angehängte Karte als Reaktion auf Nutzerinteraktionen wie Schaltflächenklicks aktualisieren.
Wenn ein Nutzer nicht möchte, dass in der Chat App eine Vorschau seines Links angezeigt wird, indem er eine Karte an seine Nachricht anhängt, kann er die Vorschau verhindern, indem er auf dem Vorschau-Chip auf klickt. Nutzer können die angehängte Karte jederzeit entfernen, indem sie auf Vorschau entfernen klicken.
Vorbereitung
Node.js
Ein Google Workspace-Add-on, das Google Chat erweitert. Führen Sie dazu die HTTP-Kurzanleitung aus.
Apps Script
Ein Google Workspace-Add-on, das Google Chat erweitert. Wenn Sie ein solches Script erstellen möchten, folgen Sie der Apps Script-Kurzanleitung.
Linkvorschauen konfigurieren
Registrieren Sie bestimmte Links wie example.com, support.example.com und support.example.com/cases/ als URL-Muster auf der Konfigurationsseite Ihrer Chat-App in der Google Cloud Console, damit sie in der Chat-App in der Vorschau angezeigt werden können.
- Öffnen Sie die Google Cloud Console.
- Klicken Sie neben „Google Cloud“ auf den Abwärtspfeil und öffnen Sie das Projekt Ihrer Chat-App.
- Geben Sie
Google Chat APIin das Suchfeld ein und klicken Sie auf Google Chat API. - Klicken Sie auf Verwalten > Konfiguration.
- Fügen Sie unter „Linkvorschau“ ein URL-Muster hinzu oder bearbeiten Sie es.
- Wenn Sie Linkvorschaubilder für ein neues URL-Muster konfigurieren möchten, klicken Sie auf URL-Muster hinzufügen.
- Wenn Sie die Konfiguration für ein vorhandenes URL-Muster bearbeiten möchten, klicken Sie auf den Abwärtspfeil .
Geben Sie in das Feld Host-Muster die Domain des URL-Musters ein. In der Chat App wird eine Vorschau von Links zu dieser Domain angezeigt.
Wenn Sie in der Chat-App Vorschaulinks für eine bestimmte Subdomain wie
subdomain.example.comsehen möchten, geben Sie die Subdomain an.Wenn Sie in der Chat-App Links für die gesamte Domain in der Vorschau sehen möchten, geben Sie als Subdomain ein Platzhalterzeichen mit einem Sternchen (*) an. Beispielsweise führt
*.example.comzu Übereinstimmungen mitsubdomain.example.comundany.number.of.subdomains.example.com.Geben Sie im Feld Pfadpräfix einen Pfad ein, der an die Domain des Hostmusters angehängt werden soll.
Wenn alle URLs in der Domain des Hostmusters abgeglichen werden sollen, lassen Sie das Feld Pfadpräfix leer.
Wenn das Hostmuster beispielsweise
support.example.comlautet, geben Siecases/ein, um URLs für Fälle abzugleichen, die aufsupport.example.com/cases/gehostet werden.Klicken Sie auf Fertig.
Klicken Sie auf Speichern.
Wenn jemand einen Link in eine Nachricht in einem Chatbereich einfügt, der Ihrer Chat-App zugeordnet ist und dessen URL einem URL-Muster für Linkvorschauen entspricht, wird in Ihrer App eine Vorschau des Links angezeigt.
Link in der Vorschau anzeigen
Nachdem Sie die Linkvorschau für einen bestimmten Link konfiguriert haben, kann Ihre Chat-App den Link erkennen und eine Vorschau anzeigen, indem sie weitere Informationen an den Link anhängt.
Wenn eine Nachricht in Chatbereichen, die Ihre Chat-App enthalten, einen Link enthält, der einem URL-Muster für Linkvorschauen entspricht, erhält Ihre Chat-App ein Ereignisobjekt mit einer MessagePayload. In der Nutzlast enthält das Objekt message.matchedUrl den Link, den der Nutzer in der Nachricht angegeben hat:
JSON
message: {
matchedUrl: {
url: "https://support.example.com/cases/case123"
},
... // other message attributes redacted
}
Wenn in der Ereignisnutzlast MESSAGE das Feld matchedUrl vorhanden ist, kann Ihre Chat-App der Nachricht Informationen mit dem Link in der Vorschau hinzufügen. Ihre Chat-App kann entweder mit einer einfachen Textnachricht antworten oder eine Karte anhängen.
Mit einer SMS antworten
Bei einfachen Antworten kann Ihre Chat-App eine Vorschau eines Links anzeigen, indem Sie mit einer SMS auf einen Link antworten. In diesem Beispiel wird eine Nachricht angehängt, in der die Link-URL wiederholt wird, die einem URL-Muster für Linkvorschauen entspricht.
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 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
}}}}};
}
}
Karte mit einer Vorschau des Links anhängen
Wenn Sie einer Linkvorschau eine Karte hinzufügen möchten, geben Sie die Aktion DataActions mit dem ChatDataActionMarkup-Objekt vom Typ UpdateInlinePreviewAction zurück.
Im folgenden Beispiel fügt eine Chat-App Nachrichten, die das URL-Muster support.example.com enthalten, eine Vorschaukarte hinzu.
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 Script
In diesem Beispiel wird eine Kartennachricht gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Kartendienst von Apps Script verwenden.
/**
* 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'}}
}]}}
]}]
}
}]}}}};
}
}
Karte mit Linkvorschau aktualisieren
Ihre Chat-App kann eine Linkvorschaukarte aktualisieren, wenn Nutzer mit ihr interagieren, z. B. auf eine Schaltfläche auf der Karte klicken.
Um die Karte zu aktualisieren, muss Ihre Chat-App die Aktion DataActions mit einem der folgenden ChatDataActionMarkup-Objekte zurückgeben:
- Wenn ein Nutzer die Nachricht gesendet hat, gib ein
UpdateMessageAction-Objekt zurück. - Wenn die Nachricht über die Chat-App gesendet wurde, geben Sie ein
UpdateInlinePreviewAction-Objekt zurück.
Um herauszufinden, wer die Nachricht gesendet hat, prüfen Sie anhand der Ereignisnutzlast (buttonClickedPayload), ob der Absender (message.sender.type) auf HUMAN (Nutzer) oder BOT (Chat-App) festgelegt ist.
Im folgenden Beispiel wird gezeigt, wie in einer Chat-App eine Linkvorschau aktualisiert wird, wenn ein Nutzer auf die Schaltfläche Mir zuweisen klickt. Dazu wird das Feld Zugewiesener Nutzer der Karte aktualisiert und die Schaltfläche deaktiviert.
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 Script
In diesem Beispiel wird eine Kartennachricht gesendet, indem Karten-JSON zurückgegeben wird. Sie können auch den Kartendienst von Apps Script verwenden.
/**
* 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 }}};
}
}
Einschränkungen und Hinweise
Beachten Sie beim Konfigurieren von Linkvorschauen für Ihre Chat-App die folgenden Einschränkungen und Hinweise:
- Jede Chat-App unterstützt Linkvorschauen für bis zu fünf URL-Muster.
- In Chat-Apps wird eine Vorschau für einen Link pro Nachricht angezeigt. Wenn eine Nachricht mehrere Links mit Vorschau enthält, wird nur die Vorschau des ersten Links angezeigt.
- In Chat-Apps werden nur Links mit
https://-Vorschau angezeigt, alsohttps://support.example.com/cases/-Vorschauen, aber keinesupport.example.com/cases/-Vorschauen. - Sofern die Nachricht keine anderen Informationen enthält, die an die Chat App gesendet werden, z. B. einen Schrägstrichenbefehl, wird nur die Link-URL über Linkvorschauen an die Chat App gesendet.
- Wenn ein Nutzer den Link postet, kann die Karte mit der Linkvorschau in einer Chat-App nur aktualisiert werden, wenn Nutzer mit der Karte interagieren, z. B. durch einen Klick auf eine Schaltfläche. Sie können die
update()-Methode der Chat API nicht auf die RessourceMessageaufrufen, um die Nachricht eines Nutzers asynchron zu aktualisieren. - Chat-Apps müssen Links für alle Nutzer im Gruppenbereich in der Vorschau anzeigen. Das Feld
privateMessageViewerdarf daher nicht in der Nachricht enthalten sein.
Linkvorschauen debuggen
Wenn Sie Linkvorschauen implementieren, müssen Sie möglicherweise die Chat-App beheben, indem Sie die Protokolle der App lesen. Sie können die Logs im Log-Explorer in der Google Cloud Console aufrufen.