Собирайте контакты и управляйте ими в 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) {
  // Checks for the presence of event.message.slashCommand.
  // If the slash command is "/about", responds with a text message and button that opens a dialog.
  // If the slash command is "/addContact", opens a dialog.
  if (event.message.slashCommand) {
    switch (event.message.slashCommand.commandId) {
      case 1: // /about
        return {
          "text": "Manage your contacts with the Rolodex app 📇. To add a contact, use the slash command `/addContact`.",
          "accessoryWidgets": [
              {
                "buttonList": {
                  "buttons": [
                    {
                      "text": "Add Contact",
                      "onClick": {
                        "action": {
                          "function": "openDialog",
                          "interaction": "OPEN_DIALOG"
                        }
                      }
                    }
                  ]
                }
              }
            ]
          }
      case 2:  // /addContact
        return openDialog(event);
    }
  }
  // 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": contactFormWidgets.concat([{
              "buttonList": {
                  "buttons": [{
                    "text": "Review and submit",
                      "onClick": {
                        "action": {"function": "openNextCard",
          }}}]}}])}]
       }}]
  };
}

/**
 * Responds to CARD_CLICKED interaction events in Google Chat.
 *
 * @param {Object} event the CARD_CLICKED interaction event from Google Chat
 */
function onCardClick(event) {
  if (event.common.invokedFunction === "openDialog") {
    return openDialog(event);
  }
  if (event.common.invokedFunction === "openNextCard") {
    const contactName = fetchFormValue(event, "contactName");
    const contactBirthdate = fetchFormValue(event, "contactBirthdate");
    const contactType = fetchFormValue(event, "contactType");
    const user = event.user;
    return openNextCard(user, contactName, contactBirthdate, contactType, event.isDialogEvent)
  }
  if (event.common.invokedFunction === "submitForm") {
    const user = event.user;
    const userInputs = event.common.parameters;
    const dialogEventType = event.dialogEventType;
    return submitForm(user, userInputs, dialogEventType);
  }
}

/**
 * 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.
 */
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.  
  if (formItem.hasOwnProperty("dateInput")) {  
    const dateInput = event.common.formInputs[widgetName][""].dateInput.msSinceEpoch;  
     if (dateInput != null) {  
       return dateInput;  
     }  
  }  
  // If no input types match, returns null.  
  return null;  
}  

/**
 * Opens a dialog that prompts users to add details about a contact.  
 *  
 * @return {Object} a message with an action response to open a dialog.  
 */
function openDialog() {
  return {
    "actionResponse": {
      "type": "DIALOG",
      "dialogAction": {
        "dialog": {
          "body": {
            "sections": [
              {
                "header": "Add new contact",
                "widgets": contactFormWidgets.concat([{
                  "buttonList": {
                    "buttons": [{
                      "text": "Review and submit",
                        "onClick": {
                          "action": {
                            "function": "openNextCard"
                            }
                          }
                        }
                      ]
                    }
                  }
                ])
              }
            ]
          }
        }
      }
    }
  };
}

/**  
 * Returns another dialog or card message that displays a confirmation of  
 * contact details before users submit.  
 *  
 * @param {String} user the user who submitted the information.  
 * @param {String} contactName the contact name from the previous dialog or card.  
 * @param {String} contactBirthdate the birthdate from the previous dialog or card.  
 * @param {String} contactType the contact type from the previous dialog or card.  
 * @param {boolean} fromDialog whether the information was submitted from a dialog.  
 *  
 * @return {Object} returns a dialog or private card message.  
 */
function openNextCard(user, contactName, contactBirthdate, contactType, fromDialog) {
  const name = contactName ?? "<i>Not provided</i>";
  const birthdate = contactBirthdate ?? "<i>Not provided</i>";
  const type = contactType ?? "<i>Not provided</i>";
  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 another dialog with contact information that the user input.
  if (fromDialog) {  
    return {  
      "action_response": {  
        "type": "DIALOG",  
        "dialog_action": {  
          "dialog": {  
            "body": {  
              "sections": [ cardConfirmation ]  
            }  
          }  
        }  
      }  
    };  
  }
  // Updates existing card message with contact information that the user input.
  return {
      "actionResponse": {
      "type": "UPDATE_MESSAGE",
      },
    "privateMessageViewer": user,
    "cardsV2": [{
      "card": {"sections": [cardConfirmation]}
      }]
  }

/**  
  * Submits information from a dialog or card message.  
  *  
  * @param {Object} user the person who submitted the information.  
  * @param {Object} userInputs the form input values specified in event object parameters  
  * @param {boolean} dialogEventType contains "SUBMIT_DIALOG" if the event came from a dialog  
  * @return {Object} a message response that opens a dialog or posts a private message.  
  */
function submitForm(user, userInputs, dialogEventType) {
  const contactName = userInputs["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 (dialogEventType === "SUBMIT_DIALOG") {
      return {
        "actionResponse": {
          "type": "DIALOG",
          "dialogAction": {
            "actionStatus": {
              "statusCode": "INVALID_ARGUMENT",
              "userFacingMessage": errorMessage
            }
          }
        }
      };
    } else {
      return {
        "privateMessageViewer": user,
        "text": errorMessage 
      };
    }
  }
  // Otherwise 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 (dialogEventType === "SUBMIT_DIALOG") {
    return {
      "actionResponse": {
        "type": "NEW_MESSAGE",
        "dialogAction": {
          "actionStatus": {
            "statusCode": "OK",
            "userFacingMessage": "Success " + JSON.stringify(contactName)
          }
        }
      },
      "privateMessageViewer": user,
      "text": confirmationMessage
    }
  } else {
    return {
      "actionResponse": {
        "type": "NEW_MESSAGE"
      },
      "privateMessageViewer": user,
      "text": confirmationMessage
  }}
}

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