Envoyer un message par carte

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:

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:

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

{
  "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:

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.

/**
 * 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],
      }
    }],
  };
}

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

/**
 * 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:

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:

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:

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:

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.