Envoyer un message par carte

Restez organisé à l'aide des collections Enregistrez et classez les contenus selon vos préférences.

En plus des SMS, les applications Chat peuvent envoyer des cartes dans des espaces et aux utilisateurs. Les fiches acceptent une mise en page définie, des éléments interactifs de l'interface utilisateur comme les boutons et des éléments rich media comme les images.

Les cartes permettent de:

  • Présenter des informations détaillées
  • Recueillir des informations auprès des utilisateurs
  • Incitez les utilisateurs à passer à l'étape suivante

Ce guide explique comment envoyer des messages de fiche de manière synchrone (réponse en temps réel à un événement Chat, comme la réception d'un message d'un utilisateur ou l'ajout à un espace) et de manière asynchrone (envoi d'un message de l'application à un espace ou à un utilisateur sans invite via l'API REST Chat).

Conditions préalables

Pour envoyer les messages de la carte dans ce guide, vous avez besoin des éléments suivants:

Node.js

Remarque : Les exemples de code Node.js de ce guide sont écrits pour s'exécuter en tant que fonction Google Cloud.

Python

Remarque : Les exemples de code Python de ce guide sont écrits pour s'exécuter en tant que fonction Google Cloud, à l'aide de Python 3.9.

Apps Script

Anatomie d'un message de fiche

Chaque fiche, qu'il s'agisse d'une boîte de dialogue ou d'un message, est un objet JSON sur la ressource spaces.messages de l'API Chat.

L'objet JSON de la fiche comprend les éléments suivants:

  1. Un tableau appelé cardsV2[] contenant un ou plusieurs objets CardWithId.
  2. Un cardId, utilisé pour identifier la fiche et limité à un message donné. (Les fiches de différents messages peuvent avoir le même ID.)
  3. Un objet card, composé des éléments suivants:

    • Un objet header qui spécifie des éléments comme un titre, un sous-titre et une image de style avatar.
    • Un ou plusieurs objets section contenant chacun au moins un widget.
    • Un ou plusieurs objets widget. Chaque widget est un objet composite qui peut représenter du texte, des images, des boutons et d'autres types d'objets.

      Les widgets suivants sont compatibles avec les messages de la fiche et les boîtes de dialogue:

      • TextParagraph : affiche un paragraphe de texte avec une mise en forme HTML simple facultative.
      • Image : affiche une image .PNG ou .JPG cliquable ou statique hébergée sur une URL HTTPS.
      • DecoratedText : affiche du texte avec des fonctionnalités et une mise en page facultatives, comme des icônes et des boutons.
      • ButtonList : affiche un ensemble de boutons.

      Les widgets suivants sont compatibles avec les boîtes de dialogue (bientôt compatibles avec les messages de la fiche):

      • TextInput : champ dans lequel les utilisateurs peuvent saisir du texte.
      • SelectionInput : fournit un ensemble d'éléments sélectionnables, comme une liste de cases à cocher, des cases d'option, des contacteurs ou un menu déroulant.

      • Divider : affiche une ligne horizontale couvrant la largeur d'une fiche entre les widgets empilés, agissant comme un séparateur visuel.

      • Grid : affiche un ensemble d'éléments dans une grille simple.

      Le widget suivant sera bientôt disponible:

      • DateTimePicker : permet aux utilisateurs de spécifier une date, une heure ou les deux.

À titre d'exemple, observez les objets header, section et widget dans le message de fiche suivant:

Application de chat avec sondage dans un espace Chat

Le code suivant représente le code JSON du message de la carte:

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

Envoyer un message de carte synchrone

Dans cet exemple, un utilisateur envoie à Google Chat un message dans Google Chat, et l'application répond en envoyant un simple message de carte synchrone affichant le nom de l'expéditeur et l'image de l'avatar:

Application de chat qui répond avec une fiche indiquant le nom à afficher et l&#39;image de l&#39;avatar de l&#39;expéditeur

Dans les exemples de code suivants, les applications Node.js et Python sont hébergées sur Google Cloud Functions. L'exemple Apps Script est hébergé sur Google Apps Script.

Pour obtenir des instructions complètes sur la création et le déploiement d'une application de chat, consultez Créer une application de 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.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],
      }
    }],
  };
}

Envoyer un message de carte asynchrone avec l'API Chat

