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

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

Посмотрите, как работает приложение «Чат»:

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

Предварительные требования

Цели

Архитектура

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

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

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

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

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

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

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

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

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

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

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

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

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

Если проект Cloud, который вы собираетесь использовать в этом примере, еще не открыт, откройте его:

  1. В консоли Google Cloud перейдите на страницу «Выберите проект» .

    Выберите облачный проект

  2. Выберите проект Google Cloud, который хотите использовать. Или нажмите «Создать проект» и следуйте инструкциям на экране. Если вы создаете проект Google Cloud, вам может потребоваться включить оплату для этого проекта .

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

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

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

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

    Перейти к разделу «Брендинг»

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

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

Создайте и разверните приложение «Чат».

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

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

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

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

main.gs

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

Просмотреть код 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 для приложения «Чат».

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

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

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

Для создания проекта Apps Script:

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

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

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

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

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

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

Создайте развертывание Apps Script.

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

  1. В Apps Script откройте проект приложения «Чат».

    Перейдите в раздел Apps Script.

  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. Нажмите «Отключить ». Создайте это приложение чата как надстройку для Google Workspace . Откроется диалоговое окно с запросом подтверждения. В диалоговом окне нажмите «Отключить» .

  3. В поле «Название приложения» введите Contact Manager .

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

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

  6. Переведите переключатель «Включить интерактивные функции» в положение «Вкл.».

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

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

  9. В поле «Идентификатор развертывания» вставьте идентификатор развертывания Apps Script, который вы скопировали в предыдущем разделе при создании развертывания Apps Script.

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

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

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

  12. В разделе «Журналы» выберите « Записывать ошибки в журнал» и перейдите в раздел «Ведение журнала» .

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

Приложение «Чат» готово к установке и тестированию в приложении «Чат».

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

Чтобы протестировать приложение «Чат», откройте личное сообщение в приложении «Чат» и отправьте сообщение:

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

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

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

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

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

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

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

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

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

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

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

Уборка

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

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

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

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