Zbieranie kontaktów w Google Chat i zarządzanie nimi

Z tego samouczka dowiesz się, jak stworzyć aplikację Google Chat, która pomoże użytkownikom tej usługi zarządzać kontaktami osobistymi i biznesowymi. Aby zbierać informacje, aplikacja Google Chat prosi użytkowników o wypełnienie formularza kontaktowego w komunikatach i oknach dialogowych na karcie.

Zobacz, jak działa aplikacja Google Chat:

  • Formularz kontaktowy z polecenia po ukośniku.
    Rysunek 1. Aplikacja Google Chat odpowiada na polecenie po ukośniku /about, wysyłając wiadomość tekstową i przycisk, który otwiera formularz kontaktowy.
  • Formularz kontaktowy w oknie.
    Rysunek 2. Aplikacja Chat otwiera okno, w którym użytkownicy mogą podać informacje o kontaktach.
  • Okno potwierdzenia i sprawdzenia.
    Rysunek 3. Aplikacja Google Chat zwraca okno potwierdzenia, w którym użytkownicy mogą sprawdzić i potwierdzić informacje przed ich przesłaniem.
  • SMS z potwierdzeniem utworzenia nowego kontaktu.
    Rysunek 4. Gdy użytkownik prześle formularz, aplikacja Google Chat wyśle prywatną wiadomość tekstową z potwierdzeniem.
  • Formularz kontaktowy z wiadomości na karcie.
    Rysunek 5. Aplikacja Google Chat prosi też użytkowników o dodanie kontaktu z karty w wiadomości.

Wymagania wstępne

Cele

Architektura

Aplikacja Google Chat jest zbudowana w Google Apps Script i używa zdarzeń interakcji do przetwarzania i odpowiadania użytkownikom Google Chat.

Poniżej znajdziesz typowe interakcje użytkowników z aplikacją Google Chat:

  1. Użytkownik otwiera czat w aplikacji Google Chat lub dodaje aplikację Google Chat do istniejącego pokoju.

  2. Aplikacja Google Chat prosi użytkownika o dodanie kontaktu, tworząc i wyświetlając formularz kontaktowy jako obiekt card. Aby wyświetlić formularz kontaktowy, aplikacja Google Chat reaguje na użytkowników w następujące sposoby:

    • odpowiada na @wzmianki i wiadomości bezpośrednie za pomocą wiadomości z kartą zawierającą formularz kontaktowy.
    • Reaguje na polecenie /addContact, otwierając okno z formularzem kontaktowym.
    • Reaguje na polecenie /about wiadomością tekstową zawierającą przycisk Dodaj kontakt, który użytkownicy mogą kliknąć, aby otworzyć okno z formularzem kontaktowym.

  3. Gdy użytkownik zobaczy formularz kontaktowy, wprowadzi swoje dane kontaktowe w tych polach i widżetach:

    • Imię i nazwisko: widżet textInput, który akceptuje ciągi znaków.
    • Data urodzenia: dateTimePicker widżet, który akceptuje tylko daty.
    • Typ kontaktu: widżet selectionInput z przyciskami, które pozwalają użytkownikom wybrać i przesłać wartość w postaci pojedynczego ciągu znaków (Personal lub Work).
    • Przycisk Sprawdź i prześlij: tablica buttonList z widżetem button, który użytkownik klika, aby przesłać wpisane przez siebie wartości.

  4. Aplikacja Google Chat obsługuje zdarzenie interakcji CARD_CLICKED, aby przetworzyć wartości wpisane przez użytkownika, i wyświetla je na karcie potwierdzenia.

  5. Użytkownik sprawdza kartę potwierdzenia i klika przycisk Prześlij, aby sfinalizować informacje kontaktowe.

  6. Aplikacja Google Chat wysyła prywatną wiadomość tekstową, która potwierdza przesłanie.

Przygotowywanie środowiska

Z tej sekcji dowiesz się, jak utworzyć i skonfigurować projekt Google Cloud dla aplikacji Google Chat.

