除了簡訊外,Chat 應用程式還可以在聊天室中向使用者傳送卡片訊息。資訊卡支援定義的版面配置、按鈕等互動式 UI 元素,以及圖片等互動式多媒體元素。
資訊卡訊息的用途如下:
- 提供詳細資訊
- 收集使用者資訊
- 引導使用者採取下一步行動
本指南說明如何同步傳送卡片訊息 (對 Chat 事件的即時回應,例如接收使用者傳來的訊息,或加入聊天室的訊息) 以及非同步 (使用 Chat REST API 從應用程式傳送訊息至聊天室或使用者),而不使用提示。
必要條件
如要傳送這份指南中的卡片訊息,您必須符合以下條件:
Node.js
- 擁有 Google Chat 存取權的 Google Workspace 帳戶。
- 即時通訊應用程式。如要建構即時通訊應用程式,請按照這份快速入門導覽課程操作。
注意事項:本指南中的 Node.js 程式碼範例是以 Google Cloud 函式的形式編寫而成。
Python
- 擁有 Google Chat 存取權的 Google Workspace 帳戶。
- 即時通訊應用程式。如要建構即時通訊應用程式,請按照這份快速入門導覽課程操作。
注意:本指南中的 Python 程式碼範例是以 Python 3.9 而寫成,是以 Google Cloud 函式的形式執行。
Apps Script
- 擁有 Google Chat 存取權的 Google Workspace 帳戶。
- 即時通訊應用程式。如要建構即時通訊應用程式,請按照這份快速入門導覽課程操作。
信用卡訊息剖析
無論是資訊卡或是訊息,每張卡片都是 Chat API 中 spaces.messages
資源的 JSON 物件。
卡片 JSON 物件包含下列項目:
- 名為
cardsV2[]
的陣列,包含一或多個CardWithId
物件。 cardId
,用於識別卡片,並限定在特定訊息中。(不同訊息的卡片可能會有相同的 ID)。card
物件,包含下列項目:header
物件,用於指定標題、副標題和顯示圖片風格圖片等內容。- 一或多個
section
物件包含至少一個小工具。 一或多個
widget
物件。每個小工具都是一個複合式物件,可以代表文字、圖片、按鈕,以及其他物件類型。卡片訊息和對話方塊支援下列小工具:
TextParagraph
:顯示一段文字,包含簡單的 HTML 格式。Image
:顯示透過 HTTPS 網址代管的可點擊或靜態.PNG
或.JPG
圖片。DecoratedText
:顯示具有選用版面配置和功能 (例如圖示和按鈕) 的文字。ButtonList
:顯示一組按鈕。
對話方塊支援下列小工具 (即將推出資訊卡訊息):
TextInput
:使用者可輸入文字的欄位。SelectionInput
:提供一組可選取的項目,例如核取方塊、圓形按鈕、切換按鈕或下拉式選單清單。Divider
:顯示堆疊小工具之間的水平線,橫跨資訊卡寬度,可做為視覺分隔線。Grid
:以一組固定的方式顯示一組項目。
即將支援以下小工具:
DateTimePicker
:允許使用者指定日期和/或時間。
例如,請觀察以下卡片訊息中的 header
、section
和 widget
物件:
以下程式碼代表卡片訊息的 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
Python
Apps Script
使用 Chat API 傳送非同步卡片訊息
這個範例會以非同步的方式建立訊息,並使用 Chat API 將訊息傳送到新增 Chat 應用程式的聊天室,如下所示:

Python
- 在工作目錄中建立名為
chat_create_card_message.py
的檔案。 在
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)
在程式碼中,將
SPACE
替換成聊天室名稱。您可以透過 Chat API 的spaces.list()
方法或聊天室網址取得該名稱。在工作目錄中建構並執行範例:
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
可將一組項目放置在簡易格狀空間中。