Tworzenie interaktywnych dialogów

Na tej stronie dowiesz się, jak aplikacja Google Chat może otwierać okna, aby wyświetlać interfejsy i odpowiadać na działania użytkowników.

Okna dialogowe to interfejsy okienkowe oparte 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ć okien dialogowych do wysyłania próśb o informacje od użytkowników Google Chat i ich zbierania, w tym formularzy wieloetapowych. Więcej informacji o tworzeniu pól 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 go utworzyć, wykonaj czynności opisane w tym przewodniku.

Google Apps Script

Dodatek do Google Workspace, który rozszerza Google Chat. Aby go utworzyć, wykonaj czynności opisane w krótkim przewodniku po Apps Script.

Otwórz okno

Okno z różnymi widżetami.
Ilustracja 1. Aplikacja Google Chat, która otwiera okno dialogowe do zbierania informacji kontaktowych.

W tej sekcji dowiesz się, jak odpowiadać na wiadomości i konfigurować dialogi, wykonując te czynności:

  1. Wywołaj prośbę o okno z interakcji użytkownika.
  2. Obsłuż żądanie, zwracając i otwierając okno.
  3. Po przesłaniu przez użytkowników informacji przetwórz je, zamykając okno lub wyświetlając inne okno.

Wywoływanie prośby o okno

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

Aby odpowiadać użytkownikom za pomocą okna, aplikacja Chat musi utworzyć interakcję, która wywołuje żądanie okna, np.:

  • Odpowiadaj na polecenia. Aby wywołać żądanie za pomocą polecenia, podczas konfigurowania polecenia musisz zaznaczyć pole wyboru Otwiera okno.
  • Odpowiadanie na kliknięcie przycisku w wiadomości, w ramach karty lub u dołu wiadomości. Aby wywołać żądanie za pomocą przycisku w wiadomości, skonfiguruj działanie onClick przycisku, ustawiając jego parametr interaction na OPEN_DIALOG.
Przycisk, który otwiera okno
Ilustracja 2. Aplikacja Google Chat wysyła wiadomość, która zachęca użytkowników do użycia /addContact polecenia z ukośnikiem.
Wiadomość zawiera też przycisk, który użytkownicy mogą kliknąć, aby wywołać polecenie.

Poniższy kod JSON pokazuje, jak wywołać żądanie okna z przycisku w wiadomości na karcie. 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, która otwiera początkowe okno dialogowe.

Otwórz pierwsze okno dialogowe

Gdy użytkownik wywoła żądanie okna, aplikacja do obsługi czatu otrzyma obiekt zdarzenia z ładunkiem, który określa, że obiekt dialogEventType jest REQUEST_DIALOG.

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

Poniższy kod JSON pokazuje, jak aplikacja w Google Chat zwraca odpowiedź, która otwiera okno:

{   "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 widżet wprowadzania danych w formularzu, a ACTION_FUNCTION to funkcja wywołania zwrotnego działania, która jest uruchamiana, gdy użytkownicy klikną przycisk.

Obsługa przesłania okna

Gdy użytkownicy klikną przycisk, który przesyła okno, aplikacja do obsługi czatu otrzyma obiekt zdarzenia z obiektem ButtonClickedPayload. W ładunku wartość parametru dialogEventType jest ustawiona na SUBMIT_DIALOG. Aby dowiedzieć się, jak zbierać i przetwarzać informacje w oknie, przeczytaj artykuł Zbieranie i przetwarzanie informacji od użytkowników Google Chat.

Aplikacja do obsługi czatu musi odpowiedzieć na obiekt zdarzenia, wykonując jedną z tych czynności:

  • Zwróć kolejne okno, aby wypełnić kolejną kartę lub formularz.
  • Zamknij okno po sprawdzeniu danych przesłanych przez użytkownika i opcjonalnie wyślij wiadomość z potwierdzeniem.

Opcjonalnie: zwracanie innego okna

Po przesłaniu początkowego okna dialogowego aplikacje w Chat mogą zwracać jedno lub więcej dodatkowych okien dialogowych, aby pomóc użytkownikom w sprawdzeniu informacji przed przesłaniem, wypełnianiu formularzy wieloetapowych lub dynamicznym wypełnianiu treści formularza.

Aby przetwarzać dane wprowadzane przez użytkowników, aplikacja Chat obsługuje je w obiekcie commonEventObject.formInputs zdarzenia. Więcej informacji o pobieraniu wartości z widżetów wejściowych znajdziesz w artykule Zbieranie i przetwarzanie informacji od użytkowników.

Aby śledzić dane wprowadzane przez użytkowników w początkowym oknie, musisz dodać parametry do przycisku, który otwiera następne okno. Więcej informacji znajdziesz w sekcji Przenoszenie danych na inną kartę.

W tym przykładzie aplikacja do obsługi czatu otwiera początkowe okno, które prowadzi do drugiego okna z prośbą o potwierdzenie 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łana jest wiadomość z kartą przez zwrócenie kodu JSON karty. Możesz też użyć usługi kart 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 oznacza dowolny inny widżet wejściowy formularza.

Zamknij okno

Gdy użytkownicy klikną przycisk przesyłania w oknie dialogowym, aplikacja do czatu wykona powiązane z nim działanie i przekaże obiekt zdarzenia z parametrem buttonClickedPayload ustawionym na:

  • isDialogEvent to true.
  • dialogEventType to SUBMIT_DIALOG.

Aplikacja do obsługi czatu powinna zwrócić obiekt RenderActions z wartością EndNavigation ustawioną na CLOSE_DIALOG.

Opcjonalnie: wyświetlanie tymczasowego powiadomienia

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

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

W tym przykładzie sprawdzamy, czy parametry są prawidłowe, i zamykamy okno dialogowe 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 oknami znajdziesz w artykule Przekazywanie 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ć istniejącą.

Aby wysłać nową wiadomość, zwróć obiekt DataActions z polem CreateMessageAction ustawionym na nową wiadomość. Aby na przykład zamknąć okno i wysłać SMS-a, zwróć te wartości:

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

Aby zaktualizować wiadomość po przesłaniu przez użytkownika okna, zwróć obiekt DataActions, który zawiera jedno z tych działań:

Rozwiązywanie problemów

Gdy aplikacja Google Chat lub karta zwraca błąd, w interfejsie Google Chat pojawia się komunikat „Coś poszło nie tak”. lub „Nie udało się przetworzyć Twojej prośby”. Czasami interfejs Google Chat nie wyświetla żadnego komunikatu o błędzie, ale aplikacja lub karta Google Chat daje nieoczekiwany wynik, np. wiadomość na karcie może się nie pojawić.

Chociaż w interfejsie czatu może nie wyświetlać się komunikat o błędzie, opisowe komunikaty o błędach i dane logowania są dostępne, aby pomóc w naprawieniu błędów, gdy rejestrowanie błędów w aplikacjach na czat jest włączone. Pomoc dotyczącą wyświetlania, debugowania i naprawiania błędów znajdziesz w artykule Rozwiązywanie problemów z Google Chat.