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 juan@empresa.com \
  "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"