Wyślij wiadomość z karty

Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Oprócz SMS-ów aplikacje do obsługi czatu mogą też wysyłać wiadomości z kart w pokojach i użytkownikom. Karty obsługują zdefiniowany układ, interaktywne elementy interfejsu (np. przyciski) i multimedialne (np. obrazy).

Używaj wiadomości na karcie do:

  • Prezentowanie szczegółowych informacji
  • Zbieranie informacji od użytkowników
  • Pokazywanie użytkownikom, co zrobić dalej

Ten przewodnik zawiera informacje na temat synchronicznego wysyłania wiadomości z karty (odpowiedzi w czasie rzeczywistym na zdarzenie Google Chat, np. odbierania wiadomości od użytkownika lub dodawania go do pokoju) oraz asynchronicznego (wysyłania wiadomości z aplikacji do pokoju lub użytkownika bez pytania przy użyciu interfejsu Chat REST API).

Wymagania wstępne

Aby wysyłać wiadomości z karty w tym przewodniku, musisz mieć:

Node.js

Uwaga: przykładowe fragmenty kodu Node.js w tym przewodniku są uruchamiane w ramach funkcji Google Cloud.

Python

Uwaga: przykłady kodu w Pythonie z tego przewodnika zostały napisane do działania jako funkcje Google Cloud w języku Python 3.9.

Google Apps Script

Anatomia wiadomości na karcie

Każda karta (czy to okno, czy wiadomość) jest obiektem JSON w zasobie spaces.messages w Google Chat API.

Obiekt JSON karty składa się z tych elementów:

  1. Tablica cardsV2[] o co najmniej jednym obiekcie CardWithId.
  2. cardId, który służy do identyfikowania karty i zakresu w danej wiadomości. (Karty w różnych wiadomościach mogą mieć ten sam identyfikator).

  3. Obiekt card, który składa się z tych elementów:

    • Obiekt header, który określa tytuł, podtytuł lub obraz w stylu awatara.
    • Jeden lub więcej obiektów section, które zawierają co najmniej jeden widżet.

    • Co najmniej 1 obiekt widget. Każdy widżet to obiekt złożony, który może reprezentować tekst, obrazy, przyciski lub inne typy obiektów.

      Te widżety i okna obsługują te widżety:

      • TextParagraph – wyświetla akapit tekstu z opcjonalnym prostym formatowaniem HTML.
      • Image – wyświetla klikalny lub statyczny obraz .PNG lub .JPG hostowany pod adresem URL HTTPS.
      • DecoratedText – wyświetla tekst z opcjonalnymi układami i funkcjami, takimi jak ikony i przyciski.
      • ButtonList – wyświetla zestaw przycisków.

      W dialogach obsługiwane są te widżety (wkrótce będą też obsługiwane wiadomości z kart):

      • TextInput – pole, w którym użytkownicy mogą wpisywać tekst

      • SelectionInput – zawiera zestaw elementów, które można wybrać, na przykład listę pól wyboru, opcji, przełączników lub menu.

      • Divider – wyświetla poziomą linię rozciągającą się po szerokość karty między skumulowanymi widżetami, pełniąc funkcję wizualnego separatora.

      • Grid – umieszcza zestaw elementów w prostej siatce.

      Wkrótce wprowadzimy obsługę tego widżetu:

      • DateTimePicker – pozwala użytkownikom określić datę, godzinę lub obie te wartości.

Przykładem mogą być obiekty header, section i widget w tym komunikacie na karcie:

Aplikacja do obsługi czatu przeprowadzająca ankietę w pokoju czatu przy użyciu wiadomości na karcie

Ten kod przedstawia kod JSON komunikatu karty:

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

Wyślij synchroniczną wiadomość z karty

W tym przykładzie użytkownik wysyła wiadomość w Google Chat, a aplikacja odpowiada, wysyłając prostą synchroniczną kartę z nazwą i awatarem nadawcy:

Aplikacja Google Chat wyświetlająca kartę z wyświetlaną nazwą i awatarem nadawcy

W poniższych przykładach kodu aplikacje Node.js i Python są hostowane w Google Cloud Functions. Przykład Apps Script znajduje się w Google Apps Script.

Pełne instrukcje tworzenia i wdrażania aplikacji do obsługi czatu znajdziesz w artykule Tworzenie aplikacji Google Chat.

Node.js

węzeł/bot-awatar/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/bot-awatar/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

Google Apps Script

apps-script/bot-awatar/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],
      }
    }],
  };
}

Wysyłanie asynchronicznej karty karty za pomocą interfejsu Chat API

