Skip to main content
POST
/
conversations
/
clearUnread
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
  }'

{
  "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 -X POST "http://localhost:5001/conversations/clearUnread" \
  -H "Content-Type: application/json" \
  -d '{
    "uid": "user123",
    "channel_id": "group123",
    "channel_type": 2,
    "message_seq": 1001
  }'

{
  "status": "ok"
}

​
Response Fields

​
status
string
required
Operation status, returns "ok" on success

​
Status Codes

Status CodeDescription
200Unread messages cleared successfully
400Request parameter error
403No operation permission
404Conversation does not exist
500Internal 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