Google Chat API

Status: Production Ready Last Updated: 2026-01-09 (Added: Spaces API, Members API, Reactions API, Rate Limits) Dependencies: Cloudflare Workers (recommended), Web Crypto API for token verification Latest Versions: Google Chat API v1 (stable), Cards v2 (Cards v1 deprecated), [email protected]

---

Quick Start (5 Minutes)

1. Create Webhook (Simplest Approach)

# No code needed - just configure in Google Chat
# 1. Go to Google Cloud Console
# 2. Create new project or select existing
# 3. Enable Google Chat API
# 4. Configure Chat app with webhook URL

Webhook URL: https://your-worker.workers.dev/webhook

Why this matters:

• Simplest way to send messages to Chat
• No authentication required for incoming webhooks
• Perfect for notifications from external systems
• Limited to sending messages (no interactive responses)

2. Create Interactive Bot (Cloudflare Worker)

export default {
  async fetch(request: Request, env: Env): Promise<Response> {
    const event = await request.json()

    // Respond with a card
    return Response.json({
      text: "Hello from bot!",
      cardsV2: [{
        cardId: "unique-card-1",
        card: {
          header: { title: "Welcome" },
          sections: [{
            widgets: [{
              textParagraph: { text: "Click the button below" }
            }, {
              buttonList: {
                buttons: [{
                  text: "Click me",
                  onClick: {
                    action: {
                      function: "handleClick",
                      parameters: [{ key: "data", value: "test" }]
                    }
                  }
                }]
              }
            }]
          }]
        }
      }]
    })
  }
}

CRITICAL:

• Must respond within timeout (typically 30 seconds)
• Always return valid JSON with cardsV2 array
• Card schema must be exact - one wrong field breaks the whole card

3. Verify Bearer Tokens (Production Security)

async function verifyToken(token: string): Promise<boolean> {
  // Verify token is signed by [email protected]
  // See templates/bearer-token-verify.ts for full implementation
  return true
}

Why this matters:

• Prevents unauthorized access to your bot
• Required for HTTP endpoints (not webhooks)
• Uses Web Crypto API (Cloudflare Workers compatible)

---

The 3-Step Setup Process

Step 1: Choose Integration Type

Option A: Incoming Webhook (Notifications Only)

Best for:

• CI/CD notifications
• Alert systems
• One-way communication
• External service → Chat

Setup:

1. Create Chat space
2. Configure incoming webhook in Space settings
3. POST JSON to webhook URL

No code required - just HTTP POST:

curl -X POST 'https://chat.googleapis.com/v1/spaces/.../messages?key=...' \
  -H 'Content-Type: application/json' \
  -d '{"text": "Hello from webhook!"}'

Option B: HTTP Endpoint Bot (Interactive)

Best for:

• Interactive forms
• Button-based workflows
• User input collection
• Chat → Your service → Chat

Setup:

1. Create Google Cloud project
2. Enable Chat API
3. Configure Chat app with HTTP endpoint
4. Deploy Cloudflare Worker
5. Handle events and respond with cards

Requires code - see templates/interactive-bot.ts

Step 2: Design Cards (If Using Interactive Bot)

IMPORTANT: Use Cards v2 only. Cards v1 was deprecated in 2025. Cards v2 matches Material Design on web (faster rendering, better aesthetics).

Cards v2 structure:

{
  "cardsV2": [{
    "cardId": "unique-id",
    "card": {
      "header": {
        "title": "Card Title",
        "subtitle": "Optional subtitle",
        "imageUrl": "https://..."
      },
      "sections": [{
        "header": "Section 1",
        "widgets": [
          { "textParagraph": { "text": "Some text" } },
          { "buttonList": { "buttons": [...] } }
        ]
      }]
    }
  }]
}

Widget Types:

• textParagraph - Text content
• buttonList - Buttons (text or icon)
• textInput - Text input field
• selectionInput - Dropdowns, checkboxes, switches
• dateTimePicker - Date/time selection
• divider - Horizontal line
• image - Images
• decoratedText - Text with icon/button

Text Formatting (NEW: Sept 2025 - GA):

Cards v2 supports both HTML and Markdown formatting:

// HTML formatting (traditional)
{
  textParagraph: {
    text: "This is <b>bold</b> and <i>italic</i> text with <font color='#ea9999'>color</font>"
  }
}

// Markdown formatting (NEW - better for AI agents)
{
  textParagraph: {
    text: "This is **bold** and *italic* text\n\n- Bullet list\n- Second item\n\n```\ncode block\n```"
  }
}

Supported Markdown (text messages and cards):

• **bold** or *italic*
• `code` for inline code
• - list item or 1. ordered for lists
• ```code block``` for multi-line code
• ~strikethrough~

Supported HTML (cards only):

• <b>bold</b>, <i>italic</i>, <u>underline</u>
• <font color="#FF0000">colored</font>
• <a href="url">link</a>

Why Markdown matters: LLMs naturally output Markdown. Before Sept 2025, you had to convert Markdown→HTML. Now you can pass Markdown directly to Chat.

CRITICAL:

• Max 100 widgets per card - silently truncated if exceeded
• Widget order matters - displayed top to bottom
• cardId must be unique - use timestamp or UUID

Step 3: Handle User Interactions

When user clicks button or submits form:

export default {
  async fetch(request: Request): Promise<Response> {
    const event = await request.json()

    // Check event type
    if (event.type === 'MESSAGE') {
      // User sent message
      return handleMessage(event)
    }

    if (event.type === 'CARD_CLICKED') {
      // User clicked button
      const action = event.action.actionMethodName
      const params = event.action.parameters

      if (action === 'submitForm') {
        return handleFormSubmission(event)
      }
    }

    return Response.json({ text: "Unknown event" })
  }
}

Event Types:

• ADDED_TO_SPACE - Bot added to space
• REMOVED_FROM_SPACE - Bot removed
• MESSAGE - User sent message
• CARD_CLICKED - User clicked button/submitted form

---

Critical Rules

Always Do

✅ Return valid JSON with cardsV2 array structure ✅ Set unique cardId for each card ✅ Verify bearer tokens for HTTP endpoints (production) ✅ Handle all event types (MESSAGE, CARD_CLICKED, etc.) ✅ Keep widget count under 100 per card ✅ Validate form inputs server-side

Never Do

❌ Store secrets in code (use Cloudflare Workers secrets) ❌ Exceed 100 widgets per card (silently fails) ❌ Return malformed JSON (breaks entire message) ❌ Skip bearer token verification (security risk) ❌ Trust client-side validation only (validate server-side) ❌ Use synchronous blocking operations (timeout risk)

---

Known Issues Prevention

This skill prevents 6 documented issues:

Issue #1: Bearer Token Verification Fails (401)

Error: "Unauthorized" or "Invalid credentials" Source: Google Chat API Documentation Why It Happens: Token not verified or wrong verification method Prevention: Template includes Web Crypto API verification (Cloudflare Workers compatible)

Issue #2: Invalid Card JSON Schema (400)

Error: "Invalid JSON payload" or "Unknown field" Source: Cards v2 API Reference Why It Happens: Typo in field name, wrong nesting, or extra fields Prevention: Use google-chat-cards library or templates with exact schema

Issue #3: Widget Limit Exceeded (Silent Failure)

Error: No error - widgets beyond 100 simply don't render Source: Google Chat API Limits Why It Happens: Adding too many widgets to single card Prevention: Skill documents 100 widget limit + pagination patterns

Issue #4: