Otwórz interaktywne okna

Na tej stronie dowiesz się, jak Twoja aplikacja Google Chat może otwierać okna dialogowe na reakcję użytkownikom.

Okna to okna, interfejsy oparte na kartach. otwieranych z poziomu pokoju lub wiadomości. Okno i elementy treść jest widoczna tylko dla użytkownika, który ją otworzył.

Aplikacje do obsługi czatu mogą używać okien do wysyłania próśb o informacje i zbierania z nich informacji Użytkownicy czatu, w tym formularze wieloetapowe. Więcej informacji o tworzeniu danych wejściowych do formularza przeczytaj artykuł Zbieranie i przetwarzanie informacji od użytkowników.

Wymagania wstępne

Node.js

  • Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.

Python

  • Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć interaktywna aplikacja do obsługi czatu przy użyciu usługi HTTP zapoznaj się z tym krótkim wprowadzeniem.

Google Apps Script

  • Aplikacja Google Chat, w której można korzystać z funkcji interaktywnych. Aby utworzyć z interaktywną aplikacją Google Chat w Apps Script, zapoznaj się z tym krótkim wprowadzeniem.

Otwórz okno

Okno z różnymi różnymi widżetami.
Rysunek 1. Okno, które zbiera informacje kontaktowe.

W tej sekcji dowiesz się, jak odpowiadać i skonfigurować okno dialogowe, wykonując te czynności:

  1. Powoduje wywołanie żądania okna na podstawie interakcji użytkownika.
  2. Aby przetworzyć żądanie, wróć i otwórz okno.
  3. Gdy użytkownicy prześlą informacje, przetwórz zgłoszenie, zamykając lub zwrócenie innego okna.

Wywołaj żądanie wyświetlenia okna

Aplikacja do obsługi czatu może otwierać tylko okna, aby odpowiedzieć użytkownikowi np. polecenie po ukośniku lub kliknięcie przycisku z wiadomości na karcie.

Aby umożliwić użytkownikom odpowiadanie w oknie, aplikacja Google Chat musi utworzyć interakcję, która wyzwala żądanie wyświetlenia, na przykład:

  • Odpowiedz na polecenie po ukośniku. Aby aktywować żądanie za pomocą polecenia po ukośniku: musisz zaznaczyć pole wyboru Otwiera okno podczas konfigurowania polecenia.
  • Reaguj na kliknięcie przycisku w wiadomość, na karcie lub u dołu wiadomości. Aby uruchomić żądania za pomocą przycisku w wiadomości, skonfigurujesz onClick przycisku działanie przez ustawienie interaction na OPEN_DIALOG.
  • Reagowanie na kliknięcie przycisku na stronie głównej aplikacji Google Chat Więcej informacji o otwieraniu okien dialogowych na stronach głównych znajdziesz w artykule Tworzenie strony głównej aplikacji Google Chat
.
Przycisk wywołujący okno
Rysunek 2. Aplikacja do obsługi czatu wysyła wiadomość z prośbą o użycie polecenia po ukośniku /addContact.
Wiadomość zawiera również przycisk, który użytkownicy mogą kliknąć, aby wywołać polecenie.

Poniższy kod JSON pokazuje, jak wyzwalać żądanie okna za pomocą przycisku w wiadomości z karty. Aby otworzyć to okno, button.interaction pole jest ustawione na OPEN_DIALOG:

{
  "buttonList": { "buttons": [{
    "text": "BUTTON_TEXT",
    "onClick": { "action": {
      "function": "FUNCTION_NAME",
      "interaction": "OPEN_DIALOG"
    }}
  }]}
}

Gdzie BUTTON_TEXT to tekst wyświetlany na przycisku a FUNCTION_NAME to funkcja uruchamiana w celu otwarcia początkowego .

Otwórz pierwsze okno

Gdy użytkownik wywoła żądanie w oknie, aplikacja Google Chat odbiera zdarzenie interakcji, reprezentowane przez event wpisz Interfejs Chat API. Jeśli interakcja wyzwala żądanie wyświetlenia okna, tag zdarzenia Pole dialogEventType jest ustawione na REQUEST_DIALOG.

Aby otworzyć okno, aplikacja Google Chat może odpowiedzieć na przez zwrócenie actionResponse obiekt z type ustawionym na DIALOG i Message obiektu. Aby określić zawartość okna dialogowego, uwzględnij następujące elementy: obiekty:

  • actionResponse z wartością type ustawioną na DIALOG.
  • dialogAction obiektu. Pole body zawiera elementy interfejsu, dzięki którym wyświetlane na karcie, w tym sections widżetów. Aby zbierać informacje od użytkowników, możesz określić widżety do wprowadzania formularzy widżetem przycisku. Aby dowiedzieć się więcej o projektowaniu danych wejściowych w formularzu, zobacz Zbieranie i przetwarzanie informacji od użytkowników

Ten kod JSON pokazuje, jak zwraca się aplikacja Google Chat odpowiedź otwierającą okno:

