Собирайте контакты и управляйте ими в Google Chat

В этом руководстве показано, как создать приложение Google Chat, которое поможет пользователям управлять личными и деловыми контактами. Для сбора информации приложение предлагает пользователям заполнить контактную форму в сообщениях и диалогах.

Посмотрите на приложение Chat в действии:

  • Контактная форма из команды «косая черта».
    Рисунок 1. Приложение чата отвечает на команду /about текстовым сообщением и кнопкой, которая открывает контактную форму.
  • Контактная форма в диалоговом режиме.
    Рисунок 2. Приложение «Чат» открывает диалоговое окно, в котором пользователи могут ввести информацию о контакте.
  • Подтвердите и просмотрите диалоговое окно.
    Рисунок 3. Приложение Chat возвращает диалоговое окно подтверждения, чтобы пользователи могли просмотреть и подтвердить информацию перед отправкой.
  • Текстовое сообщение, подтверждающее новый контакт.
    Рисунок 4. После того как пользователь отправит форму, приложение Chat отправит личное текстовое сообщение для подтверждения отправки.
  • Контактная форма из сообщения карты.
    Рисунок 5. Приложение «Чат» также предлагает пользователям добавить контакт из карточки в сообщение.

Предпосылки

Цели

Архитектура

Приложение Chat создано на основе Google Apps Script и использует события взаимодействия для обработки сообщений пользователей чата и ответа им.

Ниже показано, как пользователь обычно взаимодействует с приложением Chat:

  1. Пользователь открывает прямое сообщение с помощью приложения Chat или добавляет приложение Chat в существующее пространство.

  2. Приложение Chat предлагает пользователю добавить контакт, создавая и отображая контактную форму в виде объекта card . Для отображения контактной формы приложение Chat отвечает пользователям следующими способами:

    • Отвечает на @упоминания и личные сообщения сообщением-карточкой, содержащим контактную форму.
    • Реагирует на команду /addContact , открывая диалоговое окно с контактной формой.
    • Отвечает на команду /about текстовым сообщением с кнопкой «Добавить контакт» , которую пользователи могут нажать, чтобы открыть диалоговое окно с контактной формой.

  3. При отображении контактной формы пользователь вводит контактную информацию в следующие поля и виджеты:

    • Имя и фамилия : виджет textInput , принимающий строки.
    • Дата рождения : виджет dateTimePicker , который принимает только даты.
    • Тип контакта : виджет selectionInput с переключателями, позволяющий пользователям выбирать и отправлять одно строковое значение ( Personal или Work ).
    • Кнопка «Просмотреть и отправить» : массив buttonList с виджетом button , которую пользователь нажимает, чтобы отправить введенные им значения.

  4. Приложение Google Chat обрабатывает событие взаимодействия CARD_CLICKED для обработки значений, введенных пользователем, и отображает значения в карточке подтверждения.

  5. Пользователь просматривает карточку подтверждения и нажимает кнопку «Отправить» , чтобы завершить заполнение контактной информации.

  6. Приложение Google Chat отправляет личное текстовое сообщение, подтверждающее отправку.

Подготовьте окружающую среду

В этом разделе показано, как создать и настроить проект Google Cloud для приложения Chat.

Создайте проект Google Cloud

Консоль Google Cloud

  1. В консоли Google Cloud перейдите в > IAM и администрирование > Создать проект .

    Перейти к созданию проекта

  2. В поле «Название проекта» введите описательное название вашего проекта.

    Необязательно: чтобы изменить идентификатор проекта , нажмите «Изменить» . Идентификатор проекта нельзя изменить после его создания, поэтому выберите идентификатор, который будет соответствовать вашим потребностям на протяжении всего жизненного цикла проекта.

  3. В поле «Местоположение» нажмите «Обзор» , чтобы отобразить возможные местоположения для вашего проекта. Затем нажмите « Выбрать» .
  4. Нажмите «Создать» . Консоль Google Cloud перейдет на страницу панели управления, и ваш проект будет создан в течение нескольких минут.

gcloud CLI

В одной из следующих сред разработки получите доступ к Google Cloud CLI ( gcloud ):

  • Cloud Shell : чтобы использовать онлайн-терминал с уже настроенным интерфейсом командной строки gcloud, активируйте Cloud Shell.
    Активировать Cloud Shell
  • Локальная оболочка : чтобы использовать локальную среду разработки, установите и инициализируйте gcloud CLI.
    Чтобы создать облачный проект, используйте команду gcloud projects create :
    gcloud projects create PROJECT_ID
     Замените PROJECT_ID , указав идентификатор проекта, который вы хотите создать.

Настройте аутентификацию и авторизацию

Приложения Google Chat требуют настройки экрана согласия OAuth , чтобы пользователи могли авторизовать ваше приложение в приложениях Google Workspace, включая Google Chat.

