Documentation Menu
Back to Channels

Google Chat Setup

Workspace integration with slash commands

Overview

The Google Chat integration enables SingularCore to receive commands and send notifications through Google Workspace. It supports slash commands for team collaboration and automated notifications with customizable alert tiers.

Difficulty

Intermediate

Setup Time

15-20 minutes

Notification Tiers

Normal, High, Urgent

Prerequisites

Google Workspace Requirements

  • Google Workspace account with admin access
  • Google Cloud project with billing enabled
  • Google Chat API enabled
  • Pub/Sub API enabled (for async messaging)
  • OAuth consent screen configured

Step-by-Step Setup

1

Create Google Cloud Project

  1. Go to Google Cloud Console
  2. Click Select a project then New Project
  3. Enter project name (e.g., "singularcore-chat-integration")
  4. Click Create
  5. Enable billing for the project
  6. Navigate to APIs & Services > Library
  7. Search for and enable Google Chat API
  8. Also enable Pub/Sub API
2

Configure OAuth Consent Screen

  1. Go to APIs & Services > OAuth consent screen
  2. Select Internal (for Workspace) or External
  3. Fill in app information:
    • App name: "SingularCore Chat"
    • User support email: your email
    • Developer contact: your email
  4. Add scopes: chat.bot
  5. Save and continue
3

Create Service Account

  1. Go to IAM & Admin > Service Accounts
  2. Click Create Service Account
  3. Name: "singularcore-chat"
  4. Grant roles:
    • Chat Bot Viewer
    • Pub/Sub Publisher
  5. Create key: Keys > Add Key > Create new key
  6. Choose JSON format and download
  7. Save the JSON file securely
4

Configure Chat App

  1. Go to Google Chat API > Configuration
  2. Fill in app details:
    • App name: "SingularCore"
    • Avatar URL: Your logo URL
    • Description: "AI-powered system monitoring and control"
  3. Under Functionality, select:
    • Receive 1:1 messages
    • Join spaces and group conversations
  4. Connection settings: HTTP endpoint
  5. Enter your webhook URL (e.g., https://your-domain.com/api/chat/google)
  6. Authentication: Use service account
  7. Save configuration
5

Create Slash Commands

In the Chat API Configuration, add these commands:

Command: /status
Name: System Status
Description: Get system health and status

Command: /skills
Name: List Skills
Description: Show available skills

Command: /dream
Name: Dream Summary
Description: View last dream summary

Command: /approve
Name: Approve Action
Description: Approve a pending action (requires ID)
Parameter: id - Action ID to approve

Command: /reject
Name: Reject Action
Description: Reject a pending action (requires ID)
Parameter: id - Action ID to reject

Command: /stop
Name: Pause Heartbeat
Description: Pause system heartbeat monitoring

Command: /resume
Name: Resume Heartbeat
Description: Resume system heartbeat monitoring
6

Configure SingularCore

Edit config/comms.json:

{
  "google_chat": {
    "enabled": true,
    "project_id": "your-project-id",
    "service_account_file": "/path/to/service-account-key.json",
    "webhook_secret": "your-webhook-secret",
    "allowed_spaces": ["space-id-1", "space-id-2"],
    "notification_tiers": {
      "normal": ["space-id-1"],
      "high": ["space-id-1"],
      "urgent": ["space-id-1", "admin-space-id"]
    }
  }
}

Set environment variable for service account:

export GOOGLE_APPLICATION_CREDENTIALS="/path/to/service-account-key.json"

Supported Commands

CommandDescriptionTier
/statusSystem health check0
/skillsList available skills0
/dreamView last dream summary0
/approve <id>Approve pending action1+
/reject <id>Reject pending action1+
/stopPause heartbeat monitoring1+
/resumeResume heartbeat monitoring1+

Troubleshooting

App Not Responding

  • Verify webhook URL is accessible from internet
  • Check HTTP POST requests are being received
  • Validate service account has proper permissions
  • Review Cloud Console logs for errors

Authentication Errors

  • Verify GOOGLE_APPLICATION_CREDENTIALS path is correct
  • Check service account JSON file is valid
  • Ensure Chat API is enabled in Cloud Console
  • Verify OAuth consent screen is configured

Slash Commands Not Working

  • Re-publish the app after adding commands
  • Check command names match exactly (case-sensitive)
  • Verify bot is added to the space
  • Check allowed_spaces includes space ID

Messages Not Sending

  • Verify Pub/Sub API is enabled
  • Check notification_tiers configuration
  • Ensure service account has Pub/Sub Publisher role
  • Review space IDs are correct

Need More Details?

View the complete Google Chat integration guide with advanced configuration, webhook security, and best practices for Workspace deployments.

Google Chat API Documentation