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

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

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

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, sectionwidget trong thông báo thẻ sau:

Ứng dụng nhắn tin chạy cuộc thăm dò ý kiến trong phòng Chat bằng tin nhắn thẻ

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": "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",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

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:

Ứng dụng nhắn tin phản hồi bằng một thẻ có tên hiển thị của người gửi và hình đại diện

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

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:

Một thông báo thẻ được tạo bằng Chat REST API.
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ọ:

Hộp thoại có nhiều tiện ích khác nhau.

Để 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 DecoratedTextButtonList 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": "Khoá học", . . . }

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
KHOÁ
VIDEO_CAMERA VIDEO_PLAY

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

Tiện ích DecoratedTextButtonList 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.