> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mixus.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# SMS & WhatsApp Automation Agents

> Intelligent SMS and WhatsApp messaging with AI-powered responses and text-to-chat integration

**Status**: 🧪 **Beta Testing** - Core messaging available with ongoing improvements

Chat with your mixus AI assistant through SMS and WhatsApp for on-the-go conversations and instant responses. The SMS/WhatsApp system provides intelligent 1:1 messaging with AI capabilities.

## How It Works

### SMS & WhatsApp-to-Chat Integration

mixus automatically converts SMS and WhatsApp messages into internal chat sessions while maintaining user context and conversation flow:

```mermaid theme={null}
📱 SMS/WhatsApp Agent Workflow:

📬 Inbound Processing:
├── 📨 Message received via messaging service webhook
├── 🔍 Intent-based conversation threading
├── 👥 User resolution and organization mapping
├── 🧵 Thread detection or new conversation creation
├── 💬 Convert to internal chat session
└── 🤖 AI response generation

📤 Outbound Processing:
├── 🎯 Generate contextual AI response
├── 📱 Platform-aware content formatting
├── ✂️ Smart truncation for message limits
├── 🔗 Continue links for complex responses
└── 📨 Message delivery
```

### Always-On AI Response

The SMS/WhatsApp system is designed for direct 1:1 conversations with consistent AI responses:

```json Messaging Capabilities theme={null}
{
  "messaging_intelligence": {
    "response_behavior": {
      "always_responds": "every_message_triggers_ai_response",
      "direct_1v1": "no_group_chat_scenarios_to_handle",
      "consistent_ux": "no_missed_messages_due_to_addressing_detection",
      "context_preservation": "maintains_conversation_context_across_messages"
    },
    "platform_optimization": {
      "sms_formatting": "conservative_length_limits_with_smart_truncation",
      "whatsapp_formatting": "longer_content_with_rich_formatting_support",
      "continue_links": "provides_web_continuation_for_complex_responses",
      "intelligent_summarization": "ai_powered_content_summarization"
    },
    "threading_system": {
      "intent_based": "ai_powered_conversation_threading",
      "context_aware": "smart_context_preservation_across_messages",
      "user_focused": "simplified_logic_for_reliable_threading"
    }
  }
}
```

## Getting Started

### Setup Your SMS/WhatsApp Agent

1. **Send a Message**
   Simply text your assigned phone number:

   ```text theme={null}
   SMS: Your assigned mixus phone number
   WhatsApp: Your assigned mixus WhatsApp number
   ```

2. **Organization & Space Selection**
   For multi-organization users, the system automatically:

   * Resolves your organization based on phone number
   * Creates or finds appropriate workspace
   * Handles guest users for unknown numbers

3. **Start Conversing**
   Your message becomes a full chat conversation with AI capabilities:
   * Ask questions and get intelligent responses
   * Request tasks and basic workflows
   * Access core mixus features and integrations
   * Continue complex conversations on web with provided links

### Platform-Specific Features

#### SMS Optimization

* **Platform Limits**: 1600 character messaging service limit with intelligent processing
* **Multi-Part Messages**: Smart splitting into logical parts ("Part 1/2", "Part 2/2")
* **AI Content Cleaning**: Removes conversational artifacts and focuses on essential information
* **Continue Links**: Web continuation for complex responses
* **Link-Based Attachments**: All files shared via secure web viewer links

#### WhatsApp Enhancement

* **Enhanced Content Processing**: 1600 character limit with intelligent condensation or splitting
* **Direct Media Messages**: Send PDFs, images, and documents directly (≤5MB)
* **Rich Formatting**: Supports enhanced text formatting and emojis
* **Attachment Fallback**: Large files automatically use web viewer links
* **Sequential Delivery**: Proper message ordering with timing delays

#### Intelligent Content Management

* **AI-Powered Cleaning**: Removes meta-conversational phrases and thinking artifacts
* **Smart Strategies**: Single message → condensation → multi-part splitting
* **Priority-Based Content**: Conclusions → actions → key findings → details
* **Platform Awareness**: Automatically optimizes based on SMS vs WhatsApp
* **Graceful Fallbacks**: Reliable processing with comprehensive error handling

## Advanced Features

### Intent-Based Threading

Advanced conversation threading powered by AI:

```mermaid theme={null}
🧠 AI-Powered Threading:

🎯 Thread Decision Logic:
├── 📝 Analyze message content and context
├── 🔗 Determine relationship to previous messages
├── 📊 Evaluate conversation continuity
├── 🆕 Create new thread or continue existing
└── 🧵 Maintain context preservation

✅ Benefits:
├── 🎯 Reliable threading decisions
├── 📱 Better context management
├── 🔄 Consistent user experience
└── 🚫 No missed messages due to false detection
```

### Organization Management

Sophisticated handling of multi-organization scenarios:

* **Automatic Resolution**: Resolves organization from phone number
* **Guest User Creation**: Creates temporary users for unknown senders
* **Default Organization**: Uses playground organization for guest users
* **Multi-Org Support**: Handles users across multiple organizations

### Opt-Out/Opt-In Management

Comprehensive subscription management:

```json Subscription Features theme={null}
{
  "subscription_management": {
    "opt_out_keywords": ["STOP", "UNSUBSCRIBE", "CANCEL", "END", "QUIT"],
    "opt_in_keywords": ["START", "UNSTOP", "SUBSCRIBE"],
    "features": {
      "automatic_detection": "recognizes_opt_out_opt_in_keywords",
      "confirmation_messages": "sends_confirmation_of_subscription_changes",
      "per_channel_settings": "separate_preferences_for_sms_and_whatsapp",
      "compliance": "follows_telecommunications_compliance_standards"
    }
  }
}
```

### Smart Content Formatting

#### Platform-Aware Processing

```typescript theme={null}
// Messaging Service Limits (Both SMS & WhatsApp)
const MESSAGING_LIMITS = {
  maxContent: 1600, // Messaging service API limit
  safeBuffer: 1400, // Safety buffer for links and formatting
  multiPartThreshold: 2800 // When to consider splitting vs condensation
}

// Processing Strategies
const CONTENT_STRATEGIES = {
  single: '≤1400 chars → Direct delivery',
  condensed: '1400-2800 chars → AI summarization',
  split: '>2800 chars → Multi-part messages with logical breaks'
}
```

#### AI-Powered Summarization

The system intelligently summarizes content preserving:

1. **Final conclusions and results**
2. **Next steps and action items**
3. **Key findings and discoveries**
4. **Supporting details** (when space allows)

### Advanced Attachment Handling

#### WhatsApp Media Messages

WhatsApp users benefit from direct file sharing capabilities:

* **Direct Media Delivery**: PDFs, images, and documents sent directly to WhatsApp (≤5MB)
* **Automatic Fallback**: Large files automatically use secure web viewer links
* **Multi-Format Support**: Handles various document types and image formats
* **Sequential Delivery**: Attachments delivered with proper timing and order

#### SMS File Sharing

SMS users receive secure, accessible file links:

* **Web Viewer Links**: All attachments accessible via secure web interface
* **Universal Compatibility**: Works across all SMS-capable devices
* **Document Summaries**: Key information included in message text
* **Continue Links**: Full document access via web continuation

```mermaid theme={null}
📎 Attachment Handling Flow:

📱 WhatsApp Strategy:
├── 📄 Generate PDF/document version
├── 📏 Check file size (≤5MB limit)
├── ✅ Direct media message if compatible
└── 🔗 Web viewer link if too large

📟 SMS Strategy:
├── 📄 Process document for web viewing
├── 🔗 Generate secure viewer link
├── 📝 Include document summary in message
└── 🌐 Provide web continuation option
```

## Technical Architecture

### SMS/WhatsApp Bridge System

```mermaid theme={null}
📱 SMS/WhatsApp Processing Pipeline:

🔄 Inbound Pipeline:
├── 📨 Twilio webhook reception
├── 🔍 SmsChatBridge processing
├── 🏢 UnifiedOrganizationResolver
├── 🧵 Intent-based threading analysis
├── 💬 Chat creation or continuation
└── 🤖 AI response generation

📤 Outbound Pipeline:
├── 🎯 Response generation and formatting
├── 📱 Platform-specific optimization
├── ✂️ Smart content truncation
├── 🔗 Continue link generation
└── 📨 Twilio delivery
```

### Key Components

* **SmsChatBridge**: Main orchestration class for SMS/WhatsApp processing
* **Intent Classifier**: AI-powered message analysis and threading
* **Organization Resolver**: Handles multi-organization scenarios
* **Content Formatter**: Platform-aware message formatting
* **Loop Prevention**: Anti-spam and duplicate message detection

## Use Cases

### Customer Support

* **Instant Responses**: Immediate AI-powered customer service
* **Mobile Accessibility**: Support customers on their preferred mobile platform
* **Context Retention**: Maintain conversation history across interactions
* **Escalation Pathways**: Seamless handoff to human agents when needed

### Team Communication

* **Quick Queries**: Fast answers to urgent questions while mobile
* **Status Updates**: Get project updates and notifications via text
* **Task Management**: Create and manage tasks through messaging
* **Document Access**: Request and receive document summaries

### Personal Productivity

* **Mobile AI Assistant**: Full AI capabilities accessible via text
* **Information Retrieval**: Quick access to organizational knowledge
* **Workflow Triggers**: Initiate complex workflows from simple messages
* **Cross-Platform Continuity**: Start on mobile, continue on web

## Integration Points

### Twilio Platform Integration

* **SMS**: Complete SMS messaging support via Twilio
* **WhatsApp Business**: WhatsApp messaging through Twilio WhatsApp API
* **Media Support**: Handle images, documents, and file attachments
* **Delivery Status**: Track message delivery and read receipts

