Google Chat Messaging

---

name: google-chat

description: Send messages to Google Chat spaces and users via webhooks or OAuth. Use when you need to send notifications, alerts, or messages to Google Chat channels (spaces) or direct messages to specific users. Supports both incoming webhooks (for predefined channels) and OAuth 2.0 (for dynamic messaging to any space or user).

---

# 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:**

OAuth Setup Guide

If OAuth credentials don't exist yet:

1. Go to [Google Cloud Console](https://console.cloud.google.com)

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:**

**Use OAuth when:**

**OAuth Limitations:**

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:**

**OAuth errors:**

**Permission errors:**

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"