Gửi tin nhắn trên thẻ

Ngoài tin nhắn văn bản, các ứng dụng nhắn tin có thể gửi tin nhắn thẻ trong không gian và cho người dùng. Thẻ hỗ trợ bố cục đã xác định, các phần tử giao diện người dùng tương tác như nút và nội dung đa phương tiện như hình ảnh.

Sử dụng các thông báo thẻ để:

• Trình bày thông tin chi tiết
• Thu thập thông tin từ người dùng
• Hướng dẫn người dùng thực hiện bước tiếp theo

Hướng dẫn này mô tả cách gửi tin nhắn thẻ một cách đồng bộ (phản hồi theo thời gian thực cho một sự kiện Chat, chẳng hạn như nhận tin nhắn từ một người dùng hoặc thêm vào không gian) và không đồng bộ (gửi tin nhắn từ ứng dụng đến một không gian hoặc người dùng mà không cần lời nhắc sử dụng API REST của Chat).

Điều kiện tiên quyết

Để gửi tin nhắn thẻ trong hướng dẫn này, bạn cần:

Node.js

• Tài khoản Google Workspace có quyền truy cập vào Google Chat.
• Ứng dụng Chat. Để tạo ứng dụng nhắn tin, hãy làm theo hướng dẫn bắt đầu nhanh này.

Lưu ý: Các mã mẫu Node.js trong hướng dẫn này được viết để chạy dưới dạng Hàm Google Cloud.

Python

• Tài khoản Google Workspace có quyền truy cập vào Google Chat.
• Ứng dụng Chat. Để tạo ứng dụng nhắn tin, hãy làm theo hướng dẫn bắt đầu nhanh này.

Lưu ý: Các mã mẫu Python trong hướng dẫn này được viết để chạy dưới dạng Hàm Google Cloud, sử dụng Python 3.9.

Apps Script

• Tài khoản Google Workspace có quyền truy cập vào Google Chat.
• Ứng dụng Chat. Để tạo ứng dụng nhắn tin, hãy làm theo hướng dẫn bắt đầu nhanh này.

Phân tích các thành phần của thông báo thẻ

Mỗi thẻ, cho dù đó là hộp thoại hay thông báo, là một đối tượng JSON trên tài nguyên spaces.messages trong API Chat.

Đối tượng JSON của thẻ bao gồm:

1. Một mảng có tên là cardsV2[] chứa một hoặc nhiều đối tượng CardWithId.
2. cardId, dùng để xác định thẻ và nằm trong phạm vi một thông báo nhất định. (Các thẻ trong những tin nhắn khác nhau có thể có cùng mã nhận dạng.)

3. Đối tượng card, bao gồm:

   • Đối tượng header chỉ định những yếu tố như tiêu đề, phụ đề và hình ảnh đại diện.
   • Một hoặc nhiều đối tượng section, mỗi đối tượng chứa ít nhất một tiện ích.

   • Một hoặc nhiều đối tượng widget. Mỗi tiện ích là một đối tượng tổng hợp có thể đại diện cho văn bản, hình ảnh, nút và các loại đối tượng khác.

     Các tiện ích sau đây được hỗ trợ trong tin nhắn thẻ và hộp thoại:

     • TextParagraph – Hiển thị một đoạn văn bản có định dạng HTML đơn giản không bắt buộc.
     • Image – Hiển thị hình ảnh .PNG hoặc .JPG có thể nhấp hoặc tĩnh được lưu trữ trên URL HTTPS.
     • DecoratedText – Hiển thị văn bản bằng bố cục và các tính năng chức năng không bắt buộc, chẳng hạn như biểu tượng và nút.
     • ButtonList – Hiển thị một tập hợp các nút.

     Các tiện ích sau đây được hỗ trợ trong hộp thoại (sắp ra mắt cho tính năng thông báo thẻ):

     • TextInput–Trường mà người dùng có thể nhập văn bản.

     • SelectionInput– Cung cấp một tập hợp các mục có thể chọn, chẳng hạn như danh sách hộp đánh dấu, nút chọn, nút chuyển hoặc trình đơn thả xuống.

     • Divider – Hiển thị một đường kẻ ngang trải rộng chiều rộng của một thẻ giữa các tiện ích xếp chồng, đóng vai trò là đường phân chia hình ảnh.

     • Grid–Sắp xếp một tập hợp các mục theo dạng lưới đơn giản.

     Chúng tôi sẽ sớm hỗ trợ tiện ích sau:

     • DateTimePicker – Cho phép người dùng chỉ định ngày, giờ hoặc cả hai.

Ví dụ: quan sát các đối tượng header, section và widget trong thông báo thẻ sau:

