Google Chat Messaging

Send messages to Google Chat using two methods:

Webhooks - Fast, pre-configured channels (messages appear as a bot)

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": "",
    "general": ""
  }
}

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:

Save OAuth credentials to a file (e.g., google-chat-oauth-credentials.json)

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:

• - Send messages - - Access space information


• - 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: __CODE_BLOCK_11__ ## 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: "

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"