Google Chat API Development Skill

This skill provides comprehensive guidance for working with the Google Chat API, including REST resources, authentication, interactive cards, and best practices.

When to Use This Skill

Use this skill when:

Developing Google Chat applications or bots
Working with Google Chat REST API endpoints
Troubleshooting Google Chat API issues
Implementing Cards v2 interactive UI
Managing authentication and authorization
Handling rate limits and quotas
Creating webhooks or event handlers
Building proactive messaging features

Quick Start

API Basics

Service Endpoint: https://chat.googleapis.com
API Version: v1

Core REST Resources

The Google Chat API provides 13 main resource types:

Spaces (v1.spaces) - Conversations and chat rooms
Messages (v1.spaces.messages) - Message content and cards
Members (v1.spaces.members) - Membership management
Reactions (v1.spaces.messages.reactions) - Emoji reactions
Attachments (v1.spaces.messages.attachments) - File attachments
Media (v1.media) - Upload/download operations
Custom Emojis (v1.customEmojis) - Organization emojis
Space Events (v1.spaces.spaceEvents) - Event history
User Spaces (v1.users.spaces) - User read states
User Threads (v1.users.spaces.threads) - Thread read states
Space Notification Settings (v1.users.spaces.spaceNotificationSetting) - User notifications
Sections (v1.users.sections) - Space organization [Preview]
Section Items (v1.users.sections.items) - Items in sections [Preview]

Development Workflow

1. Understanding Authentication

Decision Tree:

Are you responding to a user interaction (MESSAGE, CARD_CLICKED)?
  → No authentication needed (synchronous response)

Need to send proactive/scheduled messages?
  → App authentication with chat.bot scope

Need user-specific operations (reactions, read states)?
  → User authentication with appropriate OAuth scopes

Need admin domain-wide access?
  → User authentication with chat.admin.* scopes

For detailed authentication guidance, see reference/authentication.md

2. Building Messages

Simple Text Message

{
  "text": "Hello, World!"
}

Formatted Text Message

{
  "text": "*Bold* _italic_ `code` ~strikethrough~\n\n• Bullet point\n1. Numbered list"
}

For complete formatting syntax (bold, italic, code blocks, lists, mentions, etc.), see reference/message-formatting.md

Message with Cards v2

{
  "text": "Fallback text",
  "cardsV2": [{
    "cardId": "unique-card-id",
    "card": {
      "header": {"title": "Card Title"},
      "sections": [{
        "widgets": [
          {"textParagraph": {"text": "Card content"}},
          {"buttonList": {"buttons": [{
            "text": "Click me",
            "onClick": {"action": {"function": "handleClick"}}
          }]}}
        ]
      }]
    }
  }]
}

For complete Cards v2 reference, see reference/cards-v2.md

3. Common Operations

The scripts/ directory contains helper scripts for common operations. All scripts use Application Default Credentials (ADC) for secure authentication.

One-time setup:

gcloud auth application-default login \
  --scopes=https://www.googleapis.com/auth/chat.bot,https://www.googleapis.com/auth/chat.spaces.create

Scripts:

create_space.py - Create spaces programmatically
send_message.py - Send messages with optional cards
handle_events.py - Process webhook events
manage_auth.py - Authentication helpers and ADC setup guide
test_webhook.py - Test message formatting via webhook (no auth needed!)

Example usage:

python scripts/create_space.py --name "My Space" --type SPACE
python scripts/send_message.py --space "spaces/AAAA" --text "Hello"
python scripts/manage_auth.py --type setup  # View ADC setup instructions
python scripts/test_webhook.py --url "WEBHOOK_URL" --text "*Bold* test"  # Quick testing

4. Working with the API

REST Resource Pattern

All resources follow this naming pattern:

{resource}/{id}/{subresource}/{subid}

Examples:
spaces/AAAAbbbb
spaces/AAAAbbbb/messages/CCCCdddd
spaces/AAAAbbbb/members/EEEEffff

Common HTTP Methods

