Buat pesan kartu

Selain pesan teks, aplikasi Google Chat dapat membuat pesan kartu saat menggunakan autentikasi aplikasi. Kartu mendukung tata letak yang ditentukan, elemen UI interaktif seperti tombol, dan multimedia seperti gambar.

Gunakan pesan kartu untuk melakukan hal berikut:

  • Menyajikan informasi mendetail
  • Mengumpulkan informasi dari pengguna
  • Pandu pengguna untuk melakukan langkah berikutnya

Panduan ini menjelaskan cara membuat pesan kartu secara sinkron (respons real-time ke peristiwa Google Chat, seperti menerima pesan dari pengguna atau ditambahkan ke ruang) dan secara asinkron (mengirim pesan dari aplikasi ke ruang atau pengguna tanpa perintah menggunakan Google Chat API).

Prasyarat

Untuk membuat pesan kartu dalam panduan ini, Anda memerlukan hal-hal berikut:

Node.js

Catatan: Contoh kode Node.js dalam panduan ini ditulis untuk dijalankan sebagai Google Cloud Function.

Python

Catatan: Contoh kode Python dalam panduan ini ditulis untuk dijalankan sebagai Google Cloud Function, menggunakan Python 3.9.

Apps Script

Anatomi pesan kartu

Setiap kartu, baik itu dialog maupun pesan, adalah objek JSON pada resource spaces.messages di Google Chat API.

Objek JSON kartu terdiri dari hal berikut:

  1. Array yang disebut cardsV2[] yang berisi satu atau beberapa objek CardWithId.
  2. cardId, yang digunakan untuk mengidentifikasi kartu dan diberi cakupan dalam pesan tertentu. (Kartu dalam pesan yang berbeda dapat memiliki ID yang sama.)

  3. Objek card, yang terdiri dari hal berikut:

    • Objek header yang menentukan hal-hal seperti judul, subtitel, dan gambar bergaya avatar.
    • Satu atau beberapa objek section yang masing-masing berisi setidaknya satu widget.
    • Satu atau beberapa objek widget. Setiap widget adalah objek gabungan yang dapat mewakili teks, gambar, tombol, dan jenis objek lainnya.

Sebagai contoh, amati objek header, section, dan widget dalam pesan kartu berikut:

Aplikasi Chat yang menjalankan polling di ruang Chat menggunakan pesan kartu

Kode berikut mewakili JSON dari pesan kartu:

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

Buat pesan kartu sinkron

Dalam contoh ini, pengguna membuat pesan di Chat untuk aplikasi Chat dan aplikasi tersebut merespons dengan mengirimkan pesan kartu sinkron sederhana yang menampilkan nama avatar dan gambar avatar:

Aplikasi Chat yang merespons dengan kartu yang menampilkan nama tampilan dan gambar avatar pengirim.

Dalam contoh kode berikut, aplikasi Node.js dan Python dihosting di Google Cloud Functions. Contoh Apps Script dihosting di Google Apps Script.

Untuk mengetahui petunjuk lengkap yang menjelaskan cara mem-build dan men-deploy aplikasi Chat, lihat Mem-build aplikasi Chat.

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.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
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) -> Mapping[str, Any]:
  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],
      }
    }],
  };
}

Membuat pesan kartu asinkron dengan Chat API

Contoh ini secara asinkron membuat pesan dengan Chat API dan mengirimkannya ke ruang tempat aplikasi Chat ditambahkan:

Pesan kartu yang dibuat dengan Google Chat API.
Gambar 1: Pesan kartu yang dibuat dengan Chat API.

Python

  1. Di direktori kerja, buat file bernama chat_create_card_message.py.

  2. Sertakan kode berikut di 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. Dalam kode, ganti SPACE dengan nama ruang, yang dapat Anda peroleh dari metode spaces.list() di Chat API, atau dari URL ruang.

  4. Di direktori kerja, buat dan jalankan contoh:

    python3 chat_create_card_message.py

Untuk mempelajari lebih lanjut cara menangani pesan di Chat API, lihat hal berikut:

Membuka dialog

Dialog adalah antarmuka berbasis kartu dan memiliki jendela yang dapat dibuka oleh aplikasi Chat untuk berinteraksi dengan pengguna. Untuk membantu pengguna menyelesaikan proses multi-langkah, aplikasi dapat membuka dialog berurutan. Aplikasi dapat membuka dialog sebagai respons terhadap klik tombol pada pesan kartu atau sebagai respons terhadap perintah garis miring.

Dialog berguna untuk berbagai jenis interaksi pengguna, termasuk:

  • Mengumpulkan informasi dari pengguna
  • Mengautentikasi pengguna dengan layanan Web
  • Mengonfigurasi setelan aplikasi Chat

Dalam contoh ini, aplikasi Chat akan membuka dialog guna membantu pengguna membuat kontak baru untuk buku alamat mereka:

Dialog yang menampilkan berbagai widget yang berbeda.

Untuk menerapkan dialog, lihat Membuka dialog.

Pemformatan kartu

Ada beberapa cara untuk memformat tampilan kartu.

Pemformatan teks kartu

Di dalam kartu, sebagian besar kolom teks mendukung pemformatan teks dasar menggunakan sekumpulan kecil tag HTML.

Tag yang didukung dan tujuannya ditampilkan dalam tabel berikut:

Format Contoh Hasil yang dirender
Tebal "This is <b>bold</b>." Ini tebal.
Miring "This is <i>italics</i>." Ini miring.
Garis bawah "This is <u>underline</u>." Ini adalah garis bawah.
Coret "This is <s>strikethrough</s>." Ini dicoret.
Warna font "This is <font color=\"#FF0000\">red font</text>." Ini adalah font merah.
Hyperlink "This is a <a href=\"https://www.google.com\">hyperlink</a>." Ini adalah hyperlink.
Waktu "This is a time format: <time>2023-02-16 15:00</time>." Ini adalah format waktu: .
Baris baru "This is the first line. <br> This is a new line. inci Ini baris pertama.
Ini adalah baris baru.

Perhatikan bahwa isi teks pesan dasar diuraikan menggunakan sintaksis markup lain yang dioptimalkan untuk pengguna manusia. Untuk mengetahui detailnya, lihat Membuat pesan teks.

Ikon bawaan

Widget DecoratedText dan ButtonList mendukung elemen icon yang digunakan untuk menentukan salah satu ikon bawaan yang tersedia di Google Chat:

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

Tabel berikut mencantumkan ikon bawaan yang tersedia untuk pesan kartu:

pesawat TANDAI BUKU
Bisnis CAR
JAM KONFIRMASI_NUMBER_ICON
DESCRIPTION DOLAR
EMAIL KEDUANYA
penerbitan_penjemputan KERJA PENERBANGAN
HOTEL HOTEL_ROOM_TYPE
UNDANG PIN_MAP
LANGGANAN BEBERAPA_ORANG
ORANG PHONE
IKON RESTAURANT SHOPPING_CART
BINTANG TOKO
TIKET PELATIHAN
KAMERA_VIDEO VIDEO_PLAY

Ikon khusus

Widget DecoratedText dan ButtonList memungkinkan Anda menggunakan ikon bawaan, atau menentukan ikon khusus Anda sendiri. Untuk menentukan ikon kustom, gunakan elemen iconUrl seperti yang ditampilkan di sini:

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