Mã sau đây biểu thị JSON của thông báo thẻ:

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": "[e-mail]",
                }
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PERSON",
                  },
                  "text": "<font color=\"#80e27e\">Online</font>",
                },
              },
              {
                "decoratedText": {
                  "startIcon": {
                    "knownIcon": "PHONE",
                  },
                  "text": "[phone]",
                }
              },
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Share",
                      "onClick": {
                        "openLink": {
                          "url": "https://example.com/share",
                        }
                      }
                    },
                    {
                      "text": "Edit",
                      "onClick": {
                        "action": {
                          "function": "goToView",
                          "parameters": [
                            {
                              "key": "viewType",
                              "value": "EDIT",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

Gửi tin nhắn thẻ đồng bộ

Trong ví dụ này, người dùng gửi tin nhắn trong ứng dụng Chat trong Google Chat và ứng dụng trả lời bằng cách gửi một tin nhắn thẻ đồng bộ đơn giản, hiển thị tên và hình đại diện của người gửi:

Trong các mã mẫu sau, các ứng dụng Node.js và Python được lưu trữ trên Hàm Google Cloud. Ví dụ về Apps Script được lưu trữ trên Google Apps Script.

Để xem toàn bộ hướng dẫn mô tả cách tạo và triển khai ứng dụng Chat, hãy xem nội dung Tạo ứng dụng nhắn tin.

Node.js

button/avatar-bot/index.js

Xem trên GitHub

/**
 * 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.helloChat = function helloChat(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

Xem trên GitHub

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

Xem trên GitHub

/**
 * 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],
      }
    }],
  };
}

Gửi tin nhắn thẻ không đồng bộ bằng API Chat

Ví dụ này tạo ra tin nhắn một cách không đồng bộ bằng API Chat và gửi tin nhắn đó đến một không gian mà ứng dụng Chat được thêm vào, giống như không gian dưới đây:

Hình 1: Một thông báo thẻ được tạo bằng API REST của Chat.

Python

1. Trong thư mục đang hoạt động, hãy tạo một tệp có tên là chat_create_card_message.py.

2. Đưa mã sau vào 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. Trong mã, hãy thay thế SPACE bằng tên không gian mà bạn có thể lấy được từ phương thức spaces.list() trong API trò chuyện hoặc từ URL của một không gian.

4. Trong thư mục đang hoạt động, hãy tạo và chạy mẫu:

   python3 chat_create_card_message.py
   

Để tìm hiểu thêm về cách làm việc với tin nhắn trong API REST của Chat, hãy xem bài viết Tạo, đọc, cập nhật, xoá tin nhắn.

Mở hộp thoại

Hộp thoại là các giao diện cửa sổ dựa trên thẻ mà các ứng dụng nhắn tin mở ra để tương tác với người dùng. Để giúp người dùng hoàn tất các quy trình nhiều bước, các ứng dụng có thể mở hộp thoại tuần tự. Các ứng dụng có thể mở hộp thoại để phản hồi lại nút nhấp vào tin nhắn trên thẻ hoặc để phản hồi lệnh dấu gạch chéo.

Hộp thoại hữu ích cho nhiều loại tương tác của người dùng, bao gồm:

• Thu thập thông tin từ người dùng
• Xác thực người dùng bằng các dịch vụ web
• Định cấu hình chế độ cài đặt ứng dụng Chat

Trong ví dụ này, ứng dụng Chat sẽ mở một hộp thoại để giúp người dùng tạo một người liên hệ mới cho sổ địa chỉ của họ:

Để triển khai hộp thoại, hãy xem phần Mở hộp thoại.

Định dạng thẻ

Định dạng văn bản thẻ

Thẻ bên trong, hầu hết các trường văn bản đều hỗ trợ định dạng văn bản cơ bản thông qua một số ít thẻ HTML. Thẻ được hỗ trợ và mục đích của các thẻ này được trình bày trong bảng bên dưới:

In đậm	<b>		In nghiêng	<i>
Gạch dưới	<>		Gạch ngang chữ	<cảnh cáo>
Màu phông chữ	<font color="">		Đường siêu liên kết	<a href="">
Ngắt dòng	<br>

Xin lưu ý rằng phần nội dung văn bản của thông báo cơ bản được phân tích cú pháp bằng cú pháp đánh dấu khác được tối ưu hóa cho người dùng. Để biết chi tiết, hãy xem phần Gửi tin nhắn văn bản.

Biểu tượng tích hợp

Các tiện ích DecoratedText và ButtonList hỗ trợ phần tử icon dùng để chỉ định một trong các biểu tượng tích hợp có trong Google Chat:

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

Bảng sau đây liệt kê các biểu tượng tích hợp có sẵn cho thông báo thẻ:

	máy bay		DẤU_TRANG
	XE BUÝT		CAR
	KHOÁ		CONFIRMATION_NUMBER_ICON
	NỘI DUNG MÔ TẢ		NGÔN NGỮ
	EMAIL		EVENT_ Trong
	Thông tin trên máy bay		PHẦN_PHẦN_PHẦN CHẠY
	KHÁCH SẠN		HOTEL_ROOM_TYPE
	MỜI		MAP_PIN
	CHƯƠNG TRÌNH HỘI VIÊN		MULTIPLE_people
	NGƯỜI		PHONE
	RESTMenuNT_ICON		shopping_CART
	NGÔI SAO		CỬA HÀNG
	VÉ		KHOÁ
	VIDEO_CAMERA		VIDEO_PLAY

Biểu tượng tùy chỉnh

Tiện ích DecoratedText và ButtonList cho phép bạn sử dụng các biểu tượng tích hợp nêu trên hoặc xác định biểu tượng tuỳ chỉnh của riêng bạn. Để chỉ định biểu tượng tuỳ chỉnh, hãy sử dụng phần tử iconUrl như minh hoạ dưới đây:

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

Các giới hạn và yếu tố cần cân nhắc

Khi bạn đã sẵn sàng gửi thông báo bằng thẻ, hãy lưu ý những giới hạn và những điều cần cân nhắc này.

• Các tiện ích sau đây không được hỗ trợ bởi tin nhắn trên thẻ nhưng sẽ sớm hỗ trợ:

  • TextInput, một trường mà trong đó người dùng có thể nhập văn bản.
  • SelectionInput cung cấp một tập hợp các mục có thể chọn, chẳng hạn như danh sách hộp đánh dấu, nút chọn, nút chuyển hoặc trình đơn thả xuống.
  • DateTimePicker, cho phép người dùng chỉ định ngày, giờ hoặc cả hai.
  • Grid, sắp xếp một tập hợp các mục trong một lưới đơn giản.