向 Google Chat 应用发送应用首页卡片消息

本页面介绍了如何为您的 Chat 应用创建和发送应用首页卡片消息。应用首页是一条可自定义的卡片消息，Chat 应用会在用户打开与 Chat 应用的私信时向其发送该卡片消息。

包含两条消息的应用首页卡片。

例如，您可以配置应用首页卡片消息，以添加有关使用斜杠命令与 Chat 应用交互的提示。对于最终用户，只有在应用开发者启用了相关功能后，才能在 Chat 应用的私信中使用应用首页。

使用卡片构建器设计和预览 Chat 应用的 JSON 卡片消息：

打开卡片制作工具

前提条件

Python

Apps 脚本

在 Google Cloud 控制台中配置

Python

  1. 在 Google Cloud 控制台中，依次点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API。

    前往 Google Chat API

  2. 点击管理，然后点击配置标签页。

  3. 启用支持应用首页。

  4. 选中 Support App Home 复选框。

  5. 在 App Home 网址（应用首页网址）字段中，添加网址。此值通常与应用网址相同。系统为 APP_HOME 事件调用此网址。

  6. 点击保存。

Apps 脚本

  1. 在 Google Cloud 控制台中，依次点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API。

    前往 Google Chat API

  2. 点击管理，然后点击配置标签页。

  3. 选中 Support App Home 复选框。

  4. 点击保存。

配置 Chat 应用

配置 Chat 应用，以发送应用首页的新卡片消息。

Python

当用户从 Chat 应用打开私信时，系统会向您的 Chat 应用发送 APP_HOME 事件。当 Chat 应用收到此事件时，系统会通过 pushCard 导航返回 RenderActions 的 JSON 实例。

@app.route('/', methods=['POST'])
def on_event():
  event = request.get_json()
  chat = event.get('chat')
  if chat is not None:
    return handle_chat_event(event)

def handle_chat_event(event):
  if event['chat'].get('type') == 'APP_HOME':
    return get_app_home_card()

def get_app_home_card():
  return {
    "action": {
      "navigations": [
        {
          "pushCard": {
            "sections": [
              {
                "widgets": [
                  {
                    "buttonList": {
                      "buttons": [
                        {
                          "text": "Open documentation",
                          "onClick": {
                            "openLink": {
                              "url": "https://developers.google.com/chat"
                            }
                          }
                        }
                      ]
                    }
                  }
                ]
              }
            ]
          }
        }
      ]
    }
  }

Apps 脚本

此示例通过返回卡片 JSON 来发送卡片消息。您也可以使用 Apps 脚本卡片服务。

实现 onAppHome 函数，以使用 pushCard 导航返回 RenderActions 的 JSON 实例：

// "onAppHome" is the pre-defined name of the callback that the Chat servers
// execute.
function onAppHome() {
  return {
    action: {
      navigations: [
        {
          pushCard: getCard()
        }
      ]
    }
  };
}

function getCard() {
  return {
    sections: [
      {
        widgets: [
          {
            buttonList: {
              buttons: [
                {
                  text: "Open documentation",
                  onClick: {
                    openLink: {
                      url: "https://developers.google.com/chat"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  };
}

更新应用首页卡片消息

当用户提交卡片消息中的信息或关闭对话框时，应用首页卡片消息可以更新。例如，初始应用首页卡片消息是一条欢迎消息，要求用户在表单中填写信息。用户填好该表单后，系统会发送更新后的应用首页卡片消息。该更新必须通过包含 updateCard 导航的 RenderActions 实例返回。

Python

对于 HTTP 应用，更新应用首页卡片消息与处理用户输入的信息类似，但您必须返回 RenderActions。invokedFunction 表示与 Card widget 关联的被调用函数的名称。如需了解详情，请参阅 CommonEventObject。在以下示例中，submitForm 显示用户已提交表单数据：

@app.route('/', methods=['POST'])
def on_event():
  event = request.get_json()
  chat = event.get('chat')
  if chat is not None:
    return handle_chat_event(event)

def handle_chat_event(event):
  if event['chat'].get('type') == 'SUBMIT_FORM':
    event_object = event.get('commonEventObject')
    if event_object is not None:
      // Forms
      if 'submitForm' == event_object.get('invokedFunction'):
        return {
          'render_actions': {
            'action': {
              'navigations': [{
                'updateCard': get_update_card()
              }]
            }
          }
        }

def get_update_card():
  return {
      "action": {
          "navigations": [{
              "pushCard": {
                  "sections": [{
                      "widgets": [{
                          "buttonList": {
                              "buttons": [{
                                  "text": "Open documentation",
                                  "onClick": {
                                      "openLink": {
                                          "url": "https://developers.google.com/chat"
                                      }
                                  },
                              }]
                          }
                      }]
                  }]
              }
          }]
      }
  }

Apps 脚本

此示例通过返回卡片 JSON 来发送卡片消息。您也可以使用 Apps 脚本卡片服务。

// Called from elsewhere (i.e. on button press).
function updateAppHomeCard(event) {
  return {
    render_actions: {
      action: {
        navigations: [
          {
            updateCard: getCard()
          }
        ]
      }
    }
  }
}

function getCard() {
  return {
    sections: [
      {
        widgets: [
          {
            buttonList: {
              buttons: [
                {
                  text: "Open documentation",
                  onClick: {
                    openLink: {
                      url: "https://developers.google.com/chat"
                    }
                  }
                }
              ]
            }
          }
        ]
      }
    ]
  };
}

限制

通常，navigation 不适用于聊天应用。您无法返回堆叠的卡。只有 pushCard（用于初始响应）和 updateCard（用于更新）可用于聊天应用。