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

W tym samouczku pokazujemy, jak utworzyć aplikację Google Chat, która pomaga użytkownikom Google Chat zarządzać kontaktami osobistymi i biznesowymi. Aby zbierać informacje, aplikacja Google Chat prosi użytkowników o wypełnienie formularza kontaktowego w wiadomościach w postaci kart i oknach.

Zobacz, jak działa aplikacja Google Chat:

Wymagania wstępne

• Konto Google Workspace w wersji Business lub Enterprise z dostępem do Google Chat.
• Utwórz projekt Google Cloud.

Cele

• Projektuj i twórz interfejsy użytkownika jako obiektycard i wyświetlaj je w wiadomościach i oknach dialogowych.
• Otrzymywanie i przetwarzanie informacji przesyłanych przez użytkowników za pomocą widżetów do wprowadzania danych w formularzu.
• Odpowiadaj na polecenia wiadomościami zawierającymi tekst, karty i widżety akcesoriów.

Architektura

Aplikacja Google Chat jest wbudowana w Google Apps Script (jako dodatek do Google Workspace, który rozszerza Google Chat) i reaguje na interakcje użytkownika (onMessage, onAppCommand i kliknięcia przycisków, które wywołują openInitialDialog, openConfirmationDialog i submitForm), aby przetwarzać i odpowiadać na wiadomości użytkowników Chatu.

Poniżej znajdziesz przykład typowej interakcji użytkownika z aplikacją do obsługi czatu:

1. użytkownik otwiera czat z aplikacją do Google Chat lub dodaje aplikację do 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 odpowiada użytkownikom w ten sposób:

   • Odpowiada na @wzmianki i wiadomości bezpośrednie (onMessage) kartą z formularzem kontaktowym.
   • Odpowiada na polecenie po ukośniku /addContact (onAppCommand), otwierając okno z formularzem kontaktowym.
   • Odpowiada na polecenie po ukośniku /about (onAppCommand) wiadomością tekstową z przyciskiem Dodaj kontakt, który użytkownicy mogą kliknąć, aby wywołać openInitialDialog i otworzyć okno z formularzem kontaktowym.

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

   • Imię i nazwisko: widżet, który akceptuje ciągi znaków.textInput
   • Data urodzenia: dateTimePicker widżet, który akceptuje tylko daty.
   • Typ kontaktu:selectionInputwidżet z opcjami, który umożliwia użytkownikom wybranie i przesłanie pojedynczego ciągu znaków (Personal lub Work).
   • Przycisk Sprawdź i prześlijbuttonList: tablica z widgetem button, który użytkownik klika, aby przesłać wpisane wartości.

4. Aplikacja Google Chat wywołuje funkcję openConfirmationDialog, 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 wywołać funkcję submitForm i sfinalizować podawanie informacji kontaktowych.

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

Przygotowywanie środowiska

W tej sekcji dowiesz się, jak skonfigurować projekt Google Cloud na potrzeby aplikacji do obsługi czatu.

Otwórz projekt w chmurze w Konsoli interfejsów API Google.

Jeśli nie jest jeszcze otwarty, otwórz projekt w chmurze, którego chcesz użyć w tym przykładzie:

1. W Konsoli interfejsów API Google otwórz stronę Wybierz projekt.

   Wybierz projekt w chmurze

2. Wybierz projekt w chmurze Google, którego chcesz używać. Możesz też kliknąć Utwórz projekt i postępować zgodnie z instrukcjami wyświetlanymi na ekranie. Jeśli utworzysz projekt Google Cloud, może być konieczne włączenie płatności za ten projekt.

Konfigurowanie uwierzytelniania i autoryzacji

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

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

1. W konsoli interfejsów API Google kliknij Menu menu > Platforma uwierzytelniania Google > Branding.

   Przejdź do sekcji Elementy marki

