Smart GWS Chat Send

Send messages, cards, and attachments to Google Chat spaces and direct messages programmatically.

When to Use This Command

Run this command when you need to:

• Send formatted messages or interactive cards to Google Chat spaces from automation scripts
• Broadcast notifications, alerts, or status updates to team channels programmatically
• Post structured data like build results, deployment status, or monitoring alerts to Chat

Consider alternatives when:

• You want to have an interactive conversation which is better done in the Chat app directly
• You need to manage Chat space membership or settings which requires the full chat command

Quick Start

Configuration

Copy
name: smart-gws-chat-send
type: command
category: google-workspace

Example Invocation

Copy
claude command:run smart-gws-chat-send --space "spaces/AAAA1234" --message "Deployment v2.5.0 complete"

Example Output

Sending message to Google Chat...
  Space: Engineering Alerts (spaces/AAAA1234)
  Type: text message

Message sent successfully.
  Message ID: msg_7x2k9f
  Timestamp: 2026-03-15 14:23:07 UTC
  Thread: new thread

Preview:
  [Bot] Deployment v2.5.0 complete

Core Concepts

Chat Messaging Overview

Aspect	Details
Message Types	Plain text, formatted text with markdown, interactive cards
Targets	Spaces (group), direct messages (1:1), threads (replies)
Cards	Rich UI elements with headers, sections, buttons, and images
Webhooks	Incoming webhook URLs for simple integrations without OAuth
Threading	Reply to existing threads to keep conversations organized

Message Sending Workflow

Compose Message Content
        |
        v
Select Target
  |         |         |
  v         v         v
Space      DM      Thread
  |         |         |
  v         v         v
Format Message
  |              |
  v              v
Plain Text    Card JSON
  |              |
  v              v
Send via API
        |
        v
Confirm Delivery

Configuration

Parameter	Type	Default	Description
space	string	(required)	Chat space ID or name (spaces/AAAA1234)
message	string	(required)	Message text content or path to card JSON file
thread	string	(none)	Thread ID to reply to an existing conversation
format	string	text	Message format: text, card, or markdown
webhook	string	(none)	Webhook URL for sending without OAuth authentication

Best Practices

1. Use threads for related messages - When sending multiple updates about the same topic, reply to the same thread to keep the space organized rather than creating new top-level messages.

2. Format messages for readability - Use markdown formatting for structured messages. Bold headers, code blocks for technical data, and bullet points make messages scannable in busy spaces.

3. Use cards for actionable messages - When the message requires user action like approving a deployment or acknowledging an alert, use interactive cards with buttons instead of plain text.

4. Rate limit your bot messages - Spaces with high-frequency automated messages quickly get muted by users. Batch notifications into periodic digests rather than sending individual alerts.

Common Issues

1. Space not found error - Space IDs change when spaces are recreated. Verify the space ID by checking the Chat space URL or listing spaces with the chat command.

2. Card JSON validation fails - Card payloads must follow the Google Chat card schema exactly. Use the card builder tool to generate valid JSON before sending.

3. Webhook URL expired or rotated - Webhook URLs can be regenerated by space admins, invalidating saved URLs. Store webhook URLs in a configuration file that is easy to update rather than hardcoding them into scripts.

4. Message delivery confirmation not received - The API returns a message ID upon successful send, but delivery to all space members depends on their notification settings and online status. The message is stored server-side regardless of whether individual members have seen it.

5. Bot lacks permission to post in space - Some spaces restrict which apps can post messages. Ensure the Chat bot is added to the space through the space settings and that the bot has been authorized by a space manager.