Ta strona została przetłumaczona przez Cloud Translation API.

Tworzenie interaktywnych dialogów

Na tej stronie opisano, jak aplikacja Google Chat może otwierać okna dialogowe, aby wyświetlać interfejsy użytkownika i na nie odpowiadać.

W Google Chat dodatki są widoczne dla użytkowników jako aplikacje Google Chat. Więcej informacji znajdziesz w artykule Omówienie rozszerzania Google Chat.

Dialogi to okna z interfejsami opartymi na kartach, które otwierają się z pokoju czatu lub wiadomości. Okno dialogowe i jego zawartość są widoczne tylko dla użytkownika, który je otworzył.

Aplikacje do czatu mogą używać dialogów do żądania i zbierania informacji od użytkowników czatu, w tym formularzy wieloetapowych. Więcej informacji o tworzeniu danych wejściowych formularza znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Wymagania wstępne

HTTP

Dodatek do Google Workspace, który rozszerza Google Chat. Aby utworzyć taki plik, wykonaj wprowadzenie do HTTP.

Google Apps Script

Dodatek do Google Workspace, który rozszerza Google Chat. Aby utworzyć skrypt, zapoznaj się z krótkim przewodnikiem po Apps Script.

Otwórz okno

Okno z różnymi widżetami. — **Ilustracja 1.**: Aplikacja Google Chat otwiera okno dialogowe do zbierania informacji kontaktowych.

**Ilustracja 1.**: Aplikacja Google Chat otwiera okno dialogowe do zbierania informacji kontaktowych.

W tej sekcji opisaliśmy, jak odpowiadać na pytania i jak konfigurować dialogy:

Wywołanie żądania dialogu w reakcji na interakcję użytkownika.
Rozwiąż prośbę, wracając do okna i otwierając okno dialogowe.
Gdy użytkownicy prześlą informacje, przetwórz dane, zamykając okno lub wyświetlając inne okno.

Wywołanie prośby o wyświetlenie okna

Aplikacja Google Chat może otwierać okna tylko w reakcji na interakcję użytkownika, np. polecenie lub kliknięcie przycisku w wiadomości na karcie.

Aby odpowiadać użytkownikom za pomocą okna dialogowego, aplikacja do czatu musi stworzyć interakcję, która uruchamia prośbę o dialog, na przykład:

Odpowiadanie na polecenie. Aby wywołać prośbę z poziomu polecenia, podczas konfigurowania polecenia musisz zaznaczyć pole wyboru Otwieranie okna dialogowego.
Reakcja na kliknięcie przycisku w wiadomości, czy to jako część karty, czy u dołu wiadomości. Aby wywołać prośbę za pomocą przycisku w wiadomości, skonfiguruj działanie onClick przycisku, ustawiając wartość parametru interaction na OPEN_DIALOG.

Przycisk wywołujący okno — **Rysunek 2.**: Aplikacja Google Chat wysyła wiadomość z prośbą o użycie polecenia `/addContact`.
Wiadomość zawiera też przycisk, który użytkownicy mogą kliknąć, aby wywołać polecenie.

Ten kod JSON pokazuje, jak wywołać prośbę o dialog z poziomu przycisku w wiadomości z kartą. Aby otworzyć okno, ustaw pole onClick.action.interaction przycisku na OPEN_DIALOG:

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

Gdzie BUTTON_TEXT to tekst wyświetlany na przycisku, a ACTION_FUNCTION to funkcja uruchamiająca początkowy dialog.

Otwórz pierwsze okno dialogowe

Gdy użytkownik wywoła prośbę o dialog, aplikacja Google Chat otrzyma obiekt zdarzenia z ładunkiem, który określa, że obiekt dialogEventType to REQUEST_DIALOG.

Aby otworzyć okno dialogowe, aplikacja Google Chat może odpowiedzieć na prośbę, zwracając obiekt RenderActions z nawigacją pushCard, aby wyświetlić kartę. Karta powinna zawierać dowolne elementy interfejsu, w tym co najmniej 1 sections[]widżet. Aby zbierać informacje od użytkowników, możesz użyć widżetów formularza i widżetu przycisku. Więcej informacji o projektowaniu pól formularza znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Ten kod JSON pokazuje, jak aplikacja Google Chat zwraca odpowiedź, która otwiera okno dialogowe:

{
  "action": { "navigations": [{ "pushCard": { "sections": [{ "widgets": [{
    WIDGETS,
    { "buttonList": { "buttons": [{
      "text": "BUTTON_TEXT",
      "onClick": {
        "action": { "function": "ACTION_FUNCTION" }
      }
    }]}}
  }]}]}}]}
}

