Собирайте контакты и управляйте ими в 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 API.

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

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

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

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

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

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

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

  1. В консоли Google API перейдите в > Платформа аутентификации Google > Брендинг .

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

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

    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. Нажмите «Переименовать» .

In the future, if you want to use certain Google APIs or publish your app, you must associate your Cloud project with your Apps Script project. For this guide, you don't need to do so. To learn more, see the Google Cloud projects guide .

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

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

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

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

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

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

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

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

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

Настройте приложение «Чат» в консоли Google API.

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

  1. В консоли Google API перейдите > API и сервисы > Включенные API и сервисы > 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 API перейдите на страницу «Управление ресурсами» > IAM и администрирование > Управление ресурсами .

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

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