傳送卡片訊息

透過集合功能整理內容 你可以依據偏好儲存及分類內容。

除了簡訊外，Chat 應用程式還可以在聊天室中向使用者傳送卡片訊息。資訊卡支援定義的版面配置、按鈕等互動式 UI 元素，以及圖片等互動式多媒體元素。

資訊卡訊息的用途如下：

  • 提供詳細資訊
  • 收集使用者資訊
  • 引導使用者採取下一步行動

本指南說明如何同步傳送卡片訊息 (對 Chat 事件的即時回應，例如接收使用者傳來的訊息，或加入聊天室的訊息) 以及非同步 (使用 Chat REST API 從應用程式傳送訊息至聊天室或使用者)，而不使用提示。

必要條件

如要傳送這份指南中的卡片訊息，您必須符合以下條件：

Node.js

注意事項：本指南中的 Node.js 程式碼範例是以 Google Cloud 函式的形式編寫而成。

Python

注意：本指南中的 Python 程式碼範例是以 Python 3.9 而寫成，是以 Google Cloud 函式的形式執行。

Apps Script

信用卡訊息剖析

無論是資訊卡或是訊息，每張卡片都是 Chat API 中 spaces.messages 資源的 JSON 物件。

卡片 JSON 物件包含下列項目：

  1. 名為 cardsV2[] 的陣列，包含一或多個 CardWithId 物件。
  2. cardId，用於識別卡片，並限定在特定訊息中。(不同訊息的卡片可能會有相同的 ID)。

  3. card 物件，包含下列項目：

    • header 物件，用於指定標題、副標題和顯示圖片風格圖片等內容。
    • 一或多個 section 物件包含至少一個小工具。

    • 一或多個 widget 物件。每個小工具都是一個複合式物件，可以代表文字、圖片、按鈕，以及其他物件類型。

      卡片訊息和對話方塊支援下列小工具：

      • TextParagraph：顯示一段文字，包含簡單的 HTML 格式。
      • Image：顯示透過 HTTPS 網址代管的可點擊或靜態 .PNG 或 .JPG 圖片。
      • DecoratedText：顯示具有選用版面配置和功能 (例如圖示和按鈕) 的文字。
      • ButtonList：顯示一組按鈕。

      對話方塊支援下列小工具 (即將推出資訊卡訊息)：

      • TextInput：使用者可輸入文字的欄位。

      • SelectionInput：提供一組可選取的項目，例如核取方塊、圓形按鈕、切換按鈕或下拉式選單清單。

      • Divider：顯示堆疊小工具之間的水平線，橫跨資訊卡寬度，可做為視覺分隔線。

      • Grid：以一組固定的方式顯示一組項目。

      即將支援以下小工具：

例如，請觀察以下卡片訊息中的 header、section 和 widget 物件：

某個 Chat 應用程式在 Chat 聊天室中使用意見調查訊息進行意見調查

以下程式碼代表卡片訊息的 JSON：

JSON