{ "actionResponse": {
  "type": "DIALOG",
  "dialogAction": { "dialog": { "body": { "sections": [{
    "widgets": [{
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "BUTTON_TEXT",
        "onClick": {
          "action": {"function": "FUNCTION_NAME"}
        }
      }]}}
    }]
  }]}}}
}}

Gdzie BUTTON_TEXT to tekst, który wyświetla się na przycisku (np. Next lub Submit), WIDGETS oznacza co najmniej jeden widżety do wprowadzania danych oraz FUNCTION_NAME to funkcja uruchamiana po kliknięciu przycisku przez użytkownika.

Obsługa przesyłania okien

Gdy użytkownik kliknie przycisk powodujący wyświetlenie okna, Aplikacja do obsługi czatu otrzymuje interakcja CARD_CLICKED wydarzenie, w którym dialogEventType jest SUBMIT_DIALOG.

Aplikacja Google Chat musi obsłużyć zdarzenie interakcji do wykonując jedną z tych czynności:

  • Zwróć kolejne okno, aby wypełnić inną kartę lub formularza.
  • Po sprawdzeniu danych przesłanych przez użytkownika zamknij okno. opcjonalnie możesz wysłać wiadomość z potwierdzeniem.

Opcjonalnie: zwróć kolejne okno

Gdy użytkownicy prześlą pierwsze okno, aplikacje Google Chat będą zwraca co najmniej jedno dodatkowe okno, aby ułatwić użytkownikom przesyłać, wypełniać wieloetapowe formularze lub dynamicznie wypełniać zawartość formularzy.

Aby wczytać dane wprowadzone przez użytkowników w pierwszym oknie, musisz dodać do przycisku otwierającego następne okno lub przekazać pierwotną CARD_CLICKED zdarzenie interakcji z początkowego okna. Więcej informacji: Przenoszenie danych na inną kartę

W tym przykładzie aplikacja Google Chat otwiera okno, które zwraca drugie okno dialogowe przed przesłaniem. Aby wczytać dane wejściowe, funkcja Aplikacja do obsługi czatu przekazuje zdarzenie interakcji CARD_CLICKED jako parametr funkcji, która otwiera następne okno:

Node.js

// Respond to button clicks on attached cards
if (event.type === "CARD_CLICKED") {

  // Open the first dialog.
  if (event.common.invokedFunction === "openDialog") {
    openDialog(event);
  }

  // Open the second dialog.
  if (event.common.invokedFunction === "openNextDialog") {
    openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }});
};

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  res.json({ "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }});
}

Python

from typing import Any, Mapping

import flask
import functions_framework

@functions_framework.http
def main(req: flask.Request) -> Mapping[str, Any]:
  """Responds to a MESSAGE event in Google Chat that includes the /createContact
     slash command by opening a dialog.

  Args:
      req (flask.Request): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """

  if req.method == 'GET':
    return 'Sorry, this function must be called from a Google Chat.'

  request = req.get_json(silent=True)

  if request.get('type') == 'CARD_CLICKED':
    if invoked_function := request.get('common', dict()).get('invokedFunction'):
      if invoked_function == 'open_dialog':
        return open_dialog(request)

      elif invoked_function == 'open_next_dialog':
        return open_dialog(request)

def open_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a dialog in Google Chat.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "open_next_dialog"
        }}
      }]}}
    ]}]}}}
  }}

def open_next_dialog(request: Mapping[str, Any]) -> Mapping[str, Any]:
  """Opens a second dialog that lets users add more contact details.

  Args:
      request (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: open a Dialog in response to a card's button click.
  """
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submit_dialog"
          }}
        }]}
      }
    ]}]}}}
  }}

Google Apps Script

Ten przykładowy kod karty wysyła wiadomość przez zwrócenie card JSON. Możesz też użyć usługi Usługa karty Apps Script. 

/**
* Responds to a CARD_CLICKED event in Google Chat.
*
* @param {Object} event the event object from Google Chat
*/
function onCardClick(event) {

  // When a user clicks a card, the Chat app checks to see which function to run.
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  }

  if (event.common.invokedFunction === "openNextDialog") {
    return openNextDialog(event);
  }
}

/**
* Opens and starts a dialog that lets users add details about a contact.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      { "buttonList": { "buttons": [{
        "text": "Next",
        "onClick": { "action": {
          "function": "openNextDialog"
        }}
      }]}}
    ]}]}}}
  }};
}

/**
* Opens a second dialog that lets users add more contact details.
*
* @param {object} event the event object from Google Chat.
*
* @return {object} open a dialog.
*/
function openNextDialog(event) {
  return { "actionResponse": {
    "type": "DIALOG",
    "dialogAction": { "dialog": { "body": { "sections": [{ "widgets": [
      WIDGETS,
      {
        "horizontalAlignment": "END",
        "buttonList": { "buttons": [{
          "text": "Submit",
          "onClick": { "action": {
            "function": "submitDialog"
          }}
        }]}
      }
    ]}]}}}
  }};
}

Gdzie WIDGETS reprezentuje co najmniej jeden widżety do wprowadzania danych.

Zamknij okno

