Отправить сообщение карты

Оптимизируйте свои подборки Сохраняйте и классифицируйте контент в соответствии со своими настройками.

Помимо текстовых сообщений , приложения для чата могут отправлять сообщения-карточки в пространстве и пользователям. Карточки поддерживают определенный макет, интерактивные элементы пользовательского интерфейса, такие как кнопки, и мультимедийные элементы, такие как изображения.

Используйте карточные сообщения, чтобы:

  • Представить подробную информацию
  • Собирать информацию от пользователей
  • Помогите пользователям сделать следующий шаг

В этом руководстве описывается, как отправлять сообщения-карточки синхронно (ответ в реальном времени на событие чата, например, получение сообщения от пользователя или добавление в пространство) и асинхронно (отправка сообщения из приложения в пространство или пользователю без запроса с помощью REST API чата ).

Предпосылки

Для отправки карточных сообщений в этом руководстве вам потребуется следующее:

Node.js

  • Аккаунт Google Workspace с доступом к Google Chat .
  • Приложение для чата. Чтобы создать приложение для чата, следуйте этому краткому руководству.

Питон

  • Аккаунт Google Workspace с доступом к Google Chat .
  • Приложение для чата. Чтобы создать приложение для чата, следуйте этому краткому руководству.

Скрипт приложений

  • Аккаунт Google Workspace с доступом к Google Chat .
  • Приложение для чата. Чтобы создать приложение для чата, следуйте этому краткому руководству.

Анатомия сообщения карты

Каждая карточка, будь то диалог или сообщение, представляет собой объект JSON в ресурсе spaces.messages в Chat API.

Объект карты JSON состоит из следующего:

  1. Массив cardsV2[] , который содержит один или несколько объектов CardWithId .
  2. cardId , используемый для идентификации карты и ограниченный рамками данного сообщения. (Карты в разных сообщениях могут иметь одинаковый идентификатор.)
  3. Объект card , который состоит из следующего:

    • Объект header , который определяет такие вещи, как заголовок, подзаголовок и изображение в стиле аватара.
    • Один или несколько объектов section , каждый из которых содержит хотя бы один виджет.
    • Один или несколько объектов widget . Каждый виджет представляет собой составной объект, который может представлять текст, изображения, кнопки и другие типы объектов.

      В карточных сообщениях и диалогах поддерживаются следующие виджеты:

      • TextParagraph — отображает абзац текста с необязательным простым форматированием HTML.
      • Image — отображает кликабельное или статическое изображение .PNG или .JPG , размещенное на URL-адресе HTTPS.
      • DecoratedText — отображает текст с дополнительными функциями макета и функциональности, такими как значки и кнопки.
      • ButtonList — отображает набор кнопок.

      В диалогах поддерживаются следующие виджеты (скоро появится поддержка карточных сообщений):

      • TextInput — Поле, в которое пользователи могут вводить текст.
      • SelectionInput — предоставляет набор выбираемых элементов, таких как список флажков, переключателей, переключателей или раскрывающееся меню.

      • Divider — отображает горизонтальную линию, охватывающую ширину карты между расположенными друг над другом виджетами, действующую как визуальный разделитель.

      • Grid — размещает набор элементов в простой сетке.

      Скоро появится поддержка следующего виджета:

      • DateTimePicker — позволяет пользователям указывать дату, время или и то, и другое.

В качестве примера обратите внимание на объекты header , section и widget в следующем сообщении карты:

Приложение чата, выполняющее опрос в пространстве чата с использованием сообщения карты

Следующий код представляет 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 сообщение в Google Chat, а приложение отвечает, отправляя простое сообщение синхронной карточки с именем отправителя и изображением аватара:

Приложение чата отвечает карточкой с отображаемым именем отправителя и изображением аватара

В следующих примерах кода приложения Node.js и Python размещены в Google Cloud Functions . Пример Apps Script размещен на Google Apps Script .

Полные инструкции по созданию и развертыванию приложения чата см. в разделе Создание приложения чата .

Node.js

/**
  * 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.
  */
exports.helloChat = function helloChat(req, res) {
  if (req.method === 'GET' || !req.body.message) {
    res.send('Hello! This function must be called from Google Chat.');
  }

  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': imageURL},
  };

  const avatarSection = {
    'widgets': [
      avatarWidget,
      avatarImageWidget,
    ],
  };

  return {
    'cards': [{
      'name': 'Avatar Card',
      'header': cardHeader,
      'sections': [avatarSection],
    }],
  };
}