Tworzenie projektu Google Cloud

Google Cloud Console

  1. W konsoli Google Cloud kliknij Menu > Administracja > Utwórz projekt.

    Otwórz stronę Tworzenie projektu

  2. W polu Nazwa projektu wpisz nazwę projektu.

    Opcjonalnie: aby edytować identyfikator projektu, kliknij Edytuj. Po utworzeniu projektu nie można zmienić jego identyfikatora. Wybierz więc identyfikator, który będzie odpowiadał Twoim potrzebom przez cały czas trwania projektu.

  3. W polu Lokalizacja kliknij Przeglądaj, aby wyświetlić potencjalne lokalizacje dla Twojego projektu. Następnie kliknij Wybierz.
  4. Kliknij Utwórz. Konsola Google Cloud przejdzie do strony Panelu, a Twój projekt zostanie utworzony w ciągu kilku minut.

interfejs wiersza poleceń gcloud

W jednym z tych środowisk programistycznych uzyskaj dostęp do Google Cloud CLI (gcloud):

  • Cloud Shell: aby korzystać z terminala online z już skonfigurowanym interfejsem gcloud CLI, aktywuj Cloud Shell.
    Aktywuj Cloud Shell
  • Interfejs lokalny: aby korzystać z lokalnego środowiska programistycznego, zainstaluj i inicjuj interfejs wiersza poleceń gcloud.
    Aby utworzyć projekt Cloud, użyj polecenia gcloud projects create: 
    gcloud projects create PROJECT_ID
    Zastąp PROJECT_ID identyfikatorem projektu, który chcesz utworzyć.

Konfigurowanie uwierzytelniania i autoryzacji

Aplikacje Google Chat wymagają skonfigurowania ekranu zgody OAuth, aby użytkownicy mogli autoryzować Twoją aplikację w aplikacjach Google Workspace, w tym w Google Chat.

W tym samouczku wdrożysz aplikację czatu, która służy tylko do testowania i użytku wewnętrznego, więc możesz użyć informacji zastępczych na ekranie zgody. Przed opublikowaniem aplikacji Chat zastąp wszystkie informacje zastępcze prawdziwymi informacjami.

  1. W konsoli Google Cloud kliknij Menu  > Interfejsy API i usługi > Ekran zgody OAuth.

    Otwórz ekran zgody OAuth

  2. W sekcji Typ użytkownika wybierz Wewnętrzny, a potem kliknij Utwórz.

  3. W polu Nazwa aplikacji wpisz Contact Manager.

  4. W polu Adres e-mail użytkownika wybierz swój adres e-mail lub odpowiednią grupę Google.

  5. W sekcji Dane kontaktowe dewelopera wpisz swój adres e-mail.

  6. Kliknij Zapisz i kontynuuj.

  7. Na stronie Zakresy kliknij Zapisz i kontynuuj. (aplikacja Chat nie wymaga żadnych zakresów OAuth).

  8. Sprawdź podsumowanie i kliknij Powrót do panelu.

Tworzenie i wdrażanie aplikacji Google Chat

W tej sekcji skopiujesz i zaktualizujesz cały projekt Apps Script zawierający cały kod aplikacji wymagany przez aplikację Google Chat, nie musisz więc kopiować i wklejać poszczególnych plików.

Opcjonalnie możesz wyświetlić cały projekt na GitHubie.

Wyświetl w GitHubie

Oto omówienie poszczególnych plików:

main.gs

Obsługuje całą logikę aplikacji, w tym zdarzenia interakcji, gdy użytkownicy wysyłają wiadomości do aplikacji do obsługi czatu, klikają przyciski w wiadomościach w aplikacji do obsługi czatu lub otwierają i zamykają okna dialogowe.

Wyświetl kod aplikacji main.gs

