openclaw/extensions/googlechat/CHANGES-SUMMARY.md

Google Chat Proactive Messaging - Implementation Summary

This document summarizes the changes made to enable proactive messaging in the Google Chat extension.

Files Modified

1. src/config/types.googlechat.ts

Added:

• GoogleChatKnownSpace type - Structure for cached space entries
• GoogleChatKnownSpaces type - Map of user IDs to space info
• knownSpaces field to GoogleChatAccountConfig - Stores cached space mappings

2. src/config/zod-schema.providers-core.ts

Added:

• GoogleChatKnownSpaceSchema - Zod validation schema for space cache entries
• knownSpaces field to GoogleChatAccountSchema - Config validation

3. extensions/googlechat/src/space-cache.ts (NEW)

Created:

• getKnownSpaces() - Retrieve cached spaces for an account
• getCachedSpaceForUser() - Look up space by user ID
• hasCachedSpace() - Check if space is cached
• buildSpaceCachePatch() - Create config patch for new cache entries
• extractSpaceInfoFromEvent() - Extract space info from incoming messages

4. extensions/googlechat/src/targets.ts

Modified:

• Updated resolveGoogleChatOutboundSpace() to accept config and options
• Added cache lookup before calling findDirectMessage API
• Added ResolveSpaceOptions type for useCache and useFindDirectMessage flags
• Improved error messages with actionable guidance

5. extensions/googlechat/src/monitor.ts

Modified:

• Added import for space-cache utilities
• Added space caching logic in processMessageWithPipeline()
• Spaces are now cached automatically when users message the bot

6. extensions/googlechat/src/channel.ts

Modified:

• Updated sendText to pass config to resolveGoogleChatOutboundSpace()
• Updated sendMedia to pass config to resolveGoogleChatOutboundSpace()
• Updated notifyApproval to pass config to resolveGoogleChatOutboundSpace()

7. extensions/googlechat/PROACTIVE-MESSAGING.md (NEW)

Created:

• Comprehensive documentation for proactive messaging
• Usage examples for all 4 methods
• Troubleshooting guide
• Best practices

How It Works

1. Incoming Message → monitor.ts extracts space info and caches it
2. Outgoing Message → channel.ts calls resolveGoogleChatOutboundSpace()
3. Resolution → targets.ts checks cache first, then API fallback
4. Delivery → Message sent via api.ts

Usage Examples

CLI

# Using user ID (auto-resolves to cached space)
moltbot message send --channel googlechat --to "users/123" --text "Hello!"

# Using space ID (direct)
moltbot message send --channel googlechat --to "spaces/AAA" --text "Hello!"

Config (Cron)

{
  "cron": {
    "jobs": [{
      "schedule": "0 9 * * *",
      "text": "Morning!",
      "target": "users/123",
      "channel": "googlechat"
    }]
  }
}

Config Structure

{
  "channels": {
    "googlechat": {
      "knownSpaces": {
        "users/123456": {
          "spaceId": "spaces/AAAAxxxx",
          "displayName": "John Doe",
          "type": "DM",
          "lastSeenAt": 1706515200000
        }
      }
    }
  }
}

Benefits

1. Automatic Caching - No manual space ID management needed
2. Multiple Fallbacks - Cache → API → Error with guidance
3. Backward Compatible - Existing space ID targeting still works
4. Well Documented - Clear patterns for developers

Testing Recommendations

1. Test incoming messages cache the space
2. Test proactive send using cached user ID
3. Test proactive send using space ID directly
4. Test error case when user hasn't messaged first
5. Test with multiple accounts