สร้างข้อความการ์ด

นอกเหนือจากข้อความแล้ว แอป Google Chat ยังสร้างข้อความในการ์ดได้ในพื้นที่ทํางานและสําหรับผู้ใช้ การ์ดสนับสนุนการจัดวางที่กําหนดไว้ องค์ประกอบ UI เชิงโต้ตอบ เช่น ปุ่ม และสื่อสมบูรณ์ เช่น รูปภาพ

ใช้ข้อความการ์ดเพื่อดําเนินการต่อไปนี้

  • นําเสนอข้อมูลโดยละเอียด
  • รวบรวมข้อมูลจากผู้ใช้
  • แนะนําให้ผู้ใช้ทําขั้นตอนถัดไป

คําแนะนํานี้จะอธิบายวิธีสร้างข้อความการ์ดแบบพร้อมกัน (การตอบกลับกิจกรรมของ Google Chat แบบเรียลไทม์ เช่น รับข้อความจากผู้ใช้หรือระบบเพิ่มลงในพื้นที่ทํางาน) และแบบอะซิงโครนัส (การส่งข้อความจากแอปไปยังพื้นที่ทํางานหรือผู้ใช้โดยไม่มีข้อความแจ้งโดยใช้ Google Chat API)

สิ่งที่ต้องดำเนินการก่อน

หากต้องการสร้างข้อความการ์ดในคู่มือนี้ คุณต้องมีสิ่งต่อไปนี้

Node.js

หมายเหตุ: ตัวอย่างโค้ด Node.js ในคู่มือนี้เขียนขึ้นให้ทํางานเป็นฟังก์ชัน Google Cloud

Python

หมายเหตุ: ตัวอย่างโค้ด Python ในคําแนะนํานี้เขียนขึ้นให้ทํางานเป็นGoogle Cloud Function โดยใช้ Python 3.9

Apps Script

โครงสร้างของข้อความการ์ด

โดยแต่ละการ์ดไม่ว่าจะเป็นกล่องโต้ตอบหรือข้อความ จะเป็นออบเจ็กต์ JSON บนทรัพยากร spaces.messages ใน Google Chat API

ออบเจ็กต์ JSON ของการ์ดประกอบด้วยรายการต่อไปนี้

  1. อาร์เรย์ชื่อ cardsV2[] ที่มีออบเจ็กต์ CardWithId อย่างน้อย 1 รายการ
  2. cardId ซึ่งใช้ระบุการ์ดและกําหนดขอบเขตภายในข้อความที่ต้องการ (การ์ดในข้อความต่างๆ อาจมีรหัสเหมือนกัน)

  3. ออบเจ็กต์ card ซึ่งประกอบด้วยสิ่งต่อไปนี้

    • วัตถุ header ที่ระบุสิ่งต่างๆ เช่น ชื่อ ชื่อรอง และรูปโปรไฟล์
    • ออบเจ็กต์ section รายการอย่างน้อย 1 รายการ แต่ละรายการมีวิดเจ็ตอย่างน้อย 1 รายการ
    • ออบเจ็กต์ widget รายการอย่างน้อย 1 รายการ วิดเจ็ตแต่ละชิ้นเป็นวัตถุแบบผสมที่สามารถแสดงข้อความ รูปภาพ ปุ่ม และวัตถุประเภทอื่นๆ

ตัวอย่างเช่น สังเกตออบเจ็กต์ 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",
                            }
                          ],
                        }
                      }
                    },
                  ],
                }
              },
            ],
          },
        ],
      },
    }
  ],
}

สร้างข้อความการ์ดซิงโครนัส

ในตัวอย่างนี้ ผู้ใช้สร้างแอป Chat ด้วยข้อความใน Chat และแอปจะตอบสนองด้วยการส่งข้อความการ์ดซิงโครนัสอย่างง่ายที่แสดงชื่อและรูปโปรไฟล์ของผู้ส่ง

แอป Chat ตอบกลับด้วยการ์ดที่มีชื่อที่แสดงและรูปโปรไฟล์ของผู้ส่ง

ในตัวอย่างโค้ดต่อไปนี้ แอป Node.js และ Python โฮสต์อยู่ใน Google Cloud Functions ตัวอย่าง Apps Script โฮสต์อยู่ใน Google Apps Script

สําหรับคําแนะนําแบบเต็มซึ่งอธิบายวิธีสร้างและทําให้แอป Chat ใช้งานได้ โปรดดูหัวข้อสร้างแอป 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):
    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 ไว้ ดังนี้

ข้อความการ์ดที่สร้างด้วย Google Chat API
ภาพที่ 1: ข้อความการ์ดที่สร้างขึ้นด้วย Chat 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 ด้วยชื่อพื้นที่ทํางานซึ่งได้จาก เมธอดของ spaces.list() ใน API ของ Chat หรือจาก URL ของพื้นที่ทํางาน

  4. สร้างและเรียกใช้ตัวอย่างในไดเรกทอรีการทํางาน

    python3 chat_create_card_message.py