Gdzie BUTTON_TEXT to tekst wyświetlany na przycisku (np. Next lub Submit), WIDGETS to co najmniej 1 element formularza do wprowadzania danych, a ACTION_FUNCTION to funkcja wywołania zwrotnego akcji, która jest wykonywana, gdy użytkownik kliknie przycisk.

Obsługa przesyłania okna dialogowego

Gdy użytkownicy klikną przycisk, który przesyła okno dialogowe, Twoja aplikacja czatu otrzyma obiekt zdarzenia z obiektem ButtonClickedPayload. W ładunku dialogEventType ma wartość SUBMIT_DIALOG. Aby dowiedzieć się, jak zbierać i przetwarzać informacje w ramach okna dialogowego, przeczytaj artykuł Zbieranie i przetwarzanie informacji od użytkowników Google Chat.

Aplikacja do czatu musi zareagować na obiekt zdarzenia, wykonując jedną z tych czynności:

Zwracanie innego okna, aby wypełnić inną kartę lub formularz.
Zamknij okno po zweryfikowaniu danych przesłanych przez użytkownika i opcjonalnie wyślij wiadomość z potwierdzeniem.

Opcjonalnie: zwracanie innego okna

Po przesłaniu przez użytkowników początkowego okna dialogowego aplikacje do czatu mogą wyświetlić jedno lub więcej dodatkowych okien, aby pomóc użytkownikom sprawdzić informacje przed ich przesłaniem, wypełnić formularze wieloetapowe lub dynamicznie wypełnić zawartość formularza.

Aby przetworzyć dane wprowadzone przez użytkowników, aplikacja Czat obsługuje dane w obiekcie zdarzenia commonEventObject.formInputs. Więcej informacji o pobieraniu wartości z widżetów z danymi wejściowymi znajdziesz w artykule Zbieranie i przetwarzanie informacji o użytkownikach.

Aby śledzić dane wprowadzane przez użytkowników w pierwszym oknie, musisz dodać parametry do przycisku, który otwiera następne okno. Szczegółowe informacje znajdziesz w artykule Przenoszenie danych na inną kartę.

W tym przykładzie aplikacja do czatu otwiera pierwsze okno dialogowe, które prowadzi do drugiego okna z potwierdzeniem przed przesłaniem:

Node.js

/**
 * Google Cloud Function that handles all Google Workspace Add On events for
 * the contact manager app.
 *
 * @param {Object} req Request sent from Google Chat space
 * @param {Object} res Response to send back
 */
exports.contactManager = function contactManager(req, res) {
  const chatEvent = req.body.chat;
  // Handle MESSAGE events
  if(chatEvent.messagePayload) {
    return res.send(handleMessage(req.body));
  // Handle button clicks
  } else if(chatEvent.buttonClickedPayload) {
    switch(req.body.commonEventObject.parameters.actionName) {
        case "openInitialDialog":
            return res.send(openInitialDialog(req.body));
        case "openConfirmationDialog":
            return res.send(openConfirmationDialog(req.body));
        case "submitDialog":
            return res.send(submitDialog(req.body));
    }
  }
};

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function handleMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openInitialDialog" }],
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{ key: "actionName", value: "openConfirmationDialog" }]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        // Use runtime environment variable set with self URL
        function: process.env.BASE_URL,
        parameters: [{
          key: "actionName", value: "submitDialog" }, {
          // Pass input values as parameters for last dialog step (submission)
          key: "contactName", value: name
        }]
      }}
    }]}}]
  }]}}]}};
}

Google Apps Script

W tym przykładzie wysyłamy wiadomość z karty, zwracając obiekt JSON karty. Możesz też użyć usługi karty w Apps Script.

/**
 * Responds to a message in Google Chat.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} response that handles dialogs.
 */
function onMessage(event) {
  // Reply with a message that contains a button to open the initial dialog
  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "To add a contact, use the `ADD CONTACT` button below.",
    accessoryWidgets: [{ buttonList: { buttons: [{
      text: "ADD CONTACT",
      onClick: { action: {
        function: "openInitialDialog",
        interaction: "OPEN_DIALOG"
      }}
    }]}}]
  }}}}};
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} open the dialog.
 */
