Virtnet.bond/extensions/Others/SocialBase/docs/MESSAGING_SYSTEM.md

# SocialBase Messaging System

The SocialBase extension includes a comprehensive messaging system that allows:
- User-to-user direct messaging
- System messages from extensions
- Admin moderation tools
- Message flagging and review

## For Extension Developers

### Sending System Messages

Other extensions can easily send system messages to users using the `MessagingHelper` class.

```php
use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

// Send a system message to a single user
MessagingHelper::sendSystemMessage(
    userId: 1,
    content: 'Your order #12345 has been completed',
    systemType: 'order_update',
    metadata: ['order_id' => 12345]
);

// Send a system message to multiple users
MessagingHelper::sendSystemMessageToUsers(
    userIds: [1, 2, 3],
    content: 'System maintenance scheduled for tomorrow',
    systemType: 'system_announcement'
);

// Send a direct message from one user to another
MessagingHelper::sendDirectMessage(
    senderId: 1,
    recipientId: 2,
    content: 'Hello! I have a question about my order.',
    metadata: []
);

// Check if messaging system is available
if (MessagingHelper::isAvailable()) {
    // Send messages
}

// Get unread message count for a user
$unreadCount = MessagingHelper::getUnreadCount($userId);
```

### System Message Types

When sending system messages, use appropriate `systemType` values to categorize them:

- `general` - General system notifications
- `order_update` - Order status changes
- `payment_received` - Payment confirmations
- `account_notification` - Account-related notifications
- `ticket_update` - Support ticket updates
- `service_activation` - Service activation notifications
- `invoice_generated` - New invoice notifications
- Custom types specific to your extension

### Listening for Message Events

You can listen for messaging events in your extension:

```php
use Illuminate\Support\Facades\Event;

Event::listen('socialbase.message.sent', function ($message) {
    // Handle when a user message is sent
});

Event::listen('socialbase.system_message.sent', function ($message, $userId) {
    // Handle when a system message is sent
});

Event::listen('socialbase.message.flagged', function ($message, $flaggedBy) {
    // Handle when a message is flagged for moderation
});

Event::listen('socialbase.message.approved', function ($message, $moderatorId) {
    // Handle when a message is approved by a moderator
});

Event::listen('socialbase.message.deleted', function ($message, $moderatorId) {
    // Handle when a message is deleted by a moderator
});
```

### Using the MessagingService Directly

For advanced use cases, you can use the `MessagingService` class directly:

```php
use Paymenter\Extensions\Others\SocialBase\Services\MessagingService;

$service = new MessagingService();

// Send a direct message
$message = $service->sendDirectMessage($senderId, $recipientId, $content);

// Send a message to an existing conversation
$message = $service->sendMessage($conversationId, $senderId, $content);

// Send system message
$message = $service->sendSystemMessage($userId, $content, 'order_update', ['order_id' => 123]);

// Get user's conversations
$conversations = $service->getUserConversations($userId, $includeArchived = false);

// Get unread count
$unreadCount = $service->getUnreadCount($userId);

// Moderation actions
$service->flagMessage($messageId, $flaggedBy, $reason);
$service->approveMessage($messageId, $moderatorId);
$service->deleteMessage($messageId, $moderatorId, $reason);
```

## For Users

### Accessing Messages

- Navigate to the Messages page from the main navigation menu
- Unread message counts are displayed in the navigation
- Click on any conversation to view and reply to messages

### Sending Messages

1. Visit a user's profile
2. Click the "Send Message" button
3. Type your message and click Send

### Message Notifications

- Unread messages are highlighted in the conversation list
- System messages appear with a special icon
- Message counts update in real-time

## For Administrators

### Message Moderation

Access the Message Moderation panel from the admin dashboard:

1. Navigate to **Message Moderation** in the admin sidebar
2. View all flagged messages
3. Filter by moderation status, system messages, etc.

### Moderation Actions

- **Approve**: Mark a message as reviewed and appropriate
- **Flag**: Mark a message for review (with reason)
- **Delete**: Remove a message (with reason for deletion)

### Bulk Actions

Select multiple messages to:
- Approve multiple messages at once
- Delete multiple messages

### Viewing Message Details

Click "View" on any message to see:
- Full message content
- Sender information
- Conversation context
- Metadata (for system messages)
- Moderation history

## Database Schema

### Tables

- `ext_social_conversations` - Conversation threads
- `ext_social_conversation_participants` - Users in conversations
- `ext_social_messages` - Individual messages
- `ext_social_message_reads` - Read receipts

### Conversation Types

- `direct` - One-on-one user conversations
- `group` - Group conversations (future feature)
- `system` - System message conversations

## Example Use Cases

### Order Update Notification

```php
// In your order processing extension
use Paymenter\Extensions\Others\SocialBase\Helpers\MessagingHelper;

public function notifyOrderComplete($order)
{
    MessagingHelper::sendSystemMessage(
        userId: $order->user_id,
        content: "Your order #{$order->id} has been completed successfully!",
        systemType: 'order_update',
        metadata: [
            'order_id' => $order->id,
            'status' => 'completed',
        ]
    );
}
```

### Payment Confirmation

```php
public function notifyPaymentReceived($invoice)
{
    MessagingHelper::sendSystemMessage(
        userId: $invoice->user_id,
        content: "Payment of {$invoice->total} received for invoice #{$invoice->id}",
        systemType: 'payment_received',
        metadata: [
            'invoice_id' => $invoice->id,
            'amount' => $invoice->total,
        ]
    );
}
```

### Broadcast System Announcement

```php
public function sendMaintenanceNotification()
{
    $allUserIds = User::pluck('id')->toArray();
    
    MessagingHelper::sendSystemMessageToUsers(
        userIds: $allUserIds,
        content: 'Scheduled maintenance will occur tomorrow at 2 AM UTC for approximately 2 hours.',
        systemType: 'system_announcement'
    );
}
```

## API Reference

### MessagingHelper

| Method | Parameters | Returns | Description |
|--------|------------|---------|-------------|
| `sendSystemMessage` | `$userId`, `$content`, `$systemType`, `$metadata` | `Message` | Send system message to one user |
| `sendSystemMessageToUsers` | `$userIds`, `$content`, `$systemType`, `$metadata` | `Message[]` | Send system message to multiple users |
| `sendDirectMessage` | `$senderId`, `$recipientId`, `$content`, `$metadata` | `Message` | Send direct message between users |
| `getUnreadCount` | `$userId` | `int` | Get unread message count |
| `isAvailable` | - | `bool` | Check if messaging system is enabled |

### MessagingService

See "Using the MessagingService Directly" section above for full API reference.

## Configuration

The messaging system works out of the box with no additional configuration required. Messages are stored in the database and managed through Livewire components.

## Security

- Users can only send messages to other users
- Users can only read their own conversations
- Admins can moderate all messages
- System messages can only be sent by extensions (not directly by users)
- Message content is sanitized to prevent XSS attacks

## Performance Considerations

- Conversations are paginated
- Messages load on-demand
- Indexes on key columns ensure fast queries
- Soft deletes allow message recovery

## Future Features

- Group conversations
- File attachments
- Voice messages
- Read receipts UI
- Typing indicators
- Push notifications
- Email notifications for messages