2. Jeśli platforma uwierzytelniania Google została już skonfigurowana, możesz skonfigurować te ustawienia ekranu zgody OAuth w sekcjach Branding, Odbiorcy i Dostęp do danych. Jeśli zobaczysz komunikat Platforma uwierzytelniania Google nie została jeszcze skonfigurowana, kliknij Rozpocznij:

   1. W sekcji Informacje o aplikacji w polu Nazwa aplikacji wpisz Contact Manager.
   2. W sekcji Adres e-mail dla użytkowników potrzebujących pomocy wybierz swój adres e-mail lub odpowiednią grupę dyskusyjną Google.
   3. Kliknij Dalej.
   4. W sekcji Odbiorcy wybierz Wewnętrzny. Jeśli nie możesz wybrać opcji Wewnętrzny, wybierz Zewnętrzny.
   5. Kliknij Dalej.
   6. W sekcji Informacje kontaktowe wpisz adres e-mail, na który będziesz otrzymywać powiadomienia o wszelkich zmianach w projekcie.
   7. Kliknij Dalej.
   8. W sekcji Zakończ zapoznaj się z zasadami dotyczącymi danych użytkownika w usługach interfejsu API Google. Jeśli je akceptujesz, kliknij Akceptuję zasady dotyczące danych użytkownika w usługach interfejsu API Google.
   9. Kliknij Dalej.
   10. Kliknij Utwórz.
   11. Jeśli jako typ użytkownika wybierzesz Zewnętrzny, dodaj testerów:
       1. Kliknij Odbiorcy.
       2. W sekcji Użytkownicy testowi kliknij Dodaj użytkowników.
       3. Wpisz swój adres e-mail i adresy e-mail innych autoryzowanych użytkowników testowych, a następnie kliknij Zapisz.

Tworzenie i wdrażanie aplikacji Google Chat

W następnej sekcji utworzysz i zaktualizujesz projekt Apps Script z kodem aplikacji (Code.gs i appsscript.json) dla aplikacji w Google Chat.

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

Wyświetl w GitHubie

Oto omówienie poszczególnych plików:

Code.gs

Obsługuje całą logikę aplikacji, w tym interakcje użytkownika (onMessage, onAppCommand, openInitialDialog, openConfirmationDialog i submitForm) oraz widżety wprowadzania danych w formularzach wyświetlane na kartach w wiadomościach i oknach.

Wyświetl kod Code.gs

apps-script/chat/contact-form-app/Code.gs

Wyświetl w GitHubie

/**
 * Copyright 2025 Google LLC
 *
 * 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 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"
    }},
    { 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 }
      ]
    }},
    { 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];
  const birthdate = event.commonEventObject.formInputs["contactBirthdate"].dateInput.msSinceEpoch;
  const type = event.commonEventObject.formInputs["contactType"].stringInputs.value[0];
  // Display the input values for confirmation
  return { action: { navigations: [{ pushCard: { sections: [{ widgets: [
    { textParagraph: { text: "Confirm contact information and submit:" }},
    { textParagraph: { text: "<b>Name:</b> " + name }},
    { textParagraph: { text: "<b>Birthday:</b> " + new Date(birthdate) }},
    { textParagraph: { text: "<b>Type:</b> " + type }},
    { buttonList: { buttons: [{
      text: "SUBMIT",
      onClick: { action: {
        function: "submitDialog",
        // Pass input values as parameters for last dialog step (submission)
        parameters: [
          { key: "contactName", value: name },
          { key: "contactBirthdate", value: birthdate },
          { key: "contactType", value: type }
        ]
      }}
    }]}}
  ]}]}}]}};
}

/**
 * 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 or message.
 */
function submitDialog(event) {
  // Validate the parameters.
  if (!event.commonEventObject.parameters["contactName"]) {
    return { action: {
      navigations: [{ endNavigation: { action: "CLOSE_DIALOG"}}],
      notification: { text: "Failure, the contact name was missing!" }
    }};
  }

  return { hostAppDataAction: { chatDataAction: { createMessageAction: { message: {
    text: "✅ " + event.commonEventObject.parameters["contactName"] + " has been added to your contacts."
  }}}}};
}

appsscript.json

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

Wyświetl kod appsscript.json

apps-script/chat/contact-form-app/appsscript.json

Wyświetl w GitHubie

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "addOns": {
    "common": {
      "name": "Contact Form app",
      "logoUrl": "https://developers.google.com/workspace/add-ons/images/contact-icon.png"
    },
    "chat": {}
  }
}

Tworzenie projektu Apps Script

Aby utworzyć projekt Apps Script z plików Code.gs i appsscript.json:

1. Otwórz Google Apps Script i kliknij Nowy projekt.

2. Nazwij projekt Apps Script:

   1. Kliknij Projekt bez nazwy.

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

   3. Kliknij Zmień nazwę.

3. Zastąp zawartość pliku Code.gs powyższym przykładowym kodem Code.gs.

4. Kliknij Ustawienia projektu i wybierz Pokaż w edytorze plik manifestu „appsscript.json”.