apps-script/contact-form-app/main.gs
/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * Responds to a MESSAGE interaction event in Google Chat.
 *
 * @param {Object} event the MESSAGE interaction event from Chat API.
 * @return {Object} message response that opens a dialog or sends private
 *                          message with text and card.
 */
function onMessage(event) {
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1:
        // If the slash command is "/about", responds with a text message and button
        // that opens a dialog.
        return {
          text: "Manage your personal and business contacts 📇. To add a " +
                  "contact, use the slash command `/addContact`.",
          accessoryWidgets: [{
            buttonList: { buttons: [{
              text: "Add Contact",
              onClick: { action: {
                function: "openInitialDialog",
                interaction: "OPEN_DIALOG"
              }}
            }]}
          }]
        }
      case 2:
        // If the slash command is "/addContact", opens a dialog.
        return openInitialDialog();
    }
  }

  // If user sends the Chat app a message without a slash command, the app responds
  // privately with a text and card to add a contact.
  return {
    privateMessageViewer: event.user,
    text: "To add a contact, try `/addContact` or complete the form below:",
    cardsV2: [{
      cardId: "addContactForm",
      card: {
        header: { title: "Add a contact" },
        sections:[{ widgets: CONTACT_FORM_WIDGETS.concat([{
          buttonList: { buttons: [{
            text: "Review and submit",
            onClick: { action: { function : "openConfirmation" }}
          }]}
        }])}]
      }
    }]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @return {Object} message responses specific to the dialog handling.
 */
function onCardClick(event) {
  // Initial dialog form page
  if (event.common.invokedFunction === "openInitialDialog") {
    return openInitialDialog();
  // Confirmation dialog form page
  } else if (event.common.invokedFunction === "openConfirmation") {
    return openConfirmation(event);
  // Submission dialog form page
  } else if (event.common.invokedFunction === "submitForm") {
    return submitForm(event);
  }
}

/**
 * Opens the initial step of the dialog that lets users add contact details.
 *
 * @return {Object} a message with an action response to open a dialog.
 */
function openInitialDialog() {
  return { actionResponse: {
    type: "DIALOG",
    dialogAction: { dialog: { body: { sections: [{
      header: "Add new contact",
      widgets: CONTACT_FORM_WIDGETS.concat([{
        buttonList: { buttons: [{
          text: "Review and submit",
          onClick: { action: { function: "openConfirmation" }}
        }]}
      }])
    }]}}}
  }};
}

/**
 * Returns the second step as a dialog or card message that lets users confirm details.
 *
 * @param {Object} event the interactive event with form inputs.
 * @return {Object} returns a dialog or private card message.
 */
function openConfirmation(event) {
  const name = fetchFormValue(event, "contactName") ?? "";
  const birthdate = fetchFormValue(event, "contactBirthdate") ?? "";
  const type = fetchFormValue(event, "contactType") ?? "";
  const cardConfirmation = {
    header: "Your contact",
    widgets: [{
      textParagraph: { text: "Confirm contact information and submit:" }}, {
      textParagraph: { text: "<b>Name:</b> " + name }}, {
      textParagraph: {
        text: "<b>Birthday:</b> " + convertMillisToDateString(birthdate)
      }}, {
      textParagraph: { text: "<b>Type:</b> " + type }}, {
      buttonList: { buttons: [{
        text: "Submit",
        onClick: { action: {
          function: "submitForm",
          parameters: [{
            key: "contactName", value: name }, {
            key: "contactBirthdate", value: birthdate }, {
            key: "contactType", value: type
          }]
        }}
      }]}
    }]
  };

  // Returns a dialog with contact information that the user input.
  if (event.isDialogEvent) {
    return { action_response: {
      type: "DIALOG",
      dialogAction: { dialog: { body: { sections: [ cardConfirmation ]}}}
    }};
  }

  // Updates existing card message with contact information that the user input.
  return {
    actionResponse: { type: "UPDATE_MESSAGE" },
    privateMessageViewer: event.user,
    cardsV2: [{
      card: { sections: [cardConfirmation]}
    }]
  }
}

/**
  * Validates and submits information from a dialog or card message
  * and notifies status.
  *
  * @param {Object} event the interactive event with parameters.
  * @return {Object} a message response that opens a dialog or posts a private
  *                  message.
  */
function submitForm(event) {
  const contactName = event.common.parameters["contactName"];
  // Checks to make sure the user entered a contact name.
  // If no name value detected, returns an error message.
  if (!contactName) {
    const errorMessage = "Don't forget to name your new contact!";
    if (event.dialogEventType === "SUBMIT_DIALOG") {
      return { actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "INVALID_ARGUMENT",
          userFacingMessage: errorMessage
        }}
      }};
    } else {
      return {
        privateMessageViewer: event.user,
        text: errorMessage
      };
    }
  }

  // The Chat app indicates that it received form data from the dialog or card.
  // Sends private text message that confirms submission.
  const confirmationMessage = "✅ " + contactName + " has been added to your contacts.";
  if (event.dialogEventType === "SUBMIT_DIALOG") {
    return {
      actionResponse: {
        type: "DIALOG",
        dialogAction: { actionStatus: {
          statusCode: "OK",
          userFacingMessage: "Success " + contactName
        }}
      }
    }
  } else {
    return {
      actionResponse: { type: "NEW_MESSAGE" },
      privateMessageViewer: event.user,
      text: confirmationMessage
    };
  }
}

