Clear Unread Messages

Clear the unread message count for a conversation

POST /conversations/clearUnread

Try it

cURL

curl -X POST "http://localhost:5001/conversations/clearUnread" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "message_seq": 1001
  }'

Success Response

{
  "status": "ok"
}

Overview

Clear the unread message count for a specified conversation, resetting the unread count to 0.

Request Body

Required Parameters

uid · string · required

User ID

channel_id · string · required

Channel ID

channel_type · integer · required

Channel type

• 1 - Personal channel
• 2 - Group channel

Optional Parameters

message_seq · integer

Message sequence number, specifies up to which message to clear

cURL

curl -X POST "http://localhost:5001/conversations/clearUnread" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "message_seq": 1001
  }'

Success Response

{
  "status": "ok"
}

Response Fields

status · string · required

Operation status, returns "ok" on success

Status Codes

Status Code	Description
200	Unread messages cleared successfully
400	Request parameter error
403	No operation permission
404	Conversation does not exist
500	Internal server error

Use Cases

Chat Interface Integration

Mark Messages as Read:

// Clear unread when user opens a conversation
async function openConversation(channelId, channelType, userId) {
    try {
        // Clear unread count
        await clearUnreadMessages({
            uid: userId,
            channel_id: channelId,
            channel_type: channelType
        });
        
        // Update UI to remove unread badge
        updateUnreadBadge(channelId, 0);
        
        console.log('Conversation opened and unread cleared');
    } catch (error) {
        console.error('Failed to clear unread messages:', error);
    }
}

Mark Read Up to Specific Message:

// Clear unread up to a specific message when user scrolls
async function markReadUpToMessage(channelId, channelType, userId, messageSeq) {
    try {
        await clearUnreadMessages({
            uid: userId,
            channel_id: channelId,
            channel_type: channelType,
            message_seq: messageSeq
        });
        
        console.log(`Marked read up to message ${messageSeq}`);
    } catch (error) {
        console.error('Failed to mark messages as read:', error);
    }
}

Batch Operations

Clear Multiple Conversations:

// Clear unread for multiple conversations
async function clearMultipleConversations(userId, conversations) {
    const results = [];
    
    for (const conv of conversations) {
        try {
            await clearUnreadMessages({
                uid: userId,
                channel_id: conv.channel_id,
                channel_type: conv.channel_type
            });
            
            results.push({ 
                channel_id: conv.channel_id, 
                success: true 
            });
        } catch (error) {
            results.push({ 
                channel_id: conv.channel_id, 
                success: false, 
                error: error.message 
            });
        }
    }
    
    return results;
}

Auto-Read Functionality

Auto-mark as Read on Focus:

// Automatically clear unread when window gains focus
class AutoReadManager {
    constructor(userId) {
        this.userId = userId;
        this.activeConversation = null;
        this.setupEventListeners();
    }
    
    setupEventListeners() {
        // Clear unread when window gains focus
        window.addEventListener('focus', () => {
            if (this.activeConversation) {
                this.clearUnreadForActive();
            }
        });
        
        // Clear unread when user is actively typing
        document.addEventListener('keydown', () => {
            if (this.activeConversation) {
                this.clearUnreadForActive();
            }
        });
    }
    
    setActiveConversation(channelId, channelType) {
        this.activeConversation = { channelId, channelType };
        this.clearUnreadForActive();
    }
    
    async clearUnreadForActive() {
        if (!this.activeConversation) return;
        
        try {
            await clearUnreadMessages({
                uid: this.userId,
                channel_id: this.activeConversation.channelId,
                channel_type: this.activeConversation.channelType
            });
        } catch (error) {
            console.error('Auto-read failed:', error);
        }
    }
}

Read Receipt Integration

Combine with Read Receipts:

// Clear unread and send read receipt
async function markAsReadWithReceipt(channelId, channelType, userId, messageSeq) {
    try {
        // Clear unread count
        await clearUnreadMessages({
            uid: userId,
            channel_id: channelId,
            channel_type: channelType,
            message_seq: messageSeq
        });
        
        // Send read receipt to other participants
        await sendReadReceipt({
            channel_id: channelId,
            channel_type: channelType,
            message_seq: messageSeq,
            reader_uid: userId
        });
        
        console.log('Messages marked as read with receipt sent');
    } catch (error) {
        console.error('Failed to mark as read with receipt:', error);
    }
}

Best Practices

1. User Intent: Only clear unread when user actually views the messages
2. Batch Operations: Use batch clearing for better performance when possible
3. Error Handling: Handle network errors gracefully without affecting UI
4. Real-time Updates: Combine with WebSocket events for real-time unread updates
5. Offline Support: Queue clear operations when offline and sync when reconnected
6. Performance: Avoid excessive API calls by debouncing clear operations
7. User Experience: Provide visual feedback when clearing unread counts