Operation	Method	Example
Get resource details	`GET`	`GET /v1/spaces/AAAA`
List resources	`GET`	`GET /v1/spaces`
Create resource	`POST`	`POST /v1/spaces`
Update resource	`PATCH`	`PATCH /v1/spaces/AAAA`
Delete resource	`DELETE`	`DELETE /v1/spaces/AAAA`

5. Rate Limits

Critical Limits to Remember:

Per-space writes: 1 request/second (shared across ALL apps!)
Message writes (per-project): 3,000 requests/60 seconds
Space writes (per-project): 60 requests/60 seconds

Always implement exponential backoff for 429 errors. See reference/rate-limits.md for details.

6. Interactive Cards

Cards v2 provides rich interactive UI elements:

Available Widgets:

Text paragraphs with HTML formatting
Images with click actions
Buttons (filled, outlined, borderless)
Text inputs (single/multi-line)
Selection inputs (dropdown, checkbox, radio, multi-select)
Date/time pickers
Grids, columns, carousels
Chips and dividers

For complete widget reference and examples, see reference/cards-v2.md

Debugging and Troubleshooting

Common Issues

Authentication Errors (401)
- Verify OAuth scopes match the operation
- Check token expiration
- Ensure service account has required permissions
Rate Limit Errors (429)
- Implement exponential backoff
- Check per-space vs per-project quotas
- Consider request batching
Permission Errors (403)
- Verify app is a member of the space
- Check if admin approval is required for scope
- Validate user has necessary permissions
Invalid Request (400)
- Validate JSON structure
- Check required fields are present
- Verify resource name format

Debugging Steps

Check the reference documentation in reference/ for the specific resource
Review authentication requirements - ensure correct auth type and scopes
Validate request structure - compare against examples in reference docs
Check rate limits - implement exponential backoff if hitting 429s
Review error response - Google returns detailed error messages

Reference Documentation

This skill includes detailed reference files:

reference/rest-api.md - Complete REST resource reference
reference/cards-v2.md - Cards v2 widget and action reference
reference/authentication.md - Auth types, scopes, and examples
reference/rate-limits.md - Quota management and backoff strategies

Code Patterns

Python Quick Examples

# Using Application Default Credentials (ADC)
from google.auth import default
from googleapiclient.discovery import build

# Automatically finds credentials (gcloud ADC or service account)
creds, project = default()
chat = build('chat', 'v1', credentials=creds)

# Create a space
space = chat.spaces().create(body={
    'spaceType': 'SPACE',
    'displayName': 'My Space'
}).execute()

# Send a message
message = chat.spaces().messages().create(
    parent='spaces/SPACE_ID',
    body={'text': 'Hello from Python!'}
).execute()

# List messages
messages = chat.spaces().messages().list(
    parent='spaces/SPACE_ID',
    pageSize=10
).execute()

Node.js Quick Examples

const {chat} = require('@googleapis/chat');
const {auth} = require('google-auth-library');

const authClient = new auth.GoogleAuth({
    keyFile: 'service_account.json',
    scopes: ['https://www.googleapis.com/auth/chat.bot']
});

const chatClient = await chat({
    version: 'v1',
    auth: await authClient.getClient()
});

// Send message
await chatClient.spaces.messages.create({
    parent: 'spaces/SPACE_ID',
    requestBody: {
        text: 'Hello from Node.js!'
    }
});

Best Practices

Use minimal scopes - Request only what you need
Implement error handling - Always handle 429, 401, 403, 400 errors
Cache when possible - Reduce redundant API calls
Monitor quota usage - Via Google Cloud Console
Secure credentials - Never commit service account keys
Validate webhook requests - Ensure requests come from Google
Use exponential backoff - For rate limit errors
Consider per-space limits - The 1 req/sec write limit is shared!

Additional Resources

Local reference files - See reference/ directory
Example scripts - See scripts/ directory
Official documentation - https://developers.google.com/workspace/chat
API reference - https://developers.google.com/workspace/chat/api/reference/rest

Getting Started Checklist

When starting a new Chat app project:

Remember: This skill contains extensive reference documentation. When you need specific details about resources, widgets, authentication, or rate limits, consult the appropriate file in the reference/ directory.

google-chat-api