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.

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:

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:

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

// 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

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

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