/**
 * Extracts form input value for a given widget.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat.
 * @param {String} widgetName a unique ID for the widget, specified in the widget's name field.
 * @returns the value inputted by the user, null if no value can be found.
 */
function fetchFormValue(event, widgetName) {
  const formItem = event.common.formInputs[widgetName][""];
  // For widgets that receive StringInputs data, the value input by the user.
  if (formItem.hasOwnProperty("stringInputs")) {
    const stringInput = event.common.formInputs[widgetName][""].stringInputs.value[0];
    if (stringInput != null) {
      return stringInput;
    }
  // For widgets that receive dateInput data, the value input by the user.
  } else if (formItem.hasOwnProperty("dateInput")) {
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;
     if (dateInput != null) {
       return dateInput;
     }
  }

  return null;
}

/**
 * Converts date in milliseconds since epoch to user-friendly string.
 *
 * @param {Object} millis the milliseconds since epoch time.
 * @return {string} Display-friend date (English US).
 */
function convertMillisToDateString(millis) {
  const date = new Date(millis);
  const options = { year: 'numeric', month: 'long', day: 'numeric' };
  return date.toLocaleDateString('en-US', options);
}
contactForm.gs

Zawiera widżety, które otrzymują dane z formularzy od użytkowników. Widżety wprowadzania danych są wyświetlane na kartach, które pojawiają się w wiadomościach i oknach dialogowych.

Wyświetl kod contactForm.gs

apps-script/contact-form-app/contactForm.gs
/**
 * Copyright 2024 Google Inc.
 *
 * Licensed under the Apache License, Version 2.0 (the "License");
 * you may not use this file except in compliance with the License.
 * You may obtain a copy of the License at
 *
 * http://www.apache.org/licenses/LICENSE-2.0
 *
 * Unless required by applicable law or agreed to in writing, software
 * distributed under the License is distributed on an "AS IS" BASIS,
 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
 * See the License for the specific language governing permissions and
 * limitations under the License.
 */

/**
 * The section of the contact card that contains the form input widgets. Used in a dialog and card message.
 * To add and preview widgets, use the Card Builder: https://addons.gsuite.google.com/uikit/builder
 */
const CONTACT_FORM_WIDGETS = [
  {
    "textInput": {
      "name": "contactName",
      "label": "First and last name",
      "type": "SINGLE_LINE"
    }
  },
  {
    "dateTimePicker": {
      "name": "contactBirthdate",
      "label": "Birthdate",
      "type": "DATE_ONLY"
    }
  },
  {
    "selectionInput": {
      "name": "contactType",
      "label": "Contact type",
      "type": "RADIO_BUTTON",
      "items": [
        {
          "text": "Work",
          "value": "Work",
          "selected": false
        },
        {
          "text": "Personal",
          "value": "Personal",
          "selected": false
        }
      ]
    }
  }
];
appsscript.json

