google-chat-messages

# Google Chat Messages Send messages to Google Chat spaces via incoming webhooks. Produces text messages, rich cards (cardsV2), and threaded replies. ## What You Produce - Text messages with Google Chat formatting - Rich card messages (cardsV2) with headers, sections, widgets - Threaded conversations - Reusable webhook sender utility ## Workflow ### Step 1: Get Webhook URL In Google Chat: 1. Open a Space > click space name > **Manage webhooks** 2. Create webhook (name it, optionally add avatar URL) 3. Copy the webhook URL Store the URL as an environment variable or in your secrets manager — never hardcode. ### Step 2: Choose Message Type | Need | Type | Complexity | |------|------|------------| | Simple notification | Text message | Low | | Structured info (status, digest) | Card message (cardsV2) | Medium | | Ongoing updates | Threaded replies | Medium | | Action buttons (open URL) | Card with buttonList | Medium | ### Step 3: Send the Message Use `assets/webhook-sender.ts` for the sender utility. Use `assets/card-builder.ts` for structured card construction. ## Text Formatting Google Chat does NOT use standard Markdown. | Format | Syntax | Example | |--------|--------|---------| | Bold | `*text*` | `*important*` | | Italic | `_text_` | `_emphasis_` | | Strikethrough | `~text~` | `~removed~` | | Monospace | `` `text` `` | `` `code` `` | | Code block | ` ```text``` ` | Multi-line code | | Link | `<url\|text>` | `<https://example.com\|Click here>` | | Mention user | `<users/USER_ID>` | `<users/123456>` | | Mention all | `<users/all>` | `<users/all>` | **Not supported**: `**double asterisks**`, headings (`###`), blockquotes, tables, images inline. ### Text Message Example ```typescript await sendText(webhookUrl, '*Build Complete*\n\nBranch: `main`\nStatus: Passed\n<https://ci.example.com/123|View Build>'); ``` ## cardsV2 Structure Cards use the cardsV2 format (recommended over legacy cards). ```typescript const message = { cardsV2: [{ cardId: 'unique-id', card: { header: { title: 'Card Title', subtitle: 'Optional subtitle', imageUrl: 'https://example.com/icon.png', imageType: 'CIRCLE' // or 'SQUARE' }, sections: [{ header: 'Section Title', // optional widgets: [ // widgets go here ] }] } }] }; ``` ## Widget Reference All widget types available in cardsV2 sections. ### textParagraph Formatted text block. Supports Google Chat formatting (`*bold*`, `_italic_`, `<url|text>`). ```typescript { textParagraph: { text: '*Status*: All systems operational\n_Last checked_: 5 minutes ago' } } ``` ### decoratedText Labelled value with optional icons. Most versatile widget for key-value data. **Basic:** ```typescript { decoratedText: { topLabel: 'Environment', text: 'Production', bottomLabel: 'Last deployed 2h ago' } } ``` **With start icon:** ```typescript { decoratedText: { topLabel: 'Status', text: 'Healthy', startIcon: { knownIcon: 'STAR' } } } ``` **With custom icon URL:** ```typescript { decoratedText: { topLabel: 'GitHub', text: 'PR #142 merged', startIcon: { iconUrl: 'https://github.githubassets.com/favicons/favicon.svg', altText: 'GitHub' } } } ``` **With button:** ```typescript { decoratedText: { topLabel: 'Alert', text: 'CPU at 95%', button: { text: 'View', onClick: { openLink: { url: 'https://monitoring.example.com' } } } } } ``` **Clickable (whole widget):** ```typescript { decoratedText: { text: 'View full report', wrapText: true, onClick: { openLink: { url: 'https://reports.example.com' } } } } ``` **With wrap text:** ```typescript { decoratedText: { topLabel: 'Description', text: 'This is a longer description that should wrap to multiple lines instead of being truncated', wrapText: true } } ``` ### buttonList One or more action buttons. Buttons open URLs or trigger actions. **Single button:** ```typescript { buttonList: { buttons: [{ text: 'Open Dashboard', onClick: { openLink: { url: 'https://dashboard.example.com' } } }] } } ``` **Multiple buttons:** ```typescript { buttonList: { buttons: [ { text: 'Approve', onClick: { openLink: { url: 'https://app.example.com/approve/123' } }, color: { red: 0, green: 0.5, blue: 0, alpha: 1 } }, { text: 'Reject', onClick: { openLink: { url: 'https://app.example.com/reject/123' } } } ] } } ``` **Button with icon:** ```typescript { buttonList: { buttons: [{ text: 'View on GitHub', icon: { knownIcon: 'BOOKMARK' }, onClick: { openLink: { url: 'https://github.com/org/repo/pull/42' } } }] } } ``` ### image Standalone image widget. ```typescript { image: { imageUrl: 'https://example.com/chart.png', altText: 'Monthly usage chart' } } ``` ### divider Horizontal line separator between widgets. ```typescript { divider: {} } ``` ### Collapsible Sections Sections can be collapsed with only the first N widgets visible: ```typescript { header: 'Details', collapsible: true, uncollapsibleWidgetsCount: 2, // Show first 2, collapse rest widgets: [ { decoratedText: { topLabel: 'Status', text: 'Active' } }, { decoratedText: { topLabel: 'Region', text: 'AU' } }, // These start collapsed { decoratedText: { topLabel: 'Instance', text: 'prod-01' } }, { decoratedText: { topLabel: 'Memory', text: '2.1 GB' } }, { decoratedText: { topLabel: 'CPU', text: '45%' } } ] } ``` ## Known Icons Icons available via `knownIcon` in decoratedText and button widgets. ```typescript { startIcon: { knownIcon: 'STAR' } } // or { icon: { knownIcon: 'EMAIL' } } ``` | Icon Name | Use For | |-----------|---------| | `AIRPLANE` | Travel, flights | | `BOOKMARK` | Save, reference, links | | `BUS` | Transport, transit | | `CAR` | Driving, transport | | `CLOCK` | Time, duration, schedule | | `CONFIRMATION_NUMBER_ICON` | Tickets, bookings | | `DESCRIPTION` | Documents, files | | `DOLLAR` | Money, pricing, cost | | `EMAIL` | Email, messages | | `INVITE` | Invitations | | `MAP_PIN` | Location, address | | `MEMBERSHIP` | Members, users | | `MULTIPLE_PEOPLE` | Teams, groups | | `OFFER` | Deals, promotions | | `PERSON` | Individual user | | `PHONE` | Phone number, calls | | `SHOPPING_CART` | Commerce, purchases | | `STAR` | Rating, favourite, important | | `STORE` | Shop, retail | | `TICKET` | Tickets, events | | `VIDEO_CAMERA` | Video, meetings | For icons not in the list, use `iconUrl` with any publicly accessible image (square, ideally 24x24 or 48x48 pixels). ## Threading Thread messages together using `threadKey`: ```typescript // First message — creates thread const response = await sendCard(webhookUrl, card, { threadKey: 'deploy-2026-02-16' }); // Reply to thread — append &messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD const threadUrl = `${webhookUrl}&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD`; await sendCard(threadUrl, replyCard, { threadKey: 'deploy-2026-02-16' }); ``` The `threadKey` is a client-assigned string. Use consistent keys for related messages (e.g., `deploy-{date}`, `alert-{id}`). ## Common Patterns ### Notification Card ```typescript import { buildCard, sendCard } from './assets/card-builder'; import { sendWebhook } from './assets/webhook-sender'; const card = buildCard({ cardId: 'deploy-notification', title: 'Deployment Complete', subtitle: 'production - v2.1.0', imageUrl: 'https://example.com/your-icon.png', sections: [{ widgets: [ { decoratedText: { topLabel: 'Environment', text: 'Production' } }, { decoratedText: { topLabel: 'Version', text: 'v2.1.0' } }, { decoratedText: { topLabel: 'Status', text: '*Healthy*', startIcon: { knownIcon: 'STAR' } } }, { buttonList: { buttons: [{ text: 'View Deployment', onClick: { openLink: { url: 'https://dash.example.com' } } }] } } ] }] }); ``` ### Digest Card (Weekly Summary) ```typescript const digest = buildCard({ cardId: 'weekly-digest', title: 'Weekly Summary', subtitle: `${count} updates this week`, sections: [ { header: 'Highlights', widgets: items.map(item => ({ decoratedText: { text: item.title, bottomLabel: item.date } })) }, { widgets: [{ buttonList: { buttons: [{ text: 'View All', onClick: { openLink: { url: dashboardUrl } } }] } }] } ] }); ``` ## Error Prevention | Mistake | Fix | |---------|-----| | `**bold**` in text | Use `*bold*` (single asterisks) | | `[text](url)` links | Use `<url\|text>` format | | Missing `cardsV2` wrapper | Wrap card in `{ cardsV2: [{ cardId, card }] }` | | Thread replies not threading | Append `&messageReplyOption=REPLY_MESSAGE_FALLBACK_TO_NEW_THREAD` to webhook URL | | Webhook returns 400 | Check JSON structure — common issue is missing `text` or `cardsV2` at top level | | Card not showing | Ensure `sections` has at least one widget | ## Asset Files | File | Purpose | |------|---------| | `assets/types.ts` | TypeScript type definitions for cardsV2 | | `assets/card-builder.ts` | Utility to build card messages | | `assets/webhook-sender.ts` | POST to webhook with error handling |