Overview
Set the unread message count for a specified conversation, used for manually adjusting the unread status of conversations.
Request Body
Required Parameters
Channel type (1=personal channel, 2=group channel)
curl -X POST "http://localhost:5001/conversations/setUnread" \
-H "Content-Type: application/json" \
-d '{
"uid": "user123",
"channel_id": "group123",
"channel_type": 2,
"unread": 5
}'
Response Fields
Operation status, returns "success" on success
Status Codes
| Status Code | Description |
|---|
| 200 | Unread count set successfully |
| 400 | Request parameter error |
| 403 | No operation permission |
| 500 | Internal server error |
Use Cases
Manual Unread Management
Mark Conversation as Important:
// Mark conversation as having unread messages to draw attention
async function markAsImportant(userId, channelId, channelType) {
try {
await setUnreadCount({
uid: userId,
channel_id: channelId,
channel_type: channelType,
unread: 1
});
console.log('Conversation marked as important');
updateUIBadge(channelId, 1);
} catch (error) {
console.error('Failed to mark conversation as important:', error);
}
}
Reset Unread Count:
// Reset unread count to zero
async function resetUnreadCount(userId, channelId, channelType) {
try {
await setUnreadCount({
uid: userId,
channel_id: channelId,
channel_type: channelType,
unread: 0
});
console.log('Unread count reset to zero');
updateUIBadge(channelId, 0);
} catch (error) {
console.error('Failed to reset unread count:', error);
}
}
Notification Management
Custom Notification Badges:
// Set custom unread count for special notifications
async function setCustomNotification(userId, channelId, channelType, count) {
try {
await setUnreadCount({
uid: userId,
channel_id: channelId,
channel_type: channelType,
unread: count
});
// Update UI with custom badge
updateNotificationBadge(channelId, count);
// Show system notification if count > 0
if (count > 0) {
showSystemNotification(`${count} new items in ${channelId}`);
}
} catch (error) {
console.error('Failed to set custom notification:', error);
}
}
Batch Unread Operations
Batch Set Unread Counts:
// Set unread counts for multiple conversations
async function batchSetUnreadCounts(userId, conversationUpdates) {
const results = [];
for (const update of conversationUpdates) {
try {
await setUnreadCount({
uid: userId,
channel_id: update.channelId,
channel_type: update.channelType,
unread: update.unreadCount
});
results.push({
channelId: update.channelId,
success: true,
unreadCount: update.unreadCount
});
} catch (error) {
results.push({
channelId: update.channelId,
success: false,
error: error.message
});
}
}
return results;
}
// Usage
const updates = [
{ channelId: 'group123', channelType: 2, unreadCount: 5 },
{ channelId: 'user456', channelType: 1, unreadCount: 2 },
{ channelId: 'group789', channelType: 2, unreadCount: 0 }
];
const results = await batchSetUnreadCounts('user123', updates);
console.log('Batch update results:', results);
Priority Management
Set Priority-based Unread Counts:
class ConversationPriorityManager {
constructor(userId) {
this.userId = userId;
this.priorityLevels = {
urgent: 99,
high: 10,
normal: 1,
low: 0
};
}
async setPriority(channelId, channelType, priority) {
const unreadCount = this.priorityLevels[priority] || 1;
try {
await setUnreadCount({
uid: this.userId,
channel_id: channelId,
channel_type: channelType,
unread: unreadCount
});
// Update UI with priority styling
this.updatePriorityUI(channelId, priority, unreadCount);
console.log(`Set ${channelId} priority to ${priority} (unread: ${unreadCount})`);
} catch (error) {
console.error(`Failed to set priority for ${channelId}:`, error);
}
}
updatePriorityUI(channelId, priority, unreadCount) {
const element = document.querySelector(`[data-channel="${channelId}"]`);
if (element) {
element.className = `conversation-item priority-${priority}`;
const badge = element.querySelector('.unread-badge');
if (badge) {
badge.textContent = unreadCount > 0 ? unreadCount : '';
badge.style.display = unreadCount > 0 ? 'block' : 'none';
}
}
}
async markAsUrgent(channelId, channelType) {
await this.setPriority(channelId, channelType, 'urgent');
}
async markAsNormal(channelId, channelType) {
await this.setPriority(channelId, channelType, 'normal');
}
async clearPriority(channelId, channelType) {
await this.setPriority(channelId, channelType, 'low');
}
}
// Usage
const priorityManager = new ConversationPriorityManager('user123');
// Mark conversation as urgent
await priorityManager.markAsUrgent('group123', 2);
// Set normal priority
await priorityManager.markAsNormal('user456', 1);
// Clear priority
await priorityManager.clearPriority('group789', 2);
Sync and Recovery
Sync Unread Counts from External Source:
// Sync unread counts from external system
async function syncUnreadFromExternal(userId, externalUnreadData) {
const syncResults = [];
for (const item of externalUnreadData) {
try {
await setUnreadCount({
uid: userId,
channel_id: item.channelId,
channel_type: item.channelType,
unread: item.unreadCount
});
syncResults.push({
channelId: item.channelId,
synced: true,
unreadCount: item.unreadCount
});
} catch (error) {
syncResults.push({
channelId: item.channelId,
synced: false,
error: error.message
});
}
}
// Log sync results
const successful = syncResults.filter(r => r.synced).length;
const failed = syncResults.filter(r => !r.synced).length;
console.log(`Sync completed: ${successful} successful, ${failed} failed`);
return syncResults;
}
Testing and Development
Test Unread Scenarios:
// Helper function for testing different unread scenarios
async function testUnreadScenarios(userId, channelId, channelType) {
const scenarios = [
{ name: 'No unread', count: 0 },
{ name: 'Single unread', count: 1 },
{ name: 'Multiple unread', count: 5 },
{ name: 'High unread', count: 99 },
{ name: 'Max unread', count: 999 }
];
for (const scenario of scenarios) {
console.log(`Testing scenario: ${scenario.name}`);
try {
await setUnreadCount({
uid: userId,
channel_id: channelId,
channel_type: channelType,
unread: scenario.count
});
// Wait for UI update
await new Promise(resolve => setTimeout(resolve, 500));
// Verify UI state
const badge = document.querySelector(`[data-channel="${channelId}"] .unread-badge`);
const displayedCount = badge ? badge.textContent : '0';
console.log(`✓ ${scenario.name}: Set ${scenario.count}, displayed ${displayedCount}`);
} catch (error) {
console.error(`✗ ${scenario.name}: Failed -`, error.message);
}
}
}
Best Practices
- Validation: Validate unread count values (non-negative integers)
- UI Consistency: Ensure UI updates match the set unread count
- Error Handling: Handle API errors gracefully without breaking UI
- Performance: Batch operations when setting multiple unread counts
- User Experience: Use meaningful unread counts that help users prioritize
- Sync Strategy: Implement proper sync mechanisms for unread counts
- Testing: Test various unread count scenarios during development