Overview
Sync user’s conversation list and status, supporting both incremental and full synchronization.
Request Body
Required Parameters
Optional Parameters
Version timestamp for incremental sync
Client’s last message sequence numbers, format: channelID:channelType:last_msg_seq|channelID:channelType:last_msg_seq
Number of recent messages to return for each conversation
Whether to return only unread conversations (1=only unread, 0=return all)
Array of channel types to exclude curl -X POST "http://localhost:5001/conversation/sync" \
-H "Content-Type: application/json" \
-d '{
"uid": "user123",
"version": 1640995200000000000,
"last_msg_seqs": "user1:1:100|group1:2:200",
"msg_count": 10,
"only_unread": 0,
"exclude_channel_types": [3, 4]
}'
[
{
"channel_id": "group123",
"channel_type": 2,
"unread": 5,
"timestamp": 1640995200,
"last_msg_seq": 1005,
"version": 1640995200000000000,
"messages": [
{
"message_id": 123456789,
"message_seq": 1005,
"client_msg_no": "msg_123",
"from_uid": "user456",
"timestamp": 1640995200,
"payload": "SGVsbG8gV29ybGQ="
}
]
},
{
"channel_id": "private_user123_user789",
"channel_type": 1,
"unread": 2,
"timestamp": 1640995100,
"last_msg_seq": 502,
"version": 1640995100000000000,
"messages": [
{
"message_id": 123456788,
"message_seq": 502,
"client_msg_no": "msg_122",
"from_uid": "user789",
"timestamp": 1640995100,
"payload": "SGkgdGhlcmU="
}
]
}
]
Response Fields
The response is an array of conversations, each containing the following fields:
Channel type
1 - Personal channel2 - Group channel
Number of unread messages
Last message sequence number
Conversation version number (nanosecond timestamp)
Message List
List of latest messages in the conversationShow Message object fields
Base64 encoded message content
Status Codes
| Status Code | Description |
|---|
| 200 | Conversation sync successful |
| 400 | Request parameter error |
| 403 | No access permission |
| 500 | Internal server error |
Parameter Details
Message Count (msg_count)
Controls the number of messages returned for each conversation:
| Value | Description | Use Case |
|---|
| 0 | No messages returned | Only need conversation list |
| 1-50 | Return specified number | Normal usage |
| > 50 | System limited to 50 | Avoid excessive data |
Version-based Incremental Sync
Use version parameter for efficient incremental synchronization:
// First sync - get all conversations
const initialSync = await syncConversations({
uid: "user123",
msg_count: 1
});
// Save the latest version
const latestVersion = Math.max(...initialSync.map(conv => conv.version));
// Later incremental sync - only get updated conversations
const incrementalSync = await syncConversations({
uid: "user123",
version: latestVersion,
msg_count: 1
});
Last Message Sequence Tracking
Track message sequences to detect missed messages:
// Build last_msg_seqs string from current conversations
function buildLastMsgSeqs(conversations) {
return conversations
.map(conv => `${conv.channel_id}:${conv.channel_type}:${conv.last_msg_seq}`)
.join('|');
}
// Use in sync request
const lastMsgSeqs = buildLastMsgSeqs(currentConversations);
const syncResult = await syncConversations({
uid: "user123",
last_msg_seqs: lastMsgSeqs,
msg_count: 5
});
Use Cases
Chat List Display
Initial Load:
// Load conversation list for chat interface
const conversations = await syncConversations({
uid: "user123",
msg_count: 1,
exclude_channel_types: [3, 4] // Exclude system channels
});
// Display in UI
conversations.forEach(conv => {
displayConversation(conv);
});
// Get only unread conversations for badge updates
const unreadConversations = await syncConversations({
uid: "user123",
only_unread: 1,
msg_count: 0
});
const totalUnread = unreadConversations.reduce((sum, conv) => sum + conv.unread, 0);
updateUnreadBadge(totalUnread);
Real-time Sync
Periodic Sync:
let lastSyncVersion = 0;
async function periodicSync() {
const conversations = await syncConversations({
uid: "user123",
version: lastSyncVersion,
msg_count: 1
});
if (conversations.length > 0) {
updateConversationList(conversations);
lastSyncVersion = Math.max(...conversations.map(c => c.version));
}
}
// Sync every 30 seconds
setInterval(periodicSync, 30000);
Offline Recovery
Sync After Reconnection:
async function syncAfterReconnection(uid, lastKnownVersion) {
try {
const missedConversations = await syncConversations({
uid: uid,
version: lastKnownVersion,
msg_count: 10
});
// Process missed conversations
missedConversations.forEach(conv => {
updateConversation(conv);
// Show notification for new messages
if (conv.unread > 0) {
showNewMessageNotification(conv);
}
});
} catch (error) {
console.error('Failed to sync conversations:', error);
}
}
Best Practices
- Incremental Sync: Use version-based incremental sync to reduce data transfer
- Appropriate Message Count: Set reasonable msg_count based on UI needs
- Error Handling: Handle network errors and implement retry logic
- Caching: Cache conversation data locally to improve performance
- Real-time Updates: Combine with WebSocket events for real-time updates
- Filtering: Use exclude_channel_types to filter out unwanted channel types
- Batch Processing: Process conversation updates in batches for better performance