В этом руководстве вы развернёте приложение Chat, предназначенное только для тестирования и внутреннего использования, поэтому вы можете использовать заглушки для экрана согласия. Перед публикацией приложения Chat замените все заглушки реальными данными.

  1. В консоли Google Cloud перейдите в > > Брендинг .

    Перейти к брендингу

  2. Если вы уже настроили, вы можете настроить следующие параметры экрана согласия OAuth в разделе Брендинг , Аудитория и Доступ к данным . Если вы видите сообщение, в котором говорится пока не настроено , нажмите «Начать» :

    1. В разделе «Информация о приложении» в поле «Имя приложения» введите Contact Manager .
    2. В поле «Электронная почта поддержки пользователей» выберите свой адрес электронной почты или соответствующую группу Google.
    3. Нажмите кнопку «Далее» .
    4. В разделе «Аудитория» выберите «Внутренняя» . Если выбрать «Внутренняя» невозможно, выберите «Внешняя» .
    5. Нажмите кнопку «Далее» .
    6. В разделе «Контактная информация» введите адрес электронной почты , на который вы можете получать уведомления о любых изменениях в вашем проекте.
    7. Нажмите кнопку «Далее» .
    8. В разделе «Готово » ознакомьтесь с Политикой использования пользовательских данных служб API Google и, если вы согласны, выберите «Я согласен с Политикой использования пользовательских данных служб API Google» .
    9. Нажмите «Продолжить» .
    10. Нажмите «Создать» .
    11. Если вы выбрали тип пользователя «Внешний» , добавьте тестовых пользователей:
      1. Нажмите Аудитория .
      2. В разделе Тестовые пользователи нажмите Добавить пользователей .
      3. Введите свой адрес электронной почты и адрес других авторизованных тестовых пользователей, затем нажмите кнопку «Сохранить» .

Создайте и разверните приложение чата

В следующем разделе вы скопируете и обновите весь проект Apps Script, содержащий весь необходимый код приложения для вашего приложения Chat, поэтому нет необходимости копировать и вставлять каждый файл.

При желании вы можете просмотреть весь проект на GitHub.

Посмотреть на GitHub

Вот обзор каждого файла:

main.gs

Обрабатывает всю логику приложения, включая события взаимодействия, связанные с отправкой пользователями сообщений в приложение Chat, нажатием кнопок в сообщении приложения Chat или открытием и закрытием диалоговых окон.

Посмотреть код 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.
  const errorMessage = "Don't forget to name your new contact!";
  if (!contactName && event.dialogEventType === "SUBMIT_DIALOG") {
    return { actionResponse: {
      type: "DIALOG",
      dialogAction: { actionStatus: {
        statusCode: "INVALID_ARGUMENT",
        userFacingMessage: errorMessage
      }}
    }};
  }
  if (!contactName) {
    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
        }}
      }
    };
  }
  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

Содержит виджеты, которые получают данные форм от пользователей. Эти виджеты ввода данных отображаются на карточках в сообщениях и диалоговых окнах.

Посмотреть код 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

Манифест Apps Script , который определяет и настраивает проект Apps Script для приложения Chat.

Просмотреть код appsscript.json

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

Найдите номер и идентификатор вашего облачного проекта

  1. В консоли Google Cloud перейдите в свой облачный проект.

    Перейти в консоль Google Cloud

  2. Нажмите Настройки и утилиты > Настройки проекта .

  3. Запишите значения в полях «Номер проекта» и «Идентификатор проекта» . Они понадобятся вам в следующих разделах.

Создайте проект Apps Script

Чтобы создать проект Apps Script и подключить его к вашему облачному проекту:

  1. Нажмите следующую кнопку, чтобы открыть проект скрипта « Управление контактами в Google Chat Apps».
    Открыть проект
  2. Нажмите Обзор .
  3. На странице обзора нажмите Значок для создания копии Сделайте копию .

  4. Назовите свою копию проекта Apps Script:

    1. Нажмите «Копировать» для управления контактами в Google Chat .

    2. В поле «Название проекта» введите Contact Manager - Google Chat app

    3. Нажмите «Переименовать» .

Настройте облачный проект проекта Apps Script.

  1. В проекте Apps Script нажмите Значок настроек проекта Настройки проекта .
  2. В разделе «Проект Google Cloud Platform (GCP)» нажмите «Изменить проект» .
  3. В поле Номер проекта GCP вставьте номер вашего облачного проекта.
  4. Нажмите «Установить проект» . Теперь проекты Cloud и Apps Script связаны.

Создайте развертывание скрипта приложений

