📱 Google Messages Extension for SillyTavern

A client-side extension that enables SMS functionality in SillyTavern through Google Messages integration. Works together with the Google Messages server plugin.

🎯 What This Extension Does

This extension provides the user interface and LLM integration for Google Messages:

• ✅ Slash commands for manual SMS control
• ✅ Function tools so LLMs can send/read messages
• ✅ Background polling for automatic message sync
• ✅ System messages display SMS in chat
• ✅ Prompt injection makes LLM aware of new messages
• ✅ Character mapping links contacts to characters
• ✅ Settings panel for easy configuration

🏗️ Architecture

Extension (browser) ← YOU ARE HERE
         ↓
    Plugin (server)
         ↓
  FastAPI Server
         ↓
  Google Messages

📦 Installation

Prerequisites

1. ✅ Server Plugin installed (SillyTavern-GoogleMessages)
2. ✅ FastAPI Server running (server.py)
3. ✅ SillyTavern installed

Installation Steps

1. Copy Extension to SillyTavern

# Copy to third-party extensions directory
cp -r Extension-GoogleMessages /path/to/SillyTavern/public/scripts/extensions/third-party/google-messages

# OR if you're in SillyTavern directory:
cd public/scripts/extensions/third-party
git clone <your-repo> google-messages

2. Restart SillyTavern

Reload the page or restart the server.

3. Enable Extension

1. Click the Extensions button (puzzle piece icon)
2. Find "📱 Google Messages" in the list
3. Toggle it ON

4. Configure Settings

1. Go to Extensions → Google Messages
2. Enable the extension
3. Configure your preferences

⚙️ Settings

Basic Settings

Setting	Description	Default
Enable integration	Master on/off switch	Off
Auto-fetch interval	How often to check for new messages	60 seconds
Show SMS in chat	Display messages as system messages	On
Notification sound	Play audio alert for new messages	On
Unread badge	Show unread count in header	On
Prompt injection	Inject SMS info into LLM prompts	On
Only mapped contacts	Filter to only mapped characters	Off

Character Mappings

Map conversation IDs to character names for better integration:

Conversation ID        → Character Name
Cgg2CrOaHA5ZAxIEMTA1NA → Mom
AnotherConversationID  → Best Friend

Benefits:

• Use character names in slash commands
• Filter messages by current character
• Better context for the LLM

💬 Slash Commands

Send SMS

/send-sms to="Mom" Hey, I'll be home late!

Send an SMS message to someone.

Arguments:

• to (required) - Recipient name or conversation ID
• Message content (required) - The text to send

Check for Messages

/check-sms

Manually check for new SMS messages immediately.

List Conversations

/list-conversations

Show all active SMS conversations with preview text.

Read Conversation

/read-conversation name="Mom" limit=20

Display recent message history from a conversation.

Arguments:

• name or id (required) - Recipient name or ID
• limit (optional) - Number of messages (default: 10)

Map Contact to Character

/map-sms id="Cgg2CrOaHA5ZAxIEMTA1NA" char="Mom"

Create a mapping between a conversation ID and a character name.

Arguments:

• id (required) - Conversation short ID
• char (required) - Character name

🤖 Function Tools (LLM Integration)

When enabled, LLMs can use these tools automatically:

sendSMS

{
  "name": "sendSMS",
  "description": "Send an SMS text message",
  "parameters": {
    "recipient": "Mom",
    "message": "I'll be home by 6pm"
  }
}

When LLM uses it:

User: "Text my mom that I'll be home by 6"

AI: calls sendSMS tool

AI: "I've sent a text to your mom letting her know you'll be home by 6pm!"

checkSMS

{
  "name": "checkSMS",
  "description": "Check for unread SMS messages"
}

When LLM uses it:

User: "Did anyone text me?"

AI: calls checkSMS tool

AI: "You have 2 unread messages from Mom and 1 from Work."

readSMSConversation

{
  "name": "readSMSConversation",
  "description": "Read recent message history",
  "parameters": {
    "recipient": "Mom",
    "limit": 10
  }
}

When LLM uses it:

User: "What did my mom say earlier?"

AI: calls readSMSConversation tool

AI: "Your mom asked if you were coming to dinner tonight. She mentioned that..."

📡 Background Polling

The extension automatically checks for new messages every X seconds (configurable).

When a new message arrives:

1. 📨 Message appears in chat as system message
2. 🔔 Toast notification pops up
3. 🔊 Sound plays (if enabled)
4. 🔴 Badge updates with unread count
5. 🤖 LLM is informed via prompt injection

Example in chat:

📱 SMS from Mom:
"Are you coming to dinner tonight?"
5m ago

💉 Prompt Injection

