通过 Incoming Webhook 向 Google…

当需要从脚本或集成向 Google Chat 空间发送通知、卡片消息或线程回复时使用。

适用场景

解决思路

1. 在 Google Chat 中打开目标 Space，点击空间名称，进入 Manage webhooks，创建 webhook（可设置名称和头像 URL），复制 webhook URL；将其存入环境变量或密钥管理器，切勿硬编码。
2. 根据需求选择消息类型：简单通知用文本消息；结构化信息（状态、摘要）用 cardsV2 卡片；持续更新用线程回复；带操作按钮用带 buttonList 的卡片。
3. 使用 assets/webhook-sender.ts 作为发送工具，使用 assets/card-builder.ts 构建结构化卡片。
4. 文本格式化使用 Google Chat 专有语法：粗体 *text*、斜体 _text_、删除线 ~text~、等宽 `text`、代码块 ```text```、链接 <url|text>、提及用户 <users/USER_ID>、提及所有人 <users/all>；不支持 **双星号**、标题、引用块、表格和内联图片。
5. 发送文本消息示例：await sendText(webhookUrl, '*Build Complete*\n\nBranch: `main`\nStatus: Passed\n<https://ci.example.com/123|View Build>');
6. cardsV2 结构：{ cardsV2: [{ cardId: 'unique-id', card: { header: { title, subtitle, imageUrl, imageType: 'CIRCLE' 或 'SQUARE' }, sections: [{ header, widgets: [...] }] } }] }。
7. textParagraph widget：{ textParagraph: { text: '*Status*: All systems operational\n_Last checked_: 5 minutes ago' } }，支持 Google Chat 格式化语法。
8. decoratedText widget 用于键值数据：基础用法 { decoratedText: { topLabel, text, bottomLabel } }；可加 startIcon: { knownIcon: 'STAR' } 或 startIcon: { iconUrl, altText }；可加 button: { text, onClick: { openLink: { url } } }；可加 onClick 使整个 widget 可点击；可加 wrapText: true 让长文本换行。
9. buttonList widget：{ buttonList: { buttons: [{ text, onClick: { openLink: { url } }, color: { red, green, blue, alpha }, icon: { knownIcon } }] } }，支持单个或多个按钮。
10. image widget：{ image: { imageUrl, altText } }。
11. divider widget：{ divider: {} }，用于分隔 widget。
12. 可折叠 section：{ header, collapsible: true, uncollapsibleWidgetsCount: 2, widgets: [...] }，前 N 个 widget 可见，其余折叠。
13. knownIcon 可用值包括：AIRPLANE、BOOKMARK、BUS、CAR、CLOCK、CONFIRMATION_NUMBER_ICON、DESCRIPTION、DOLLAR、EMAIL、INVITE、MAP_PIN、MEMBERSHIP、MULTIPLE_PEOPLE、OFFER、PERSON、PHONE、SHOPPING_CART、STAR、STORE、TICKET、VIDEO_CAMERA；不在列表中的图标使用 iconUrl 指向公开可访问的方形图片（建议 24x24 或 48x48 像素）。
14. 线程消息：首条消息发送时传 { threadKey: 'deploy-2026-02-16' } 创建线程；回复时在 webhook URL 后追加 &messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD，并传相同的 threadKey；threadKey 是客户端自定义字符串，相关消息使用一致 key（如 deploy-{date}、alert-{id}）。
15. 通知卡片模式：用 buildCard 构建，包含 cardId、title、subtitle、imageUrl、sections，widgets 中使用 decoratedText 展示 Environment、Version、Status 等，并用 buttonList 添加查看链接按钮。
16. 摘要卡片模式：用 buildCard 构建，包含多个 section，第一个 section 用 header 和 decoratedText 列表展示 Highlights，第二个 section 放 buttonList 的 View All 按钮。
17. 错误预防：文本中不要用 **bold**，改用 *bold*；链接不要用 [text](url)，改用 <url|text>；卡片必须包裹在 { cardsV2: [{ cardId, card }] } 中；线程回复不生效时在 webhook URL 追加 &messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD；webhook 返回 400 时检查 JSON 结构，常见问题是顶层缺少 text 或 cardsV2；卡片不显示时确保 sections 至少有一个 widget。

适用边界 · 注意事项

• 需要双向交互或读取消息（如接收用户回复、管理空间成员）时，incoming webhook 只能单向发送，不适用。
• 需要发送内联图片、表格、标题、引用块或标准 Markdown 时，Google Chat 不支持这些格式。
• 没有 Google Chat 空间管理权限或无法创建 webhook 时无法使用。