Как создать главную страницу для приложения Google Chat

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

Рисунок 1. Пример главной страницы, которая появляется в прямых переписках с приложением Chat.

В отличие от других приложений Google Workspace, дополнения, расширяющие возможности Chat, не показывают домашнюю страницу на панели быстрого доступа справа и не используют addOns.common.homepageTrigger в манифесте. Вместо этого главная страница отображается в Chat в виде карточки на вкладке Главная в прямой переписке 1:1 с приложением Chat. Настроить ее можно в консоли Google Cloud.

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

---

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

Как открыть конструктор карточек

---

Требования

HTTP

Приложение Google Chat, которое получает и обрабатывает действия пользователей. Чтобы создать его, выполните краткое руководство по HTTP.

Примечание. Примеры кода в этом руководстве написаны для запуска в качестве функции Google Cloud Run для Node.js.

Apps Script

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

Как настроить главную страницу приложения Chat

Чтобы включить поддержку App Home, активируйте параметр Поддержка App Home и настройте триггер App Home в консоли Google Cloud. Приложение Chat получает событие запуска Главной страницы приложения, когда пользователь открывает вкладку Главная в прямой переписке с приложением.

Чтобы настроить главную страницу приложения в консоли Google Cloud:

1. В консоли Google Cloud нажмите Меню > API и сервисы > Включенные API и сервисы > Google Chat API > Конфигурация.

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

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

3. В разделе Настройки подключения > Триггеры укажите обработчик главной страницы приложения в поле Главная страница приложения в зависимости от архитектуры приложения Chat:

   • HTTP. Введите URL конечной точки HTTPS, которая обрабатывает запросы на главную страницу приложения (или выберите Использовать общий URL конечной точки HTTP для всех триггеров, чтобы все события получал общий URL конечной точки HTTP).
   • Google Apps Script – введите название функции обратного вызова Google Apps Script, которая создает и возвращает карточку главной страницы (по умолчанию onAppHome).

4. Нажмите Сохранить.

Как обрабатывать объект события App Home

Когда пользователь открывает вкладку Главная в прямой переписке с вашим приложением Chat, Chat отправляет объект события в конечную точку или функцию обратного вызова главной страницы приложения.

В отличие от событий взаимодействия с чат-группой или сообщением, исходный объект события "Главная страница приложения" не содержит полезную нагрузку взаимодействия с объединением (например, messagePayload). Он содержит следующие поля:

• commonEventObject: включает clientPlatform, hostApp ("CHAT"), userLocale и userTimezone.
• chat.user – пользователь Chat, который открыл вкладку Главная.
• chat.eventTime – временная метка момента, когда пользователь открыл вкладку Главная.

Как создать карточку приложения на главном экране

Когда пользователь открывает вкладку Главная, обработайте триггерное событие Главная страница приложения, вернув объект RenderActions с действием навигации pushCard и Card. Чтобы сделать карточку интерактивной, в нее можно добавить интерактивные виджеты, например кнопки или поля ввода текста.

HTTP

