google-chat

Google Chat Messaging

Send messages to Google Chat using two methods:

1. Webhooks - Fast, pre-configured channels (messages appear as a bot)
2. OAuth - Dynamic messaging to any space or user (requires authentication)

Quick Start

Method 1: Webhooks (Recommended for Known Channels)

Send to a pre-configured channel:

python3 scripts/send_webhook.py "$WEBHOOK_URL" "Your message here"

Example with threading:

python3 scripts/send_webhook.py "$WEBHOOK_URL" "Reply message" --thread_key "unique-thread-id"

Configuration: Store webhooks in google-chat-config.json:

{
  "webhooks": {
    "acs_engineering_network": "https://chat.googleapis.com/v1/spaces/...",
    "general": "https://chat.googleapis.com/v1/spaces/..."
  }
}

Read config and send:

WEBHOOK_URL=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK_URL" "Deploy completed ✅"

Method 2: OAuth (For Dynamic Messaging)

First-time setup:

1. Save OAuth credentials to a file (e.g., google-chat-oauth-credentials.json)
2. Run initial authentication (opens browser, saves token):

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "General" \
  "Test message"

Send to a space by name:

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "Deploy completed"

Note: OAuth messages automatically include 🤖 emoji prefix. Use --no-emoji to disable this:

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space "Engineering Network" \
  "Message without emoji" \
  --no-emoji

List available spaces:

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --list-spaces

Send to a DM (requires existing space ID):

# Note: Google Chat API doesn't support creating new DMs by email
# You need the space ID of an existing DM conversation
python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/xxxxx" \
  "The report is ready"

Send to space by ID (faster):

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --space-id "spaces/AAAALtlqgVA" \
  "Direct message to space"

Dependencies

Install required Python packages:

pip install google-auth-oauthlib google-auth-httplib2 google-api-python-client

Required OAuth Scopes:

• https://www.googleapis.com/auth/chat.messages - Send messages
• https://www.googleapis.com/auth/chat.spaces - Access space information
• https://www.googleapis.com/auth/chat.memberships.readonly - List space members (for DM identification)

OAuth Setup Guide

If OAuth credentials don't exist yet:

1. Go to Google Cloud Console
2. Select your project or create one
3. Enable Google Chat API
4. Go to APIs & Services → Credentials
5. Create OAuth 2.0 Client ID (Desktop app type)
6. Download JSON and save as google-chat-oauth-credentials.json

The credentials JSON should look like:

{
  "installed": {
    "client_id": "...apps.googleusercontent.com",
    "client_secret": "GOCSPX-...",
    "redirect_uris": ["http://localhost"],
    ...
  }
}

Webhook Setup Guide

To create a webhook for a Google Chat space:

1. Open Google Chat in browser
2. Go to the space
3. Click space name → Apps & integrations
4. Click Manage webhooks → Add webhook
5. Give it a name (e.g., "Agustin Networks")
6. Copy the webhook URL
7. Add to google-chat-config.json

Choosing the Right Method

Use Webhooks when:

• Sending to the same channels repeatedly
• Messages should appear as a bot/service
• Speed is important (no OAuth handshake)
• Configuration is static

Use OAuth when:

• Sending to different spaces dynamically
• Messages should appear from your configured Google Chat App
• Space names are determined at runtime
• Need to list and discover available spaces

OAuth Limitations:

• Cannot create new DMs by email address (Google Chat API restriction)
• To send DMs, you need the space ID of an existing conversation
• Use --list-spaces to find available DM space IDs

Message Formatting

Both methods support simple text. For advanced formatting (cards, buttons), construct JSON payloads:

Webhook with card:

import json
import urllib.request

payload = {
    "cardsV2": [{
        "cardId": "unique-card-id",
        "card": {
            "header": {"title": "Deploy Status"},
            "sections": [{
                "widgets": [{
                    "textParagraph": {"text": "Production deploy completed successfully"}
                }]
            }]
        }
    }]
}

data = json.dumps(payload).encode("utf-8")
req = urllib.request.Request(webhook_url, data=data, headers={"Content-Type": "application/json"})
urllib.request.urlopen(req)

Troubleshooting

Webhook errors:

• Verify webhook URL is correct and active
• Check space still exists and webhook wasn't deleted
• Ensure message isn't empty

OAuth errors:

• Run authentication flow again if token expired
• Verify Google Chat API is enabled in Cloud Console
• Check user has access to the target space
• For DMs, ensure user email is correct and in same workspace

Permission errors:

• Webhooks: Must be member of the space
• OAuth: Must have access to target space or user
• Corporate Workspace: Some features may be restricted by admin policies

Examples

Deploy notification to engineering channel:

WEBHOOK=$(jq -r '.webhooks.acs_engineering_network' google-chat-config.json)
python3 scripts/send_webhook.py "$WEBHOOK" "🚀 Production deploy v2.1.0 completed"

Alert specific user about task:

python3 scripts/send_oauth.py \
  --credentials google-chat-oauth-credentials.json \
  --token google-chat-token.json \
  --dm [email protected] \
  "Your report is ready for review: https://docs.company.com/report"

Thread multiple messages together (webhook):

WEBHOOK=$(jq -r '.webhooks.general' google-chat-config.json)
THREAD_KEY="deploy-$(date +%s)"

python3 scripts/send_webhook.py "$WEBHOOK" "Starting deploy..." --thread_key "$THREAD_KEY"
# ... deployment happens ...
python3 scripts/send_webhook.py "$WEBHOOK" "Deploy completed ✅" --thread_key "$THREAD_KEY"