Питон

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 = {'cards': [{'name': 'Avatar Card',
                      'header': header, 'sections': [avatar_section]}]}

  return cards  

Скрипт приложений

/**
* 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 {
        cards: [{
            name: 'Avatar Card',
            header: cardHeader,
            sections: [avatarSection]
        }]
    };
}

Отправить асинхронное карточное сообщение с помощью Chat API

Этот пример асинхронно создает сообщение с помощью Chat API и отправляет его в пространство, в которое добавлено приложение Chat, как показано ниже:

Карточное сообщение, созданное с помощью Chat REST API.
Рис. 1. Карточное сообщение, созданное с помощью Chat REST API.

Питон

  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=
        {
          'cards_v2': [{
            'card_id': '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() в Chat API или из URL-адреса пространства.

  4. В рабочем каталоге соберите и запустите пример:

    python3 chat_create_card_message.py
    

Дополнительные сведения о работе с сообщениями в Chat REST API см. в статье Создание, чтение, обновление и удаление сообщений .

Открыть диалог

Диалоги — это оконные карточные интерфейсы, которые приложения чата открывают для взаимодействия с пользователями. Чтобы помочь пользователям выполнять многоэтапные процессы, приложения могут открывать последовательные диалоги. Приложения могут открывать диалоговые окна в ответ на нажатие кнопки на сообщении карточки или в ответ на команду косой черты .

Диалоги полезны для многих типов взаимодействия с пользователем, в том числе:

  • Сбор информации от пользователей
  • Аутентификация пользователей с помощью веб-сервисов
  • Настройка параметров приложения чата

В этом примере приложение Chat открывает диалоговое окно , помогающее пользователю создать новый контакт для своей адресной книги:

Диалог с множеством различных виджетов.

Чтобы реализовать диалоги, см. Открытие диалогов .

Форматирование карты

Форматирование текста карты

Внутри карточек большинство текстовых полей поддерживают базовое форматирование текста с помощью небольшого подмножества тегов HTML. Поддерживаемые теги и их назначение показаны в таблице ниже:

Смелый <b> Курсив <я>
Подчеркнуть <> Зачеркнутый <удар>
Цвет шрифта <цвет шрифта=""> Гиперссылка <а href="">
Разрыв строки <br>

Обратите внимание, что текст основного сообщения анализируется с использованием другого синтаксиса разметки, оптимизированного для пользователей-людей. Подробнее см. в разделе Отправка текстового сообщения .

Встроенные значки

Виджеты DecoratedText и ButtonList поддерживают элемент icon , используемый для указания одного из встроенных значков, доступных в Google Chat:

{ . . . "knownIcon": "ПОЕЗД", . . . }

В следующей таблице перечислены встроенные значки, доступные для карточных сообщений:

САМОЛЕТ ЗАКЛАДКА
АВТОБУС АВТОМОБИЛЬ
ЧАСЫ CONFIRMATION_NUMBER_ICON
ОПИСАНИЕ ДОЛЛАР
ЭЛ. АДРЕС EVENT_SEAT
FLIGHT_ARRIVAL FLIGHT_DEPARTURE
ОТЕЛЬ HOTEL_ROOM_TYPE
ПРИГЛАШАТЬ MAP_PIN
ЧЛЕНСТВО НЕСКОЛЬКО_ЧЕЛОВЕК
ЧЕЛОВЕК ТЕЛЕФОН
РЕСТОРАН_ICON КОРЗИНА ПОКУПАТЕЛЯ
ЗВЕЗДА ХРАНИТЬ
ПРОЕЗДНОЙ БИЛЕТ ТРЕНИРОВАТЬСЯ
ВИДЕОКАМЕРА VIDEO_PLAY

Пользовательские значки

Виджеты DecoratedText и ButtonList позволяют использовать встроенные значки, перечисленные выше, или определять собственные значки. Чтобы указать собственный значок, используйте элемент iconUrl , как показано здесь:

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

Ограничения и соображения

Готовясь к отправке карточных сообщений, обратите внимание на эти ограничения и соображения.

  • Следующие виджеты не поддерживаются карточными сообщениями, но поддержка появится в ближайшее время:

    • TextInput — поле, в которое пользователи могут вводить текст.
    • SelectionInput , который предоставляет набор выбираемых элементов, таких как список флажков, переключателей, переключателей или раскрывающееся меню.
    • DateTimePicker , который позволяет пользователям указывать дату, время или и то, и другое.
    • Grid , который размещает набор элементов в простой сетке.