{
  "cardsV2": [
    {
      "cardId": "unique-card-id",
      "card": {
        "header": {
          "title": "Sasha",
          "subtitle": "Software Engineer",
          "imageUrl":
          "https://developers.google.com/chat/images/quickstart-app-avatar.png",
          "imageType": "CIRCLE",
          "imageAltText": "Avatar for Sasha",
        },
        "sections": [
          {
            "header": "Contact Info",
            "collapsible": true,
            "uncollapsibleWidgetsCount": 1,
            "widgets": [
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "EMAIL",
                  },
                  "text": "sasha@example.com",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "+1 (555) 555-1234",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

傳送同步卡片訊息

在此範例中，使用者在 Google Chat 中傳送即時通訊應用程式給應用程式，而應用程式傳送簡單的同步訊息，內含寄件者的名稱和顯示圖片，以回應訊息：

即時通訊應用程式回應卡片，當中有寄件者的顯示名稱和顯示圖片

下列程式碼範例包含 Google Cloud Functions 託管的 Node.js 和 Python 應用程式。Apps Script 範例由 Google Apps Script 代管。

如需建構及部署即時通訊應用程式的完整操作說明，請參閱建構即時通訊應用程式。

Node.js

node/avatar-bot/index.js
/**
 * Google Cloud Function that responds to messages sent from a
 * Hangouts Chat room.
 *
 * @param {Object} req Request sent from Hangouts Chat room
 * @param {Object} res Response to send back
 */
exports.helloHangoutsChat = function helloHangoutsChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function is meant to be used in a Hangouts Chat ' +
      'Room.');
  }

  const sender = req.body.message.sender.displayName;
  const image = req.body.message.sender.avatarUrl;

  const data = createMessage(sender, image);

  res.send(data);
};

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} imageUrl the URL for the sender's avatar
 * @return {Object} a card with the user's avatar.
 */
function createMessage(displayName, imageUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`,
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '},
  };

  const avatarImageWidget = {
    image: {imageUrl},
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

Python

python/avatar-bot/main.py
from typing import Any, Mapping

import flask
import functions_framework

# Google Cloud Function that responds to messages sent in
# Google Chat.
#
# @param {Object} req Request sent from Google Chat.
# @param {Object} res Response to send back.
@functions_framework.http
def hello_chat(req: flask.Request):
    if req.method == "GET":
        return "Hello! This function must be called from Google Chat."

    request_json = req.get_json(silent=True)

    display_name = request_json["message"]["sender"]["displayName"]
    avatar = request_json["message"]["sender"]["avatarUrl"]

    response = create_message(name=display_name, image_url=avatar)

    return response


# Creates a card with two widgets.
# @param {string} name the sender's display name.
# @param {string} image_url the URL for the sender's avatar.
# @return {Object} a card with the user's avatar.
def create_message(name: str, image_url: str) -> Mapping[str, Any]:
    avatar_image_widget = {"image": {"imageUrl": image_url}}
    avatar_text_widget = {"textParagraph": {"text": "Your avatar picture:"}}
    avatar_section = {"widgets": [avatar_text_widget, avatar_image_widget]}

    header = {"title": f"Hello {name}!"}

    cards = {
        "cardsV2": [
            {
                "cardId": "avatarCard",
                "card": {
                    "name": "Avatar Card",
                    "header": header,
                    "sections": [avatar_section],
                },
            }
        ]
    }

    return cards

Apps Script

apps-script/avatar-bot/hello-chat.gs
/**
 * Responds to a MESSAGE event in Google Chat.
 *
 * @param {Object} event the event object from Google Chat
 */
function onMessage(event) {
  const displayName = event.message.sender.displayName;
  const avatarUrl = event.message.sender.avatarUrl;

  return createMessage(displayName, avatarUrl);
}

/**
 * Creates a card with two widgets.
 * @param {string} displayName the sender's display name
 * @param {string} avatarUrl the URL for the sender's avatar
 * @return {Object} a card with the sender's avatar.
 */
function createMessage(displayName, avatarUrl) {
  const cardHeader = {
    title: `Hello ${displayName}!`
  };

  const avatarWidget = {
    textParagraph: {text: 'Your avatar picture: '}
  };

  const avatarImageWidget = {
    image: {imageUrl: avatarUrl}
  };

  const avatarSection = {
    widgets: [
      avatarWidget,
      avatarImageWidget
    ],
  };

  return {
    cardsV2: [{
      cardId: 'avatarCard',
      card: {
        name: 'Avatar Card',
        header: cardHeader,
        sections: [avatarSection],
      }
    }],
  };
}

使用 Chat API 傳送非同步卡片訊息

這個範例會以非同步的方式建立訊息，並使用 Chat API 將訊息傳送到新增 Chat 應用程式的聊天室，如下所示：

透過 Chat REST API 建立的資訊卡訊息。
圖 1：使用 Chat REST API 建立的資訊卡訊息。

Python

  1. 在工作目錄中建立名為 chat_create_card_message.py 的檔案。

  2. 在 chat_create_card_message.py 中加入下列程式碼：

    from httplib2 import Http
from oauth2client.service_account import ServiceAccountCredentials
from apiclient.discovery import build

# Specify required scopes.
SCOPES = ['https://www.googleapis.com/auth/chat.bot']

# Specify service account details.
CREDENTIALS = ServiceAccountCredentials.from_json_keyfile_name(
    'service_account.json', SCOPES)

# Build the URI and authenticate with the service account.
chat = build('chat', 'v1', http=CREDENTIALS.authorize(Http()))

# Create a Chat message.
result = chat.spaces().messages().create(

    # The space to create the message in.
    #
    # Replace SPACE with a space name.
    # Obtain the space name from the spaces resource of Chat API,
    # or from a space's URL.
    parent='spaces/SPACE',

    # The message to create.
    body=
    {
      'cardsV2': [{
        'cardId': 'createCardMessage',
        'card': {
          'header': {
            'title': 'A Card Message!',
            'subtitle': 'Created with Chat REST API',
            'imageUrl': 'https://developers.google.com/chat/images/chat-product-icon.png',
            'imageType': 'CIRCLE'
          },
          'sections': [
            {
              'widgets': [
                {
                  'buttonList': {
                    'buttons': [
                      {
                        'text': 'Read the docs!',
                        'onClick': {
                          'openLink': {
                            'url': 'https://developers.google.com/chat'
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }]
    }

).execute()

print(result)

  3. 在程式碼中，將 SPACE 替換成聊天室名稱。您可以透過 Chat API 的 spaces.list() 方法或聊天室網址取得該名稱。

  4. 在工作目錄中建構並執行範例：

    python3 chat_create_card_message.py

如要進一步瞭解如何在 Chat REST API 中使用訊息，請參閱建立、讀取、更新、刪除訊息。

開啟對話方塊

對話方塊是視窗式的介面，即時通訊應用程式可開啟，與使用者互動。為協助使用者完成多步驟程序，應用程式可以開啟依序對話方塊。應用程式可以開啟對話方塊，以回應按鈕點選卡片訊息或回應斜線指令。

對話方塊非常適合用於多種使用者互動，包括：

  • 收集使用者資訊
  • 透過網路服務驗證使用者
  • 調整即時通訊應用程式設定

在此範例中，Chat 應用程式會開啟對話方塊，協助使用者為通訊錄建立新的聯絡人：

包含各種不同小工具的對話方塊。

如要實作對話方塊，請參閱開啟對話方塊一文。

卡片格式

卡片文字格式設定

在大部分資訊卡中，大多數文字欄位都支援透過少量的 HTML 標記使用基本文字格式設定。下表列出支援的代碼及其用途：

粗體 <b> 斜體 <i>
底線 <> 刪除線 <警告>
字型色彩 <font color=""> 超連結 <a href="">
分行符號 <br>

請注意，基本訊息的文字內文是以其他針對使用者使用者最佳化的標記語法加以剖析。詳情請參閱傳送簡訊。

內建圖示

DecoratedText 和 ButtonList 小工具支援 icon 元素，用來指定 Google Chat 中可用的其中一個內建圖示：

{ 。。"knownIcon": "TRAIN", . 。. }

下表列出適用於卡片訊息的內建圖示：

氣派 圖書行銷
客運 預估
錶面 CONFIRMATION_NUMBER_ICON
DESCRIPTION 說明
電子郵件 EVENT_SEAT
搭乘航班 航班航班
飯店 HOTEL_ROOM_TYPE
邀請 MAP_PIN 碼
成員資格 MULTIPLE_人員
個人 手機
RESTAURANT_ICON 購物活動
星號 商店
票券 火車
VIDEO_CAMERA VIDEO_PLAY

自訂圖示

DecoratedText 和 ButtonList 小工具可讓您使用上述的內建圖示，或定義您專屬的自訂圖示。如要指定自訂圖示，請使用 iconUrl 元素，如下所示：

{ 。。"iconUrl": "https://developers.google.com/chat/images/quickstart-app-avatar.png" 。. }

限制和注意事項

準備要傳送卡片訊息時，請留意這些限制和注意事項。

  • 資訊卡訊息不支援下列小工具，但即將支援這項功能：

    • TextInput 為一個欄位，可讓使用者輸入文字。
    • SelectionInput：提供一組可選取的項目，例如核取方塊、圓形按鈕、切換按鈕或下拉式選單清單。
    • DateTimePicker 可讓使用者指定日期、時間或兩者。
    • Grid 可將一組項目放置在簡易格狀空間中。