Теперь, когда весь код готов, разверните проект Apps Script. Идентификатор развёртывания используется при настройке приложения Chat в Google Cloud.

  1. В Apps Script откройте проект приложения Chat.

    Перейти к скрипту приложений

  2. Нажмите Развернуть > Новое развертывание .

  3. Если надстройка еще не выбрана, рядом с пунктом «Выбрать тип» нажмите «Типы развертывания». Значок настроек проекта и выберите Дополнение .

  4. В поле Описание введите описание этой версии, например Test of Contact Manager .

  5. Нажмите «Развернуть» . Apps Script сообщает об успешном развертывании и предоставляет идентификатор развертывания.

  6. Нажмите Копировать , чтобы скопировать идентификатор развертывания, а затем нажмите Готово .

Настройте приложение чата в консоли Google Cloud

В этом разделе показано, как настроить API Google Chat в консоли Google Cloud, используя информацию о вашем приложении Chat, включая идентификатор развертывания, которое вы только что создали из своего проекта Apps Script.

  1. В консоли Google Cloud выберите Меню Дополнительные продукты > Google Workspace > Библиотека продуктов > Google Chat API > Управление > Конфигурация .

    Перейти к настройке API чата

  2. В поле Имя приложения введите Contact Manager .

  3. В поле URL аватара введите https://developers.google.com/chat/images/contact-icon.png .

  4. В поле Описание введите Manage your personal and business contacts .

  5. Установите переключатель «Включить интерактивные функции» в положение «Вкл.».

  6. В разделе «Функциональность» выберите Присоединяйтесь к пространствам и групповым беседам .

  7. В разделе «Настройки подключения» выберите «Скрипт приложений» .

  8. В поле Deployment ID вставьте идентификатор развертывания Apps Script, скопированный в предыдущем разделе при создании развертывания Apps Script.

  9. В разделе «Команды» настройте слэш-команды /about и /addContact :

    1. Нажмите Добавить команду слэш , чтобы настроить первую команду слэш.
    2. В поле Имя введите About .
    3. В поле «Идентификатор команды» введите 1 .
    4. В поле Описание введите Learn how to use this Chat app to manage your contacts .
    5. В разделе «Тип команды» выберите Slash command .
    6. В поле Имя команды Slash введите /about .
    7. Выбрать Открывает диалоговое окно .
    8. Нажмите Готово .
    9. Нажмите Добавить команду , чтобы настроить еще одну слэш-команду.
    10. В поле Имя введите Add a contact .
    11. В поле «Идентификатор команды» введите 2 .
    12. В поле Описание введите Submit information about a contact .
    13. В разделе «Тип команды» выберите Slash command .
    14. В поле Имя команды Slash введите /addContact .
    15. Выбрать Открывает диалоговое окно .
    16. Нажмите Готово .

  10. В разделе «Видимость» установите флажок Сделать это приложение чата доступным для определенных людей и групп в YOUR DOMAIN и введите свой адрес электронной почты.

  11. В разделе Журналы выберите Записывать ошибки в Журнал .

  12. Нажмите «Сохранить» . Появится сообщение о сохранении конфигурации.

Приложение Chat готово к установке и тестированию в Chat.

Протестируйте приложение чата

Чтобы протестировать приложение Chat, откройте чат-комнату в приложении и отправьте сообщение:

  1. Откройте Google Chat, используя учетную запись Google Workspace, которую вы указали при добавлении себя в качестве доверенного тестировщика.

    Перейти в Google Чат

  2. Нажмите новый чат» .
  3. В поле Добавить 1 или более человек введите название вашего чат-приложения.

  4. Выберите приложение чата из результатов. Откроется личное сообщение.

  1. В новом прямом сообщении с помощью приложения «Чат» введите /addContact и нажмите Enter .

  2. В открывшемся диалоговом окне введите контактную информацию:

    1. В текстовом поле Имя и фамилия введите имя.
    2. В поле «Дата рождения» выберите дату.
    3. В разделе «Тип контакта» выберите переключатель «Рабочий» или «Личный ».

  3. Нажмите «Просмотреть и отправить» .

  4. В диалоговом окне подтверждения проверьте отправленную информацию и нажмите «Отправить» . Приложение Chat ответит текстовым сообщением: ✅ CONTACT NAME has been added to your contacts.

  5. При желании вы также можете протестировать и отправить контактную форму следующими способами:

    • Используйте команду /about . Чат-приложение отвечает текстовым сообщением и кнопкой-виджетом « Add a contact . Нажмите эту кнопку, чтобы открыть диалоговое окно с контактной формой.
    • Отправьте приложению Chat прямое сообщение без команды «косая черта», например, Hello . Приложение Chat ответит текстом и карточкой, содержащей контактную форму.

Очистить

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, мы рекомендуем вам удалить проект Cloud.

  1. В консоли Google Cloud перейдите на страницу «Управление ресурсами» . Выберите « Меню > «IAM и администрирование» > «Управление ресурсами» .

    Перейти к диспетчеру ресурсов

  2. В списке проектов выберите проект .
  3. В диалоговом окне введите идентификатор проекта, а затем нажмите кнопку «Завершить» , чтобы удалить проект.