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: ```bash python3 scripts/send_webhook.py "$WEBHOOK_URL" "Your message here" ``` Example with threading: ```bash python3 scripts/send_webhook.py "$WEBHOOK_URL" "Reply message" --thread_key "unique-thread-id" ``` **Configuration:** Store webhooks in `google-chat-config.json`: ```json { "webhooks": { "acs_engineering_network": "https://chat.googleapis.com/v1/spaces/...", "general": "https://chat.googleapis.com/v1/spaces/..." } } ``` Read config and send: ```bash 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): ```bash 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:** ```bash 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: ```bash 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:** ```bash 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):** ```bash # 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):** ```bash 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: ```bash 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](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: ```json { "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:** ```python 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:** ```bash 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:** ```bash 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):** ```bash 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" ```