本页面介绍了如何为您的 Chat 应用创建和发送应用首页卡片消息。应用首页是一条可自定义的卡片消息,Chat 应用会在用户打开与 Chat 应用的私信时向其发送该卡片消息。
例如,您可以配置应用首页卡片消息,以添加有关使用斜杠命令与 Chat 应用交互的提示。对于最终用户,只有在应用开发者启用了相关功能后,才能在 Chat 应用的私信中使用应用首页。
使用卡片构建器设计和预览 Chat 应用的 JSON 卡片消息:
打开卡片制作工具前提条件
Python
- 有权访问 Google Chat 的 Google Workspace 帐号。
- 一款已发布的 Chat 应用。如需构建 Chat 应用,请参阅此quickstart。
- 一款经过配置的 Google Chat 应用,可进行互动。如需了解详情,请参阅配置 Google Chat 应用以接收互动事件。
Apps 脚本
- 有权访问 Google Chat 的 Google Workspace 帐号。
- 一款已发布的 Chat 应用。如需构建 Chat 应用,请按照此quickstart操作。
- 一款经过配置的 Google Chat 应用,可进行互动。如需了解详情,请参阅配置 Google Chat 应用以接收互动事件。
在 Google Cloud 控制台中配置
Python
在 Google Cloud 控制台中,依次点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API。
点击管理,然后点击配置标签页。
启用支持应用首页。
选中 Support App Home 复选框。
在 App Home 网址(应用首页网址)字段中,添加网址。此值通常与应用网址相同。系统为
APP_HOME
事件调用此网址。点击保存。
Apps 脚本
在 Google Cloud 控制台中,依次点击菜单 > 更多产品 > Google Workspace > 产品库 > Google Chat API。
点击管理,然后点击配置标签页。
选中 Support App Home 复选框。
点击保存。
配置 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
(用于更新)可用于聊天应用。
相关主题
如需打开对话框,请使用
OPEN_DIALOG
互动。如需了解详情,请参阅打开对话框以响应应用首页卡片消息。如需关闭对话框,请使用
CLOSE_DIALOG
互动关闭对话框并返回到应用首页卡片消息,或使用CLOSE_DIALOG_EXECUTE
互动关闭对话框并刷新应用首页卡片消息。如需了解详情,请参阅响应有关应用首页卡片消息的对话框。如需查看如何创建和发送应用首页卡片消息的示例,请参阅使用 Gemini 构建 Google Chat 应用 Codelab 中的问题管理 Chat 应用。