function openInitialDialog(event) {
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    textInput: {
      name: "contactName",
      label: "First and last name",
      type: "SINGLE_LINE"
    }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "NEXT",
      onClick: { action: { function : "openConfirmationDialog" }}
    }]}}
  ]}]}}]}};
}

/**
 * Opens the second step of the dialog that lets users confirm details.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} update the dialog.
 */
function openConfirmationDialog(event) {
  // Retrieve the form input values
  const name = event.commonEventObject.formInputs["contactName"].stringInputs.value[0];
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [{
    // Display the input values for confirmation
    textParagraph: { text: "<b>Name:</b> " + name }},
    WIDGETS, {
    buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [{ key: "contactName", value: name }]
      }}
    }]}}]
  }]}}]}};
}

Gdzie WIDGETS reprezentuje dowolne inne widżety wprowadzania danych.

Zamknij okno

Gdy użytkownicy klikną przycisk przesyłania w oknie dialogowym, aplikacja Google Chat wykona powiązane z nim działanie i przekaże obiekt zdarzenia z parametrem buttonClickedPayload o tej wartości:

isDialogEvent to true.
dialogEventType to SUBMIT_DIALOG.

Aplikacja Google Chat powinna zwrócić obiekt RenderActions, w którym EndNavigationma wartość CLOSE_DIALOG.

Opcjonalnie: wyświetlenie tymczasowego powiadomienia

Po zamknięciu okna możesz też wyświetlić tymczasowe powiadomienie tekstowe użytkownikowi, który wchodzi w interakcję z aplikacją.

Aby wyświetlić powiadomienie, zwracaj obiekt RenderActions z ustawionym polem notification.

W tym przykładzie sprawdzamy, czy parametry są prawidłowe, i zamykamy okno z powiadomieniem tekstowym w zależności od wyniku:

Node.js

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Google Apps Script

/**
 * Handles submission and closes the dialog.
 *
 * @param {Object} event The event object from the Google Workspace add-on.
 * @return {Object} close the dialog with a status in text notification.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: "CLOSE_DIALOG"}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { action: {
    navigations: [{ endNavigation: "CLOSE_DIALOG"}],
    notification: { text: "Success, the contact was added!" }
  }};
}

Szczegółowe informacje o przekazywaniu parametrów między dialogami znajdziesz w artykule Przenoszenie danych na inną kartę.

Opcjonalnie: wysyłanie wiadomości z potwierdzeniem na czacie

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

Aby wysłać nową wiadomość, zwróć obiekt DataActions z polem CreateMessageAction zawierającym nową wiadomość. Aby na przykład zamknąć okno i wysłać SMS-a, zwracaj:

{ "hostAppDataAction": { "chatDataAction": { "createMessageAction": { "message": {
  "text": "Your information has been submitted."
}}}}}

Aby zaktualizować wiadomość po przesłaniu przez użytkownika okna dialogowego, zwróć obiekt DataActions zawierający jedną z tych czynności:

UpdateMessageAction: zaktualizuje wiadomość wysłaną przez aplikację Google Chat, na przykład wiadomość, z której użytkownik poprosił o dialog.
UpdateInlinePreviewAction: zaktualizuje kartę na podstawie podglądu linku.

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwróci błąd, interfejs Google Chat wyświetli komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs czatu nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta czatu powoduje nieoczekiwany wynik, na przykład może nie wyświetlać się wiadomość na karcie.

Komunikat o błędzie może się nie wyświetlać w interfejsie czatu, ale gdy włączone jest rejestrowanie błędów w przypadku aplikacji czatu, dostępne są opisowe komunikaty o błędach i dane dziennika, które ułatwiają ich rozwiązywanie. Informacje o wyświetlaniu, debugowaniu i poprawianiu błędów znajdziesz w artykule Rozwiązywanie problemów z błędami Google Chat.

Tworzenie interaktywnych dialogów Zadbaj o dobrą organizację dzięki kolekcji Zapisuj i kategoryzuj treści zgodnie ze swoimi preferencjami.

Wymagania wstępne

HTTP

Google Apps Script

Otwórz okno

Wywołanie prośby o wyświetlenie okna

Otwórz pierwsze okno dialogowe

Obsługa przesyłania okna dialogowego

Opcjonalnie: zwracanie innego okna

Node.js

Google Apps Script

Zamknij okno

Opcjonalnie: wyświetlenie tymczasowego powiadomienia

Node.js

Google Apps Script

Opcjonalnie: wysyłanie wiadomości z potwierdzeniem na czacie

Rozwiązywanie problemów

Tworzenie interaktywnych dialogów