SKILL.md
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:
- Open a Space > click space name > Manage webhooks
- Create webhook (name it, optionally add avatar URL)
- 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
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
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).
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>`).
{
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:**
{
decoratedText: {
topLabel: 'Environment',
text: 'Production',
bottomLabel: 'Last deployed 2h ago'
}
}
**With start icon:**
{
decoratedText: {
topLabel: 'Status',
text: 'Healthy',
startIcon: { knownIcon: 'STAR' }
}
}
**With custom icon URL:**
{
decoratedText: {
topLabel: 'GitHub',
text: 'PR #142 merged',
startIcon: {
iconUrl: 'https://github.githubassets.com/favicons/favicon.svg',
altText: 'GitHub'
}
}
}
**With button:**
{
decoratedText: {
topLabel: 'Alert',
text: 'CPU at 95%',
button: {
text: 'View',
onClick: { openLink: { url: 'https://monitoring.example.com' } }
}
}
}
**Clickable (whole widget):**
{
decoratedText: {
text: 'View full report',
wrapText: true,
onClick: { openLink: { url: 'https://reports.example.com' } }
}
}
**With wrap text:**
{
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:**
{
buttonList: {
buttons: [{
text: 'Open Dashboard',
onClick: { openLink: { url: 'https://dashboard.example.com' } }
}]
}
}
**Multiple buttons:**
{
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:**
{
buttonList: {
buttons: [{
text: 'View on GitHub',
icon: { knownIcon: 'BOOKMARK' },
onClick: { openLink: { url: 'https://github.com/org/repo/pull/42' } }
}]
}
}
### image
Standalone image widget.
{
image: {
imageUrl: 'https://example.com/chart.png',
altText: 'Monthly usage chart'
}
}
### divider
Horizontal line separator between widgets.
{ divider: {} }
### Collapsible Sections
Sections can be collapsed with only the first N widgets visible:
{
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.
{ 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`:
// 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
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)
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 } } }]
}
}]
}
]
});