Ten przykład asynchronicznie tworzy wiadomość za pomocą interfejsu Chat API i wysyła ją do pokoju, do którego aplikacja Google Chat jest dodana, jak w poniższym przykładzie:

Wiadomość w postaci karty utworzona za pomocą interfejsu Chat REST API.
Ilustracja 1. Karta z wiadomością utworzoną za pomocą interfejsu Chat REST API

Python

  1. W katalogu roboczym utwórz plik o nazwie chat_create_card_message.py.

  2. Umieść w kodzie chat_create_card_message.py ten kod:

    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. W kodzie zastąp SPACE nazwą pokoju, który możesz uzyskać za pomocą metody spaces.list() w interfejsie Chat API lub z adresu URL pokoju.

  4. W katalogu roboczym utwórz i uruchom przykład:

    python3 chat_create_card_message.py

Więcej informacji o pracy z wiadomościami w interfejsie API REST Chat znajdziesz w artykule Tworzenie, odczytywanie, aktualizowanie i usuwanie wiadomości.

Otwórz okno

Okna to opracowane w aplikacji Google Chat interfejsy oparte na kartach, które umożliwiają interakcję z użytkownikami. Aby ułatwić użytkownikom wykonywanie wieloetapowych procesów, aplikacje mogą otwierać kolejne okna dialogowe. Aplikacje mogą otwierać okna dialogowe w odpowiedzi na kliknięcie przycisku na karcie lub polecenie po ukośniku.

Okna są przydatne w przypadku wielu rodzajów interakcji użytkownika, np.:

  • Zbieranie informacji od użytkowników
  • Uwierzytelnianie użytkowników za pomocą usług internetowych
  • Konfigurowanie ustawień aplikacji Google Chat

W tym przykładzie aplikacja do obsługi czatu otworzy okno, aby pomóc użytkownikowi utworzyć nowy kontakt do jego książki adresowej:

Okno z różnymi widżetami.

Implementację okien znajdziesz w artykule Otwieranie okien.

Formatowanie karty

Formatowanie tekstu karty

Większość kart tekstowych w kartach na stronie obsługuje podstawowe formatowanie tekstu za pomocą niewielkiego podzbioru tagów HTML. Obsługiwane tagi i ich przeznaczenie znajdziesz w tabeli poniżej:

pogrubienia, <b> kursywy, <i>
Podkreślenie <> Przekreślenie <ostrzeżenie>
Kolor czcionki <font color=""> Hiperlink <a href="">
Podział wiersza <br>

Pamiętaj, że treść wiadomości podstawowej jest analizowana przy użyciu innej składni znaczników, która jest zoptymalizowana dla użytkowników. Szczegółowe informacje znajdziesz w artykule Wysyłanie SMS-ów.

Wbudowane ikony

Widżety DecoratedText i ButtonList obsługują element icon używany do określania jednej z wbudowanych ikon dostępnych w Google Chat:

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

Poniższa tabela zawiera wbudowane ikony dostępne dla wiadomości na karcie:

samolot ZAKŁADKA
Autobus CAR
ZEGAR CONFIRMATION_NUMBER_ICON
DESCRIPTION KWOTA
E-MAIL ZDARZENIE_ZDARZENIA
Przylot WYPRZEDZENIE_lotu
HOTEL TYP_ROOM_ROOM
ZAPROŚ MAP_PIN
CZŁONKOSTWO WIELE OSÓB
OSOBA TELEFON
ICON_RESTAURANT KARTA_PRODUKTOWA
GWIAZDKA SKLEP
BILET Pociąg
KAMERA_WIDEO WIDEO PLAY

Ikony niestandardowe

Widżety DecoratedText i ButtonList umożliwiają korzystanie z wbudowanych ikon wymienionych powyżej lub definiowanie własnych ikon niestandardowych. Aby określić ikonę niestandardową, użyj elementu iconUrl w ten sposób:

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

Ograniczenia i uwagi

Podczas przygotowywania się do wysyłania wiadomości dotyczących kart pamiętaj o tych ograniczeniach i uwagach.

  • Te widżety nie są obsługiwane przez wiadomości na karcie, ale wkrótce będą dostępne:

    • TextInput – pole, w którym użytkownicy mogą wpisywać tekst
    • SelectionInput, który zawiera zestaw możliwych do wybrania elementów, takich jak lista pól wyboru, opcji, przełączników lub menu.
    • DateTimePicker, który umożliwia użytkownikom określenie daty, godziny lub obu tych opcji.
    • Grid, który zawiera zestaw elementów w prostej siatce.