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

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

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

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

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

Цели

Архитектура

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

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

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

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

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

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

    • Имя и фамилия : виджет textInput , который принимает строки.
    • Birthdate : виджет 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

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

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

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

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

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

  1. > API и службы > Экран согласия OAuth .

    Перейдите на экран согласия OAuth.

  2. В разделе «Тип пользователя» выберите «Внутренний» , затем нажмите «Создать» .

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

  4. В разделе «Электронная почта поддержки пользователей» выберите свой адрес электронной почты или соответствующую группу Google.

  5. В разделе «Контактная информация разработчика» введите свой адрес электронной почты.

  6. Нажмите «Сохранить и продолжить» .

  7. На странице «Области» нажмите «Сохранить и продолжить» . (Приложению Chat не требуются области OAuth.)

  8. Просмотрите сводку и нажмите «Вернуться на панель мониторинга» .

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

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

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

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

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

main.gs

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

Посмотреть код main.gs

приложения-скрипт/контакт-форма-приложение/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

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

Посмотреть код contactForm.gs

приложения-скрипт/контакт-форма-приложение/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

приложения-скрипт/контакт-форма-приложение/appsscript.json
{
  "timeZone": "America/Los_Angeles",
  "dependencies": {},
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "chat": {}
}

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

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

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

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

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

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

Чтобы создать проект Apps Script и связать его с проектом Cloud:

  1. Нажмите следующую кнопку, чтобы открыть проект «Управление контактами в приложениях Google Chat Script».
    Открыть проект
  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. Нажмите Копировать », чтобы скопировать идентификатор развертывания, а затем нажмите «Готово» .

Настройте приложение Chat в консоли 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. В разделе «Функциональность» установите флажки « Получать сообщения 1:1» и «Присоединяться к группам и групповым беседам» .

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

  8. В поле «Идентификатор развертывания » вставьте идентификатор развертывания 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. Выбрать Открывает диалоговое окно .
    6. Нажмите Готово .
    7. Нажмите «Добавить команду косой черты» , чтобы настроить другую команду косой черты.
    8. В поле Имя введите /addContact
    9. В поле «Идентификатор команды» введите 2 .
    10. В поле «Описание» введите Submit information about a contact .
    11. Выбрать Открывает диалоговое окно .
    12. Нажмите Готово .

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

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

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

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

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

Чтобы протестировать приложение Chat, откройте пространство для прямых сообщений в приложении Chat и отправьте сообщение:

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

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

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

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

  1. В новом прямом сообщении в приложении Chat введите /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. В диалоговом окне введите идентификатор проекта и нажмите «Завершить работу», чтобы удалить проект.