5. Wróć do edytora i zastąp zawartość appsscript.json powyższym kodem manifestu appsscript.json, a następnie zapisz projekt.

Jeśli w przyszłości zechcesz używać określonych interfejsów API Google lub opublikować aplikację, musisz powiązać projekt w chmurze z projektem Apps Script. W tym przewodniku nie musisz tego robić. Więcej informacji znajdziesz w przewodniku po projektach Google Cloud.

Tworzenie wdrożenia Apps Script

Gdy cały kod będzie już gotowy, wdróż projekt Apps Script. Identyfikator wdrożenia jest używany podczas konfigurowania aplikacji do 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 opcja Dodatek nie jest jeszcze wybrana, obok Wybierz typ kliknij typy wdrożenia  i wybierz Dodatek.

4. W polu Opis wpisz opis tej wersji, np. Test of Contact Manager.

5. Kliknij Wdróż. Apps Script zgłasza pomyślne wdrożenie i podaje identyfikator wdrożenia.

6. Kliknij content_copy Kopiuj, aby skopiować identyfikator wdrożenia, a następnie kliknij Gotowe.

Konfigurowanie aplikacji do obsługi czatu w Konsoli interfejsów API Google

W tej sekcji dowiesz się, jak skonfigurować interfejs Google Chat API w Konsoli interfejsów API Google, podając informacje o aplikacji do Google Chat, w tym identyfikator wdrożenia, które zostało utworzone w projekcie Apps Script.

1. W konsoli interfejsów API Google kliknij Menu menu > Interfejsy API i usługi > Włączone interfejsy API i usługi > Google Chat API > 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. Ustaw przełącznik Włącz funkcje interaktywne w pozycji włączonej.

6. W sekcji Funkcje wybierz Dołączanie do pokoi i rozmów grupowych.

7. W sekcji Ustawienia połączenia wybierz 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 Wyzwalacze skonfiguruj funkcje, które reagują na interakcje użytkownika:

   • W przypadku wyzwalacza Wiadomość wpisz onMessage.
   • W przypadku reguły Polecenie aplikacji wpisz onAppCommand.

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

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

11. 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.

12. W sekcji Logi kliknij Loguj błędy w usłudze Logging.

13. Kliknij Zapisz. Pojawi się komunikat „Zapisano konfigurację”.

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

Testowanie aplikacji Google Chat

Aby przetestować aplikację do Google Chat, otwórz czat z aplikacją i wyślij wiadomość:

1. Otwórz Google Chat, używając konta Google Workspace, które zostało podane podczas dodawania siebie jako zaufanego testera.

   Otwórz Google Chat

2. Kliknij add Nowy czat.
3. W polu Dodaj co najmniej 1 osobę wpisz nazwę aplikacji do obsługi czatu w Google Chat.

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

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

2. W wyświetlonym oknie podaj informacje kontaktowe:

   1. W polu tekstowym Imię i nazwisko wpisz nazwę.
   2. W selektorze daty Data urodzenia wybierz datę.
   3. W sekcji Typ kontaktu wybierz Służbowy lub Prywatny.

3. Kliknij Sprawdź i prześlij.

4. W oknie potwierdzenia sprawdź przesłane informacje i kliknij Prześlij. Aplikacja Google Chat odpowie wiadomością tekstową z informacją ✅ 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 po ukośniku /about. Aplikacja do obsługi czatu odpowiada wiadomością tekstową i przyciskiem widżetu akcesoriów z tekstem Add a contact. Możesz kliknąć przycisk, aby otworzyć okno z formularzem kontaktowym.
   • Wyślij do aplikacji Google Chat wiadomość na czacie bez polecenia po ukośniku, np. Hello. Aplikacja Google Chat odpowie 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 w chmurze.

1. W konsoli interfejsów API Google otwórz stronę Zarządzanie zasobami. Kliknij Menu menu > IAM i administrator > Zarządzaj zasobami.

   Otwórz Resource Manager

2. Z listy projektów wybierz projekt do usunięcia, a potem kliknij Usuń delete.
3. W oknie wpisz identyfikator projektu i kliknij Wyłącz, aby usunąć projekt.

Powiązane artykuły

• Odpowiadanie na polecenia
• Zbieranie i przetwarzanie informacji od użytkowników Google Chat
• Otwieranie interaktywnych okien
• Poznaj inne przykłady aplikacji Google Chat