Plik manifestu Apps Script, który definiuje i konfiguruje projekt Apps Script na potrzeby aplikacji Google Chat.

Wyświetl kod appsscript.json

apps-script/contact-form-app/appsscript.json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

Znajdowanie numeru i identyfikatora projektu Cloud

  1. W konsoli Google Cloud otwórz swój projekt Cloud.

    Otwórz konsolę Google Cloud

  2. Kliknij Ustawienia i narzędzia > Ustawienia projektu.

  3. Zapisz sobie wartości w polach Numer projektu i Identyfikator projektu. Użyjesz ich w następnych sekcjach.

Tworzenie projektu Apps Script

Aby utworzyć projekt Apps Script i połączyć go z projektem Cloud:

  1. Kliknij ten przycisk, aby otworzyć projekt Apps Script Zarządzanie kontaktami w Google Chat.
    Otwórz projekt
  2. Kliknij Przegląd.
  3. Na stronie Przegląd kliknij Ikona tworzenia kopii Utwórz kopię.

  4. Nadaj nazwę kopii projektu Apps Script:

    1. Kliknij Kopia Menedżera kontaktów w Google Chat.

    2. W polu Tytuł projektu wpisz Contact Manager - Google Chat app.

    3. Kliknij Zmień nazwę.

Ustawianie projektu Google Cloud w projekcie Apps Script

  1. W projekcie Apps Script kliknij Ikona ustawień projektu Ustawienia projektu.
  2. W sekcji Projekt Google Cloud Platform (GCP) kliknij Zmień projekt.
  3. W polu Numer projektu GCP wklej numer swojego projektu Cloud.
  4. Kliknij Ustaw projekt. Projekt w chmurze i projekt Apps Script są teraz połączone.

Tworzenie wdrożenia Apps Script

Po umieszczeniu całego kodu w odpowiednim miejscu wdruż projekt Apps Script. Identyfikator wdrożenia służy do konfigurowania aplikacji Google Chat w Google Cloud.

  1. W Apps Script otwórz projekt aplikacji Google Chat.

    Otwórz Apps Script

  2. Kliknij Wdróż > Nowe wdrożenie.

  3. Jeśli Dodatek nie jest jeszcze wybrany, obok pozycji Wybierz typ kliknij typ wdrożenia Ikona ustawień projektu i wybierz Dodatek.

  4. W polu Opis wpisz opis tej wersji, na przykład Test of Contact Manager.

  5. Kliknij Wdróż. Skrypt Apps Script zgłasza pomyślne wdrożenie i udostępnia identyfikator wdrożenia.

  6. Kliknij  Kopiuj, aby skopiować identyfikator wdrożenia, a potem kliknij Gotowe.

Konfigurowanie aplikacji Google Chat w konsoli Google Cloud