Cet exemple crée un message avec l'API Chat de manière asynchrone et l'envoie à un espace auquel l'application Chat est ajoutée, comme illustré ci-dessous:

Message de fiche créé avec l&#39;API REST Chat.
Figure 1 : Message de fiche créé avec l'API REST Chat.

Python

  1. Dans votre répertoire de travail, créez un fichier nommé chat_create_card_message.py.
  2. Ajoutez le code suivant dans 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. Dans le code, remplacez SPACE par un nom d'espace, que vous pouvez obtenir à l'aide de la méthode spaces.list() dans l'API Chat ou à partir de l'URL d'un espace.

  4. Dans votre répertoire de travail, créez et exécutez l'exemple:

    python3 chat_create_card_message.py
    

Pour en savoir plus sur l'utilisation des messages dans l'API REST Chat, consultez Créer, lire, mettre à jour et supprimer des messages.

Ouvrir une boîte de dialogue

Les boîtes de dialogue sont des interfaces fenêtrées que les applications Chat ouvrent pour interagir avec les utilisateurs. Pour aider les utilisateurs à effectuer des processus en plusieurs étapes, les applications peuvent ouvrir des boîtes de dialogue séquentielles. Les applications peuvent ouvrir des boîtes de dialogue en réponse à un clic sur un bouton de fiche de message ou en réponse à une commande à barre oblique.

Les boîtes de dialogue sont utiles pour de nombreux types d'interactions utilisateur:

  • Collecte d'informations auprès des utilisateurs
  • Authentifier les utilisateurs avec les services Web
  • Configurer les paramètres de l'application Chat

Dans cet exemple, une application de chat ouvre une boîte de dialogue pour aider un utilisateur à créer un contact pour son carnet d'adresses:

Boîte de dialogue présentant différents widgets.

Pour implémenter des boîtes de dialogue, consultez Ouvrir les boîtes de dialogue.

Format de la fiche

Mise en forme du texte de la fiche

À l'intérieur des fiches, la plupart des champs de texte acceptent la mise en forme de base avec un petit sous-ensemble de balises HTML. Les balises acceptées et leur rôle sont indiqués dans le tableau ci-dessous:

Gras <b> Italique <i>
Souligné <> Barrer <avertissement>
Couleur de police <font color=""> Lien hypertexte <a href="">
Saut de ligne <br>

Notez que le corps de texte d'un message de base est analysé à l'aide d'une syntaxe de balisage différente, optimisée pour les utilisateurs humains. Pour en savoir plus, consultez Envoyer un SMS.

Icônes intégrées

Les widgets DecoratedText et ButtonList sont compatibles avec l'élément icon permettant de spécifier l'une des icônes intégrées disponibles dans Google Chat:

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

Le tableau suivant répertorie les icônes intégrées disponibles pour les messages de la fiche:

avion MARQUE-MAIL
BUS VOITURE
Horloge CONFIRMATION_NUMBER_ICON
DESCRIPTION DEVISE
E-MAIL SEAT_EVENT
FLIGHT_ARRIVAL FLIGHT_DEPARTURE
HÔTEL HOTEL_ROOM_TYPE
INVITER MAP_PIN
SOUSCRIPTION PLUSIEURS_PERSONNES
PERSONNE TÉLÉPHONE
RESTAURANT_ICON CARTE_SHOPPING
ÉTOILE BOUTIQUE
BILLET FORMATION
CAMÉRA_VIDÉO VIDÉO_VIDÉO

Icônes personnalisées

Les widgets DecoratedText et ButtonList vous permettent d'utiliser les icônes intégrées répertoriées ci-dessus ou de définir vos propres icônes personnalisées. Pour spécifier une icône personnalisée, utilisez l'élément iconUrl comme indiqué ci-dessous:

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

Limites et considérations

Lorsque vous êtes prêt à envoyer des messages de la carte, tenez compte de ces limites et considérations.

  • Les widgets suivants ne sont pas compatibles avec les messages de fiche, mais ils seront bientôt compatibles:

    • TextInput : champ dans lequel les utilisateurs peuvent saisir du texte.
    • SelectionInput, qui fournit un ensemble d'éléments sélectionnables, comme une liste de cases à cocher, des cases d'option, des contacteurs ou un menu déroulant.
    • DateTimePicker, qui permet aux utilisateurs de spécifier une date, une heure ou les deux.
    • Grid, qui présente un ensemble d'éléments dans une grille simple.