Invia il messaggio di una scheda

Oltre agli messaggi di testo, le app di chat possono inviare messaggi relativi alle schede negli spazi e agli utenti. Le schede supportano un layout definito, elementi UI interattivi come pulsanti e rich media come immagini.

Utilizza i messaggi delle schede per:

  • Presentare informazioni dettagliate
  • Raccogliere informazioni dagli utenti
  • Guida gli utenti a un passaggio successivo

Questa guida descrive come inviare messaggi in modo sincrono (una risposta in tempo reale a un evento di Chat, come la ricezione di un messaggio da un utente o l'aggiunta a uno spazio) e in modo asincrono (invio di un messaggio dall'app a uno spazio o un utente senza un messaggio utilizzando l'API Chat REST).

Prerequisiti

Per inviare i messaggi in questa guida, occorre quanto segue:

Node.js

Python

Apps Script

Anatomia di un messaggio relativo a una scheda

Ogni scheda, che sia una finestra di dialogo o un messaggio, è un oggetto JSON nella risorsa spaces.messages nell'API Chat.

L'oggetto JSON della scheda è costituito dai seguenti elementi:

  1. Un array chiamato cardsV2[] che contiene uno o più oggetti CardWithId.
  2. cardId, utilizzato per identificare la scheda e l'ambito all'interno di un determinato messaggio. Le schede di messaggi diversi possono avere lo stesso ID.
  3. Un oggetto card, costituito da:

    • Un oggetto header che specifica elementi quali il titolo, il sottotitolo e l'immagine in stile avatar.
    • Uno o più oggetti section che contengono almeno un widget.
    • Uno o più oggetti widget. Ciascun widget è un oggetto composto che può rappresentare testo, immagini, pulsanti e altri tipi di oggetti.

      I seguenti widget sono supportati nei messaggi delle schede e nelle finestre di dialogo:

      • TextParagraph: visualizza un paragrafo di testo con una formattazione HTML semplice facoltativa.
      • Image: mostra un'immagine .PNG o .JPG cliccabile o statica ospitata su un URL HTTPS.
      • DecoratedText: mostra il testo con funzionalità facoltative di layout e funzionalità, come icone e pulsanti.
      • ButtonList: mostra un insieme di pulsanti.

      I seguenti widget sono supportati nelle finestre di dialogo (a breve saranno supportati i messaggi relativi alle schede):

      • TextInput: campo in cui gli utenti possono inserire testo.
      • SelectionInput: fornisce una serie di elementi selezionabili, come un elenco di caselle di controllo, pulsanti di opzione, opzioni o un menu a discesa.

      • Divider: mostra una linea orizzontale che si estende per tutta la larghezza di una scheda tra widget in pila, fungendo da separatore visivo.

      • Grid: disposte un insieme di elementi in una griglia semplice.

      Il seguente widget sarà presto disponibile:

      • DateTimePicker: consente agli utenti di specificare una data, un'ora o entrambe le cose.

Ad esempio, osserva gli oggetti header, section e widget nel seguente messaggio relativo alla scheda:

Un'app di chat che esegue un sondaggio in uno spazio di Chat utilizzando un messaggio relativo a una scheda

Il codice seguente rappresenta il JSON del messaggio della scheda:

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

Inviare un messaggio della scheda sincrona

In questo esempio, un utente invia un messaggio in Google Chat all'app Chat e l'app risponde inviando un semplice messaggio con scheda sincrona che mostra il nome e l'immagine dell'avatar del mittente:

L&#39;app di chat risponde con una scheda contenente il nome visualizzato e l&#39;immagine dell&#39;avatar del mittente

Nei seguenti esempi di codice, le app Node.js e Python sono ospitate in Google Cloud Functions. L'esempio di Apps Script è ospitato su Google Apps Script.

Per istruzioni complete su come creare ed eseguire il deployment di un'app Chat, vedi Creare un'app Chat.

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

Python

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  

Apps Script

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

Inviare un messaggio della scheda asincrono con l'API Chat

Questo esempio crea in modo asincrono un messaggio con l'API Chat e lo invia a uno spazio a cui viene aggiunta l'app Chat, come quella mostrata di seguito:

Un messaggio scheda creato con l&#39;API REST di Chat.
Figura 1: un messaggio sulla scheda creato con l'API Chat REST.

Python

  1. Nella directory di lavoro, crea un file denominato chat_create_card_message.py.
  2. Includi il seguente codice in 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. Nel codice, sostituisci SPACE con un nome di spazio, che puoi ottenere dal metodo spaces.list() nell'API Chat o dall'URL di uno spazio.

  4. Nella directory di lavoro, crea ed esegui l'esempio:

    python3 chat_create_card_message.py
    

Per scoprire di più sull'utilizzo dei messaggi nell'API REST di Chat, vedi Creare, leggere, aggiornare ed eliminare i messaggi.

Apri una finestra di dialogo

Le finestre di dialogo sono finestre basate su schede che le app di chat aprono per interagire con gli utenti. Per aiutare gli utenti a completare processi con più passaggi, le app possono aprire finestre di dialogo sequenziali. Le app possono aprire le finestre di dialogo in risposta a un clic sul pulsante su un messaggio della scheda o in risposta a un comando slash.

Le finestre di dialogo sono utili per molti tipi di interazioni degli utenti, tra cui:

  • Raccolta di informazioni dagli utenti
  • Autenticazione degli utenti con i servizi web
  • Configurazione delle impostazioni dell'app Chat

In questo esempio, un'app di chat apre una finestra di dialogo per aiutare un utente a creare un nuovo contatto per la propria rubrica:

Una finestra di dialogo con una varietà di widget.

Per implementare le finestre di dialogo, vedi Aprire le finestre di dialogo.

Formattazione della scheda

Formattazione del testo della scheda

All'interno delle schede, la maggior parte dei campi di testo supporta la formattazione di base del testo tramite un piccolo sottoinsieme di tag HTML. I tag supportati e il relativo scopo sono riportati nella tabella riportata di seguito:

Grassetto <b> Corsivo <i>
Sottolineato <> Barrato <avvertimento>
Colore carattere <font color=""> Link ipertestuale <a href="">
Interruzione di riga <br>

Tieni presente che il corpo del testo di un messaggio di base viene analizzato utilizzando una sintassi di markup diversa, ottimizzata per gli utenti umani. Per maggiori dettagli, vedi Inviare un SMS.

Icone integrate

I widget DecoratedText e ButtonList supportano l'elemento icon utilizzato per specificare una delle icone integrate disponibili in Google Chat:

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

Nella tabella seguente sono elencate le icone integrate disponibili per i messaggi delle schede:

Aereo SEGNALIBRO
Autobus CAR
OROLOGIO CONFIRMATION_NUMBER_ICON
DESCRIPTION DOLLARE
EMAIL EVENT_SEAT
Volo di arrivo Volo_partenza
HOTEL TIPO_SALA_HOTEL
INVITA PIN_MAP
ABBONAMENTO MULTIPLE_PERSONE
PERSONA TELEFONO
RESTAURANT_ICON SHOPPING_CART
STELLA NEGOZIO
BIGLIETTO TRENO
VIDEO_CAMERA VIDEO_PLAY

Icone personalizzate

I widget DecoratedText e ButtonList ti consentono di utilizzare le icone integrate elencate in precedenza o di definire le tue icone personalizzate. Per specificare un'icona personalizzata, utilizza l'elemento iconUrl come mostrato di seguito:

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

Limiti e considerazioni

Quando inizi a inviare i messaggi relativi alle carte, tieni presente questi limiti e considerazioni.

  • I seguenti widget non sono supportati dai messaggi nelle schede, ma saranno supportati a breve:

    • TextInput, un campo in cui gli utenti possono inserire testo.
    • SelectionInput, che fornisce una serie di elementi selezionabili, come un elenco di caselle di controllo, pulsanti di opzione, opzioni o un menu a discesa.
    • DateTimePicker, che consente agli utenti di specificare una data, un'ora o entrambe le cose.
    • Grid, che mostra un insieme di elementi in una griglia semplice.