{
  "action": {
    "navigations": [
      {
        "pushCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Manage your settings and view your dashboard here."
                  }
                },
                {
                  "buttonList": {
                    "buttons": [
                      {
                        "text": "Refresh",
                        "onClick": {
                          "action": {
                            "function": "https://example.com/updateAppHome"
                          }
                        }
                      }
                    ]
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Builds and returns the App Home card when a user opens the Home tab.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response pushing the homepage card.
 */
function onAppHome(event) {
  const card = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection()
              .addWidget(
                  CardService.newTextParagraph().setText(
                      'Manage your settings and view your dashboard here.'))
              .addWidget(
                  CardService.newButtonSet().addButton(
                      CardService.newTextButton()
                          .setText('Refresh')
                          .setOnClickAction(
                              CardService.newAction().setFunctionName(
                                  'updateAppHome')))))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().pushCard(card))
      .build();
}

Как отвечать на запросы в приложении Home

Если на карточке главного экрана приложения есть интерактивные виджеты, например кнопки или поля формы, при нажатии кнопки отправляется объект события, содержащий chat.buttonClickedPayload (а также commonEventObject.parameters и commonEventObject.formInputs), в настроенную функцию действия или конечную точку кнопки.

Чтобы обновить карточку на главном экране приложения в ответ на действия пользователя, верните объект RenderActions с действием навигации updateCard. Чтобы узнать больше о том, как считывать данные, введенные пользователями в интерактивные виджеты, ознакомьтесь со статьей Как считывать данные, введенные пользователями в формы на карточках.

HTTP

{
  "action": {
    "navigations": [
      {
        "updateCard": {
          "header": {
            "title": "Welcome to App Home"
          },
          "sections": [
            {
              "widgets": [
                {
                  "textParagraph": {
                    "text": "Last updated: 2026-10-02T23:00:00Z"
                  }
                }
              ]
            }
          ]
        }
      }
    ]
  }
}

Apps Script

/**
 * Updates the App Home card when a user clicks the Refresh button.
 *
 * @param {Object} event The event object from Google Chat.
 * @return {ActionResponse} The RenderActions response updating the homepage card.
 */
function updateAppHome(event) {
  const updatedCard = CardService.newCardBuilder()
      .setHeader(
          CardService.newCardHeader().setTitle('Welcome to App Home'))
      .addSection(
          CardService.newCardSection().addWidget(
              CardService.newTextParagraph().setText(
                  'Last updated: ' + new Date().toTimeString())))
      .build();

  return CardService.newActionResponseBuilder()
      .setNavigation(CardService.newNavigation().updateCard(updatedCard))
      .build();
}

Как открывать диалоговые окна из приложения

Приложение Chat также может отвечать на действия в App Home, открывая диалоговые окна.

Рисунок 2. Диалоговое окно с предложением добавить контакт.

Чтобы узнать, как открывать, обновлять и закрывать диалоговые окна с помощью RenderActions (pushCard, updateCard и endNavigation: "CLOSE_DIALOG"), ознакомьтесь со статьей Как открывать интерактивные диалоговые окна.

Статьи по теме

• Как получать и обрабатывать действия пользователей
• Как открыть интерактивные диалоговые окна
• Как читать данные, введенные пользователями в формы на карточках
• Примеры приложений Chat

Приложения Chat, которые не являются дополнениями: создание главной страницы для приложения Chat

Если вы поддерживаете приложение Chat, которое не является дополнением Google Workspace, Chat отправляет событие взаимодействия APP_HOME, когда пользователь открывает вкладку Главная, а также события взаимодействия CARD_CLICKED или SUBMIT_FORM, когда пользователь взаимодействует с виджетами на карточке приложения на главной странице.

Чтобы преобразовать приложение Chat, которое не является дополнением, в дополнение Google Workspace, ознакомьтесь со статьей Как преобразовать приложение Google Chat в дополнение Google Workspace.

Как создать карточку главной страницы приложения в приложении Chat, которое не является дополнением

В приложении Chat, которое не является дополнением, обработайте событие взаимодействия APP_HOME, вернув ответ, содержащий поле renderActions верхнего уровня с навигацией pushCard:

Node.js

node/app-home/index.js

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

app.post('/', async (req, res) => {
  let event = req.body.chat;

  let body = {};
  if (event.type === 'APP_HOME') {
    // App home is requested
    body = { action: { navigations: [{
      pushCard: getHomeCard()
    }]}}
  } else if (event.type === 'SUBMIT_FORM') {
    // The update button from app home is clicked
    commonEvent = req.body.commonEventObject;
    if (commonEvent && commonEvent.invokedFunction === 'updateAppHome') {
      body = updateAppHome()
    }
  }

  return res.json(body);
});

// Create the app home card
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Python

python/app-home/main.py

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

@app.route('/', methods=['POST'])
def post() -> Mapping[str, Any]:
  """Handle requests from Google Chat

  Returns:
      Mapping[str, Any]: the response
  """
  event = request.get_json()
  match event['chat'].get('type'):

    case 'APP_HOME':
      # App home is requested
      body = { "action": { "navigations": [{
        "pushCard": get_home_card()
      }]}}

    case 'SUBMIT_FORM':
      # The update button from app home is clicked
      event_object = event.get('commonEventObject')
      if event_object is not None:
        if 'update_app_home' == event_object.get('invokedFunction'):
          body = update_app_home()

    case _:
      # Other response types are not supported
      body = {}

  return json.jsonify(body)


def get_home_card() -> Mapping[str, Any]:
  """Create the app home card

  Returns:
      Mapping[str, Any]: the card
  """
  return { "sections": [{ "widgets": [
    { "textParagraph": {
      "text": "Here is the app home 🏠 It's " +
        datetime.datetime.now().isoformat()
    }},
    { "buttonList": { "buttons": [{
      "text": "Update app home",
      "onClick": { "action": {
        "function": "update_app_home"
      }}
    }]}}
  ]}]}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

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

// Process Google Chat events
@PostMapping("/")
@ResponseBody
public GenericJson onEvent(@RequestBody JsonNode event) throws Exception {
  switch (event.at("/chat/type").asText()) {
    case "APP_HOME":
      // App home is requested
      GenericJson navigation = new GenericJson();
      navigation.set("pushCard", getHomeCard());

      GenericJson action = new GenericJson();
      action.set("navigations", List.of(navigation));

      GenericJson response = new GenericJson();
      response.set("action", action);
      return response;
    case "SUBMIT_FORM":
      // The update button from app home is clicked
      if (event.at("/commonEventObject/invokedFunction").asText().equals("updateAppHome")) {
        return updateAppHome();
      }
  }

  return new GenericJson();
}

// Create the app home card
GoogleAppsCardV1Card getHomeCard() {
  return new GoogleAppsCardV1Card()
    .setSections(List.of(new GoogleAppsCardV1Section()
      .setWidgets(List.of(
        new GoogleAppsCardV1Widget()
          .setTextParagraph(new GoogleAppsCardV1TextParagraph()
            .setText("Here is the app home 🏠 It's " + new Date())),
        new GoogleAppsCardV1Widget()
          .setButtonList(new GoogleAppsCardV1ButtonList().setButtons(List.of(new GoogleAppsCardV1Button()
            .setText("Update app home")
            .setOnClick(new GoogleAppsCardV1OnClick()
              .setAction(new GoogleAppsCardV1Action()
                .setFunction("updateAppHome"))))))))));
}

Apps Script

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

apps-script/app-home/app-home.gs

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

/**
 * Responds to a APP_HOME event in Google Chat.
 */
function onAppHome() {
  return { action: { navigations: [{
    pushCard: getHomeCard()
  }]}};
}

/**
 * Returns the app home card.
 */
function getHomeCard() {
  return { sections: [{ widgets: [
    { textParagraph: {
      text: "Here is the app home 🏠 It's " + new Date().toTimeString()
    }},
    { buttonList: { buttons: [{
      text: "Update app home",
      onClick: { action: {
        function: "updateAppHome"
      }}
    }]}}
  ]}]};
}

Как отвечать на действия в главном окне приложения Chat, если оно не является дополнением

В приложении Chat, которое не является дополнением, обрабатывайте события взаимодействия CARD_CLICKED или SUBMIT_FORM с карточкой на главной странице приложения, возвращая ответ, содержащий поле верхнего уровня renderActions с навигацией updateCard:

Node.js

node/app-home/index.js

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

// Update the app home
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}}
};

Python

python/app-home/main.py

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

def update_app_home() -> Mapping[str, Any]:
  """Update the app home

  Returns:
      Mapping[str, Any]: the update card render action
  """
  return { "renderActions": { "action": { "navigations": [{
    "updateCard": get_home_card()
  }]}}}

Java

java/app-home/src/main/java/com/google/chat/app/home/App.java

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

// Update the app home
GenericJson updateAppHome() {
  GenericJson navigation = new GenericJson();
  navigation.set("updateCard", getHomeCard());

  GenericJson action = new GenericJson();
  action.set("navigations", List.of(navigation));

  GenericJson renderActions = new GenericJson();
  renderActions.set("action", action);

  GenericJson response = new GenericJson();
  response.set("renderActions", renderActions);
  return response;
}

Apps Script

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

apps-script/app-home/app-home.gs

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

/**
 * Updates the home app.
 */
function updateAppHome() {
  return { renderActions: { action: { navigations: [{
    updateCard: getHomeCard()
  }]}}};
}