Gdy użytkownik kliknie przycisk w oknie, Aplikacja do obsługi czatu odbiera zdarzenie interakcji z urządzeniem następujące informacje:

W sekcjach poniżej wyjaśniamy, jak sprawdzać dane wprowadzane przez użytkowników Zamknij to okno.

Sprawdź dane wejściowe użytkownika i zamknij okno

Do przetwarzania danych wprowadzonych przez użytkowników aplikacja Google Chat korzysta z funkcji event.common.formInputs obiektu. Więcej informacji o pobieraniu wartości z widżetów wejściowych znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników

Jeśli użytkownik pominie wymagane pole lub wpisze nieprawidłowe wartości, Aplikacja do obsługi czatu może odpowiedzieć z błędem, zwracając ActionResponse który zawiera "actionStatus": "ERROR MESSAGE".

W tym przykładzie sprawdzamy, czy użytkownik wpisał wartość dla widżetu, który akceptuje ciągi tekstowe (stringInputs), takie jak widżet textInput. Jeśli go nie podasz, Aplikacja do obsługi czatu zwraca błąd. Jeśli istnieje, aplikacja Google Chat potwierdzi przesłanie okna i zamyka okno dialogowe:

Node.js

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {Object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME.stringInputs.value[0] === "") {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    });

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    res.json({
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    });
  }
}

Python

def receive_dialog(event: Mapping[str, Any]) -> Mapping[str, Any]:
  """Checks for a form input error, the absence of a "name" value, and returns
     an error if absent. Otherwise, confirms successful receipt of a dialog.

  Args:
      event (Mapping[str, Any]): the event object from Chat API.

  Returns:
      Mapping[str, Any]: the response.
  """

  if common := event.get('common'):
    if form_inputs := common.get('formInputs'):
      if contact_name := form_inputs.get('WIDGET_NAME'):
        if string_inputs := contact_name.get('stringInputs'):
          if name := string_inputs.get('value')[0]:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'OK'
                }
              }
            }
          else:
            return {
              'actionResponse': {
                'type': 'DIALOG',
                'dialogAction': {
                  'actionStatus': 'ERROR_MESSAGE'
                }
              }
            }

Google Apps Script

Ten przykładowy kod karty wysyła wiadomość przez zwrócenie card JSON. Możesz też użyć usługi Usługa karty Apps Script. 

/**
* Checks for a form input error, the absence of
* a "name" value, and returns an error if absent.
* Otherwise, confirms successful receipt of a dialog.
*
* Confirms successful receipt of a dialog.
*
* @param {Object} event the event object from Chat API.
*
* @return {object} open a Dialog in Google Chat.
*/
function submitDialog(event) {

  // Checks to make sure the user entered a value
  // in a dialog. If no value detected, returns
  // an error message. Any "actionStatus" value other than "OK"
  // gets returned as an error.
  if (event.common.formInputs.WIDGET_NAME[""].stringInputs.value[0] === "") {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "ERROR_MESSAGE"
        }
      }
    };

    // Otherwise the Chat app indicates that it received
    // form data from the dialog. An "actionStatus" of "OK" is
    // interpreted as code 200, and the dialog closes.
  } else {
    return {
      "actionResponse": {
        "type": "DIALOG",
        "dialogAction": {
          "actionStatus": "OK"
        }
      }
    };
  }
}

W tym przykładzie WIDGET_NAME reprezentuje pole name parametru (takie jak contactName), a ERROR_MESSAGE reprezentuje treść komunikatu o błędzie (np. Don't forget to name your contact). Szczegółowe informacje na temat przetwarzania danych wejściowych z widżetów znajdziesz w sekcji Otrzymywanie danych z interaktywnych widżetów.

Opcjonalnie: wyślij wiadomość z potwierdzeniem

Po zamknięciu okna możesz też wysłać nową wiadomość lub zaktualizować już istnieje.

Aby wysłać nową wiadomość, zwróć ActionResponse obiekt z type ustawionym na NEW_MESSAGE. Aby na przykład zamknąć okno i wyślij SMS-a, zwróć:

  {
    "actionResponse": {
      "type": "NEW_MESSAGE",
    },
    "text": "Your information has been submitted."
  }

Aby zaktualizować wiadomość, zwróć obiekt actionResponse zawierający zaktualizowany komunikat i ustawia type na jedną z tych wartości:

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub card zwraca błąd, Interfejs czatu wyświetla komunikat „Coś poszło nie tak”. lub „Nie można przetworzyć żądania”. Czasami interfejs Google Chat nie wyświetla się żaden komunikat o błędzie, ale aplikacja Google Chat lub zwraca nieoczekiwany wynik; na przykład wiadomość w formie karty .

Komunikat o błędzie może nie wyświetlać się w interfejsie Google Chat, opisowe komunikaty o błędach i dane dziennika, które pomogą Ci w naprawianiu błędów gdy logowanie błędów aplikacji Google Chat jest włączone. Aby uzyskać pomoc w wyświetlaniu, debugowania i naprawiania błędów, zapoznaj się z artykułem Rozwiązywanie problemów z błędami w Google Chat