หากต้องการเรียนรู้เพิ่มเติมเกี่ยวกับการทํางานกับข้อความใน Chat API โปรดดูข้อมูลต่อไปนี้

เปิดกล่องโต้ตอบ

กล่องโต้ตอบจะเป็นอินเทอร์เฟซแบบการ์ดในหน้าต่างซึ่งแอป Chat จะเปิดขึ้นเพื่อโต้ตอบกับผู้ใช้ แอปเปิดกล่องโต้ตอบตามลําดับเพื่อช่วยให้ผู้ใช้ดําเนินการตามขั้นตอนหลายขั้นตอนได้ แอปจะเปิดกล่องโต้ตอบเพื่อตอบสนองต่อการคลิกปุ่มข้อความบนการ์ดหรือเพื่อตอบสนองในคําสั่งเครื่องหมายทับได้

กล่องโต้ตอบมีประโยชน์สําหรับการโต้ตอบของผู้ใช้หลายประเภท ได้แก่

  • การเก็บข้อมูลจากผู้ใช้
  • การตรวจสอบสิทธิ์ผู้ใช้ด้วยบริการเว็บ
  • การกําหนดการตั้งค่าแอป Chat

ในตัวอย่างนี้ แอปแชทจะเปิดกล่องโต้ตอบเพื่อช่วยผู้ใช้สร้างรายชื่อติดต่อใหม่สําหรับสมุดที่อยู่

กล่องโต้ตอบที่มีวิดเจ็ตต่างๆ มากมาย

หากต้องการใช้กล่องโต้ตอบ โปรดดูที่หัวข้อเปิดกล่องโต้ตอบ

การจัดรูปแบบการ์ด

มี 2-3 วิธีในการจัดรูปแบบลักษณะของการ์ด

การจัดรูปแบบข้อความในการ์ด

ภายในการ์ด ช่องข้อความส่วนใหญ่รองรับการจัดรูปแบบข้อความพื้นฐานโดยใช้เซ็ตย่อยของแท็ก HTML

แท็กที่สนับสนุนและวัตถุประสงค์ของแท็กจะแสดงอยู่ในตารางต่อไปนี้

รูปแบบ ตัวอย่าง แสดงผลแล้ว
ตัวหนา "This is <b>bold</b>." ส่วนนี้จะเป็นตัวหนา
ตัวเอียง "This is <i>italics</i>." นี่คือตัวเอียง
ขีดเส้นใต้ "This is <u>underline</u>." ตัวเลือกนี้จะเป็นขีดเส้นใต้
ขีดทับ "This is <s>strikethrough</s>." นี่คือขีดทับ
สีแบบอักษร "This is <font color=\"#FF0000\">red font</text>." นี่คือแบบอักษรสีแดง
ไฮเปอร์ลิงก์ "This is a <a href=\"https://www.google.com\">hyperlink</a>." นี่คือไฮเปอร์ลิงก์
เวลา "This is a time format: <time>2023-02-16 15:00</time>." รูปแบบเวลาคือ
บรรทัดใหม่ "This is the first line. <br> This is a new line. นิ้ว นี่คือบรรทัดแรก
นี่คือบรรทัดใหม่

โปรดทราบว่าระบบจะแยกวิเคราะห์เนื้อหาพื้นฐานของข้อความพื้นฐานโดยใช้ไวยากรณ์มาร์กอัปอื่นซึ่งเพิ่มประสิทธิภาพให้เหมาะกับผู้ใช้ที่เป็นมนุษย์ โปรดดูรายละเอียดที่หัวข้อสร้าง SMS

ไอคอนในตัว

วิดเจ็ต DecoratedText และ ButtonList รองรับองค์ประกอบ icon ซึ่งใช้เพื่อระบุไอคอนในตัวที่มีใน Google Chat

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

ตารางต่อไปนี้แสดงไอคอนในตัวที่พร้อมใช้งานสําหรับข้อความการ์ด

เครื่องบิน บุ๊กมาร์ก
รถบัส รถยนต์
นาฬิกา ยืนยันไอคอน NUMBER_ICON
คําอธิบาย Dollar
อีเมล กิจกรรม
FLIGHT_ARRIVAL FLIGHT_DEPARTURE
โรงแรม ประเภทห้องพักแบบโรงแรม
เชิญ MAP_PIN
การเป็นสมาชิก ผู้คนจํานวนมาก
บุคคล โทรศัพท์
ไอคอนร้านอาหาร รถเข็นช็อปปิ้ง
ติดดาว ร้านค้า
บัตร ฝึก
กล้องวิดีโอ VIDEO_PLAY

ไอคอนที่กำหนดเอง

วิดเจ็ต DecoratedText และ ButtonList ช่วยให้คุณใช้ไอคอนในตัว หรือกําหนดไอคอนของคุณเองได้ หากต้องการระบุไอคอนที่กําหนดเอง ให้ใช้องค์ประกอบ iconUrl ตามที่ปรากฏที่นี่

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