Google Chat

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).

Security Scan

The skill's code, instructions, and requirements are consistent with its stated purpose of sending messages to Google Chat via webhooks or OAuth.

Purpose & Capability

Name/description match what the files and SKILL.md implement: webhook sends and OAuth-based messaging using the Google Chat API. No unrelated credentials, binaries, or platform services are requested.

Instruction Scope

SKILL.md only instructs running the included Python scripts, storing webhook URLs and OAuth credentials/tokens on disk, and installing Google auth libraries. The OAuth flow opens a browser and the token is persisted to the specified token file — this is expected for OAuth clients and is documented in the README and SKILL.md.

Install Mechanism

There is no automated install spec; the skill is instruction-only and recommends installing well-known Python libraries (google-auth-oauthlib, google-api-python-client). No downloads from untrusted URLs or archive extraction are present.

Credentials

The skill does not request environment variables or unrelated secrets. It requires user-provided OAuth credentials (client_id/client_secret JSON), token file path, or webhook URLs — all are proportional and necessary for the described functionality. These files/URLs are sensitive and should be protected by the user.

Persistence & Privilege

always is false and the skill does not request permanent system presence or modify other skills. It writes only its own token file when you run the OAuth flow, which is normal for OAuth clients.

Assessment

This skill appears to do what it says: send messages to Google Chat via incoming webhooks or OAuth. Before installing or running it: (1) review the two Python scripts yourself — they are short and readable; (2) protect any credential files and token files you create (google-chat-oauth-credentials.json, google-chat-token.json) and your webhook URLs (they contain keys/tokens); (3) be aware the OAuth flow opens a browser and will persist a token file on disk; (4) installing the recommended Python packages (pip) carries typical dependency risk — consider using a virtual environment; (5) because the skill can send messages, only grant it credentials you trust and avoid giving it access to high-privilege service accounts or reuse secrets shared elsewhere.

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 [e-mail] \
  "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"