Before the LLM generates a response, the extension automatically injects unread SMS information:

📱 **SMS Notifications:**
- 2 unread message(s) from Mom
  Latest: "Are you coming to dinner tonight?"
- 1 unread message(s) from Work
  Latest: "Can you review the report by EOD?"

Effect: The LLM naturally becomes aware of messages and can react:

AI: "Oh, I see you got a text from your mom about dinner. Would you like me to help you respond?"

🎨 Features in Detail

System Messages

SMS messages appear as styled system messages in your chat:

┌────────────────────────────────────────┐
│ 📱 SMS from Mom:                       │
│ "Are you coming to dinner tonight?"    │
│ 5m ago                                 │
└────────────────────────────────────────┘

Unread Badge

A floating badge in the top-right shows unread count:

┌─────┐
│ 5   │  ← Unread messages
└─────┘

Click to view (future feature).

Character Mapping

When you map conversations to characters:

Before:

• "Send SMS to Cgg2CrOaHA5ZAxIEMTA1NA"

After:

• "Send SMS to Mom" ✨

Smart Resolution

The extension automatically resolves recipients:

"Mom"                      → Looks up in mappings
"John Doe"                 → Looks up in conversation names
"Cgg2CrOaHA5ZAxIEMTA1NA"  → Uses directly as ID

🔧 Troubleshooting

Extension not loading

Problem: Extension doesn't appear in the list

Solutions:

• Check extension is in correct directory
• Refresh browser (Ctrl+F5)
• Check browser console for errors

Plugin not available

Problem: "Plugin not available" error on load

Solutions:

• Ensure server plugin is installed
• Check SillyTavern has enableServerPlugins: true
• Restart SillyTavern server
• Check plugin loads in server logs

No messages appearing

Problem: Messages not showing up in chat

Solutions:

• Enable extension in settings
• Check "Show SMS in chat" is enabled
• Verify FastAPI server is running
• Check browser console for errors
• Use /check-sms to manually refresh

Function tools not working

Problem: LLM can't use SMS tools

Solutions:

• Check your LLM API supports function calling
• Supported: OpenAI, Claude, Cohere, Groq, etc.
• Not supported: Some local models
• Check function tools are enabled in SillyTavern

Slash commands not found

Problem: Commands don't autocomplete

Solutions:

• Extension must be enabled
• Refresh page after enabling
• Type / to see all commands
• Check console for registration errors

📋 Usage Examples

Example 1: User asks LLM to send message

User: Can you text my mom that I'll be late?

AI: [uses sendSMS tool]
AI: I've sent a text to your mom letting her know you'll be late.

[System message appears in chat]
📱 SMS to Mom:
"I'll be late, see you soon!"

Example 2: New message arrives

[Background poll detects new message]

[Toast notification appears]
📱 SMS Received
New message from Mom

[System message in chat]
📱 SMS from Mom:
"Okay, drive safe!"
5s ago

[On next AI generation]
AI: I see your mom replied. She said to drive safe!

Example 3: User asks about messages

User: Did anyone text me?

AI: [uses checkSMS tool]
AI: Yes! You have 2 unread messages - one from your mom 
    about dinner, and one from work about the report.
    Would you like me to read them for you?

User: Yes please

AI: [uses readSMSConversation tool for each]
AI: Your mom asked: "Are you coming to dinner tonight?"
    And your work said: "Can you review the report by EOD?"

🎯 Best Practices

1. Map Your Contacts

Create mappings for frequently texted contacts:

/map-sms id="Cgg..." char="Mom"
/map-sms id="Aaa..." char="Best Friend"

2. Set Reasonable Polling Interval

• Fast (30s): For active conversations
• Normal (60s): General use
• Slow (120s+): Background monitoring

3. Use Prompt Injection

Keep it enabled! The LLM works much better when it knows about new messages naturally.

4. Filter by Mapped Contacts

If you have lots of conversations, enable "Only show mapped contacts" to reduce noise.

🚀 Advanced Usage

Custom Automation

Combine with other SillyTavern features:

// In custom STscript
{{run: /check-sms}}
{{if: {{getvar::google_messages_unread}} > 0}}
    You have unread messages!
{{/if}}

Integration with Characters

Set character-specific instructions:

System: When the user receives an SMS, help them craft 
an appropriate response based on your character.

🤝 Contributing

See the main project README for contribution guidelines.

📝 Version History

• 1.0.0 - Initial release
  • Slash commands
  • Function tools
  • Background polling
  • Prompt injection
  • Character mapping
  • Settings UI

📄 License

MIT License - See LICENSE file

---

Happy messaging! 📱✨

Part of the Google Messages integration suite