W tej sekcji dowiesz się, jak skonfigurować interfejs Google Chat API w konsoli Google Cloud przy użyciu informacji o Twojej aplikacji Google Chat, w tym identyfikatora wdrożenia utworzonego z poziomu projektu Apps Script.

  1. W konsoli Google Cloud kliknij Menu > Więcej usług > Google Workspace > Biblioteka usług > Interfejs API Google Chat > Zarządzaj > Konfiguracja.

    Otwórz konfigurację interfejsu Chat API

  2. W polu Nazwa aplikacji wpisz Contact Manager.

  3. W polu URL awatara wpisz https://developers.google.com/chat/images/contact-icon.png.

  4. W polu Opis wpisz Manage your personal and business contacts.

  5. Kliknij przełącznik Włącz funkcje interaktywne, aby go włączyć.

  6. W sekcji Funkcjonalność zaznacz pola wyboru Odbieranie wiadomości 1:1 i Dołączanie do pokoi i rozmów grupowych.

  7. W sekcji Ustawienia połączenia kliknij Apps Script.

  8. W polu Identyfikator wdrożenia wklej identyfikator wdrożenia Apps Script skopiowany w poprzedniej sekcji podczas tworzenia wdrożenia Apps Script.

  9. W sekcji Polecenia po ukośniku skonfiguruj polecenia /about i /addContact:

    1. Aby skonfigurować pierwsze polecenie po ukośniku, kliknij Dodaj polecenie po ukośniku.
    2. W polu Nazwa wpisz /about.
    3. W polu Identyfikator polecenia wpisz 1.
    4. W polu Opis wpisz Learn how to use this Chat app to manage your contacts.
    5. Kliknij Otwiera okno.
    6. Kliknij Gotowe.
    7. Aby skonfigurować kolejne polecenie po ukośniku, kliknij Dodaj polecenie po ukośniku.
    8. W polu Nazwa wpisz /addContact
    9. W polu Identyfikator polecenia wpisz 2.
    10. W polu Opis wpisz Submit information about a contact.
    11. Kliknij Otwiera okno.
    12. Kliknij Gotowe.

  10. W sekcji Widoczność zaznacz pole wyboru Udostępnij tę aplikację do obsługi czatu konkretnym osobom i grupom w domenie YOUR DOMAIN i wpisz swój adres e-mail.

  11. W sekcji Logi wybierz Rejestruj błędy w usłudze Logging.

  12. Kliknij Zapisz. Pojawi się komunikat o zapisanej konfiguracji.

Aplikacja Google Chat jest gotowa do zainstalowania i przetestowania w Google Chat.

Testowanie aplikacji Google Chat

Aby przetestować aplikację Google Chat, otwórz czat w aplikacji Google Chat i wyślij wiadomość:

  1. Otwórz Google Chat za pomocą konta Google Workspace, które zostało podane podczas dodawania siebie jako zaufanego testera.

    Otwórz Google Chat

  2. Kliknij Nowy czat.
  3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji Google Chat.

  4. Wybierz aplikację Google Chat z wyników. Otworzy się czat.

  1. W nowym czacie z aplikacją Google Chat wpisz /addContact i naciśnij Enter.

  2. W wyświetlonym oknie wpisz informacje kontaktowe:

    1. W polu tekstowym Imię i nazwisko wpisz imię i nazwisko.
    2. W selektorze daty Data urodzenia wybierz datę.
    3. W sekcji Typ kontaktu kliknij przycisk radiowy Praca lub Osobiście.

  3. Kliknij Sprawdź i prześlij.

  4. W oknie potwierdzenia sprawdź przesłane informacje i kliknij Prześlij. Aplikacja Google Chat odpowie tekstem: ✅ CONTACT NAME has been added to your contacts..

  5. Opcjonalnie możesz też przetestować i przesłać formularz kontaktowy w jeden z tych sposobów:

    • Użyj polecenia /about. Aplikacja do czatu odpowiada wiadomością tekstową i przyciskiem widżetu akcesoria z napisem Add a contact. Możesz kliknąć przycisk, aby otworzyć okno z formularzem kontaktowym.
    • Wyślij wiadomość na czacie bez użycia polecenia ukośnika, na przykład Hello. Aplikacja Czat odpowiada tekstem i kartą zawierającą formularz kontaktowy.

Czyszczenie danych

Aby uniknąć obciążenia konta Google Cloud opłatami za zasoby zużyte w tym samouczku, zalecamy usunięcie projektu Google Cloud.

  1. W konsoli Google Cloud otwórz stronę Zarządzanie zasobami. Kliknij Menu > Administracja > Zarządzaj zasobami.

    Otwórz Menedżera zasobów

  2. Na liście projektów wybierz projekt do usunięcia, a następnie kliknij Usuń .
  3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.