560d31b0ff
Add space caching and auto-resolution for proactive Google Chat messages:
- Auto-cache space IDs when users message the bot (knownSpaces)
- Auto-resolve users/{id} to cached spaces for outbound messages
- Fallback to findDirectMessage API when not cached
- Add comprehensive documentation for proactive messaging patterns
This enables cron jobs, skills, and agents to send proactive messages
to users who have previously interacted with the bot.
Fixes: Users can now send messages via 'users/{id}' target instead of
needing to know the space ID beforehand.
116 lines
3.6 KiB
Markdown
116 lines
3.6 KiB
Markdown
# 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
|
|
```bash
|
|
# 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)
|
|
```json
|
|
{
|
|
"cron": {
|
|
"jobs": [{
|
|
"schedule": "0 9 * * *",
|
|
"text": "Morning!",
|
|
"target": "users/123",
|
|
"channel": "googlechat"
|
|
}]
|
|
}
|
|
}
|
|
```
|
|
|
|
### Config Structure
|
|
```json
|
|
{
|
|
"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
|