ユーザーが Google Chat でリンクを共有する際にコンテキストの切り替えが行われないように、Chat アプリでリンクをプレビューできます。そのためには、詳細情報が記載されたカードをメッセージに添付して、ユーザーが Google Chat から直接対応できるようにします。
たとえば、会社のすべてのカスタマー サービス エージェントと、Case-y という名前の Chat アプリを含む Google Chat スペースがあるとします。エージェントは Chat スペースでカスタマー サービスのケースへのリンクを頻繁に共有します。同僚は、そのたびにケースリンクを開いて割り当て先、ステータス、件名などの詳細を確認する必要があります。同様に、ケースのオーナー権限の取得やステータスの変更を希望するユーザーは、リンクを開く必要があります。
リンク プレビューを使用すると、スペースに常駐する Chat アプリである Case-y は、ケースリンクが共有されるたびに、担当者、ステータス、件名を示すカードを添付できます。カード上のボタンを使用すると、エージェントはケースの所有権を取得して、チャット ストリームから直接ステータスを変更できます。
リンク プレビューの仕組み
ユーザーがメッセージにリンクを追加すると、Chat アプリによってリンクがプレビューされる可能性があることを知らせるチップが表示されます。
メッセージの送信後、リンクが Chat アプリに送信され、カードが生成されてユーザーのメッセージに添付されます。
リンクとともに、ボタンなどのインタラクティブな要素など、リンクに関する追加情報もカードに表示されます。Chat アプリでは、ボタンのクリックなどのユーザー操作に応じて、添付されたカードを更新できます。
メッセージにカードを追加してリンクをプレビューしたくないユーザーがいる場合は、プレビュー チップの cancel をクリックしてプレビューできないようにします。ユーザーは [プレビューを削除] をクリックすることで、添付されたカードをいつでも削除できます。
Google Cloud コンソールの Chat アプリの構成ページで、example.com、support.example.com、support.example.com/cases/ などの特定のリンクを URL パターンとして登録し、Chat アプリでプレビューできるようにします。
- Google Cloud コンソールを開きます。
- [Google Cloud] の横にある下矢印 arrow_drop_down をクリックし、Chat アプリのプロジェクトを開きます。
- 検索フィールドに「
Google Chat API」と入力して、[Google Chat API] をクリックします。
- [Manage] > [Configuration] をクリックします。
- [リンク プレビュー] で URL パターンを追加または編集します。
- 新しい URL パターンのリンク プレビューを設定するには、[URL パターンを追加] をクリックします。
- 既存の URL パターンの設定を編集するには、下矢印 expand_more をクリックします。
[Host pattern] フィールドに、URL パターンのドメインを入力します。このドメインへのリンクが、Chat アプリによってプレビューされます。
Chat アプリで特定のサブドメイン（subdomain.example.com など）のリンクをプレビューするには、そのサブドメインを含めます。
Chat アプリでドメイン全体のリンクをプレビューするには、ワイルドカード文字（サブドメインとしてアスタリスク（*）を含む）を指定します。たとえば、*.example.com は subdomain.example.com および any.number.of.subdomains.example.com と一致します。
[パスの接頭辞] フィールドに、ホストパターン ドメインに追加するパスを入力します。
ホストパターン ドメイン内のすべての URL を照合する場合は、[パスの接頭辞] を空のままにします。
たとえば、ホストパターンが support.example.com の場合、support.example.com/cases/ でホストされているケースの URL を照合するには、「cases/」と入力します。
[完了] をクリックします。
[保存] をクリックします。
これで、リンク プレビュー 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
}
MESSAGE イベント ペイロードに matchedUrl フィールドが存在するかどうかを確認することで、Chat アプリは、プレビュー リンクを含むメッセージに情報を追加できます。Chat アプリは、シンプルなテキスト メッセージで返信するか、カードを添付できます。
テキスト メッセージで返信する
シンプルなレスポンスの場合、Chat アプリでリンクに対してシンプルなテキスト メッセージで返信することで、リンクをプレビューできます。この例では、リンク プレビュー URL のパターンに一致するリンク URL を繰り返すメッセージを添付します。
カードを追加する
プレビューされたリンクにカードを添付するには、UPDATE_USER_MESSAGE_CARDS タイプの ActionResponse を返します。この例では、シンプルなカードを添付します。
Node.js
/**
* 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.'});
};
Apps Script
/**
* 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.'};
}
カードを更新する
プレビューされたリンクに関連付けられているカードを更新するには、UPDATE_USER_MESSAGE_CARDS タイプの ActionResponse を返します。Chat アプリでは、Chat アプリ操作イベントに対するレスポンスとしてリンクをプレビューするカードのみを更新できます。Chat アプリでは、Chat API を非同期で呼び出してこれらのカードを更新することはできません。
リンク プレビューでは、UPDATE_MESSAGE タイプの ActionResponse を返すことはできません。UPDATE_MESSAGE はカードだけでなくメッセージ全体を更新するため、Chat アプリによって元のメッセージが作成されている場合にのみ機能します。リンク プレビューでは、ユーザーが作成したメッセージにカードが添付されるため、Chat アプリにカードを更新する権限はありません。
Chat ストリーム内のユーザーが作成したカードとアプリによって作成されたカードの両方を関数で更新できるようにするには、メッセージを作成したのが Chat アプリとユーザーのどちらであるかに基づいて ActionResponse を動的に設定します。
これを行うには、添付されたカードの onclick プロパティの一部としてカスタム actionMethodName を指定して確認する（メッセージがユーザー作成であることを識別する）と、メッセージがユーザーによって作成されたかどうかを確認する方法の 2 つがあります。
actionMethodName を使用して、プレビューされたカードの CARD_CLICKED インタラクション イベントを適切に処理するには、添付されたカードの onclick プロパティの一部としてカスタム actionMethodName を設定します。
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" がリンク プレビューの一部としてボタンを識別すると、一致する actionMethodName を確認することで、正しい ActionResponse を動的に返すことができます。
方法 2: 送信者の種類を確認する
message.sender.type が HUMAN か BOT かを確認します。HUMAN の場合は ActionResponse を UPDATE_USER_MESSAGE_CARDS に設定し、それ以外の場合は ActionResponse を UPDATE_MESSAGE に設定します。方法は次のとおりです。
カードを更新する一般的な理由は、ボタンのクリックがあった場合です。前のセクションの [カードを追加] の [自分に割り当てる] ボタンを思い出してください。次の完全なサンプルでは、ユーザーが [自分に割り当てる] をクリックした後に、カードが「あなた」に割り当てられたようにカードを更新します。この例では、送信者のタイプを確認して ActionResponse を動的に設定しています。
完全な例: カスタマー サービスの Chat アプリ「Case-y」
以下に、Case-y のコード全体を示します。これは、カスタマー サービス エージェントが共同作業する Chat スペースで共有されたケースへのリンクをプレビューする Chat アプリです。
Node.js
/**
* 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',
},
},
},
},
],
},
],
},
],
}
},
],
};
}
Apps Script
/**
* 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 アプリでは、メッセージごとに 1 つのリンクがプレビューされます。1 つのメッセージにプレビュー可能なリンクが複数ある場合は、最初にプレビュー可能なリンクのみがプレビューされます。
- Chat アプリでは
https:// で始まるリンクのみがプレビューされるため、https://support.example.com/cases/ ではプレビューされますが、support.example.com/cases/ ではプレビューは行われません。
- メッセージにスラッシュ コマンドなど、Chat アプリに送信される他の情報が含まれていない場合は、リンク プレビューでリンク URL のみが Chat アプリに送信されます。
- プレビュー リンクに添付されたカードは、Chat アプリのインタラクション イベントに応答して、
UPDATE_USER_MESSAGE_CARDS タイプの ActionResponse のみをサポートします。リンク プレビューは、UPDATE_MESSAGE や、Chat API を介してプレビュー リンクに添付されたカードを更新する非同期リクエストに対応していません。詳しくは、カードを更新するをご覧ください。
リンク プレビューをデバッグする
リンク プレビューを実装する際、Chat アプリのログを参照してデバッグする必要が生じることがあります。ログを確認するには、Google Cloud コンソールのログ エクスプローラにアクセスします。