### mixus Platform Integration

* **Chat System**: Seamless conversion to internal chat conversations
* **Agents**: Full access to all mixus AI agents and capabilities
* **Tools**: Complete integration with mixus tools and workflows
* **Files & Memory**: Access to organizational knowledge and files
* **Web Continuation**: Smooth transition from mobile to web interface

## Configuration & Setup

### Environment Setup

Required environment variables for SMS/WhatsApp functionality:

```bash theme={null}
# Twilio Configuration
TWILIO_ACCOUNT_SID=your_account_sid
TWILIO_AUTH_TOKEN=your_auth_token
TWILIO_MESSAGING_SERVICE_SID=your_messaging_service_sid

# SMS/WhatsApp Settings
SMS_ENABLE_LINK_SHORTENING=true
SMS_SMART_CONTENT_STRATEGY=true
SMS_INTENT_THREADING=true
```

### Webhook Configuration

Set up Twilio webhook to process inbound messages:

```text theme={null}
Webhook URL: https://yourdomain.com/api/twilio/webhook
Events: Incoming Messages
Method: POST
```

### Phone Number Setup

Configure your Twilio phone numbers:

* **SMS Number**: Dedicated number for SMS messaging
* **WhatsApp Number**: WhatsApp-enabled number or sandbox
* **Messaging Service**: Unified service managing both channels

## Monitoring & Analytics

### Message Processing Metrics

Track SMS/WhatsApp agent performance:

* **Processing Times**: Monitor message-to-response latency
* **Threading Accuracy**: Measure conversation threading success
* **Content Optimization**: Track truncation and summarization effectiveness
* **User Engagement**: Analyze response patterns and continuation rates
* **Platform Usage**: SMS vs WhatsApp usage patterns

### Performance Optimization

Built-in optimization features:

* **Smart Continue Strategy**: Reduces unnecessary link generation by 70-80%
* **Platform-Aware Formatting**: Optimizes content for each platform
* **Intelligent Truncation**: Preserves most important information
* **Cost Management**: Minimizes SMS costs through smart segmentation

## Security & Compliance

### Data Protection

* **Encryption**: All messages encrypted in transit and at rest
* **Phone Number Privacy**: Secure handling of phone number data
* **Organization Isolation**: Proper data boundaries between organizations
* **Guest User Management**: Limited access scope for unknown senders

### Compliance Features

* **Opt-Out Compliance**: Automatic handling of STOP keywords
* **Rate Limiting**: Prevents message flooding and abuse
* **Audit Logging**: Comprehensive logging for compliance requirements
* **Telecommunications Compliance**: Follows carrier and regulatory requirements

## Best Practices

### Message Management

1. **Clear Communication**: Use concise, clear language for mobile context
2. **Action-Oriented**: Focus on actionable information and next steps
3. **Platform Awareness**: Understand SMS vs WhatsApp capabilities
4. **Continue Links**: Use web continuation for complex interactions

### Integration Strategy

1. **Phone Number Management**: Properly configure and test phone numbers
2. **User Education**: Train users on SMS/WhatsApp agent capabilities
3. **Monitoring Setup**: Implement performance monitoring
4. **Fallback Procedures**: Maintain backup communication methods

## Current Status & Limitations

### **Beta Testing Notice**

This feature is currently in beta testing with known limitations:

### **Current Limitations**

* **Reliability**: Message delivery and response consistency under improvement
* **Attachment Processing**: Limited file type support and processing capabilities
* **Advanced Features**: Not all integrations and tools are available via messaging
* **Threading**: Conversation threading may occasionally create new threads unexpectedly
* **International Support**: Limited testing with international phone numbers

### **Technical Considerations**

* **Message Length**: Character limits for SMS and WhatsApp messaging
* **Network Dependencies**: Requires reliable messaging service connectivity
* **Carrier Restrictions**: Subject to carrier filtering and delivery policies
* **Rate Limits**: Messaging service rate limiting may affect delivery speed

## Related Features

* [Agent Creation](/agents/creating) - Build custom automation agents
* [Chat System](/chats/basics) - Understand the underlying chat platform
* [Email Agents](/agents/email) - Email automation capabilities
* [Integrations](/integrations/setup) - Connect external services

## Support & Troubleshooting

### Common Issues

1. **Missing Messages**: Check Twilio webhook configuration and delivery
2. **Threading Problems**: Verify intent-based threading is working properly
3. **Opt-Out Issues**: Ensure proper handling of STOP/START keywords
4. **Organization Confusion**: Verify phone number to organization mapping

### Getting Help

For SMS/WhatsApp agent support:

* Check messaging service delivery logs and webhook status
* Verify phone number configuration and service setup
* Contact support with specific message details for troubleshooting
* Review organization and user resolution settings

***

*The SMS/WhatsApp messaging system is actively being improved based on user feedback and testing. Please report any issues to help us enhance the experience.*