Sync User Conversations

Sync user’s conversation list and status

POST /conversation/sync

cURL

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]
  }'

Success Response

[
  {
    "channel_id": "group123",
    "channel_type": 2,
    "unread": 5,
    "timestamp": 1640995200,
    "last_msg_seq": 1005,
    "version": 1640995200000000000,
    "recents": [
      {
        "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,
    "recents": [
      {
        "message_id": 123456788,
        "message_seq": 502,
        "client_msg_no": "msg_122",
        "from_uid": "user789",
        "timestamp": 1640995100,
        "payload": "SGkgdGhlcmU="
      }
    ]
  }
]

Overview

Sync user’s conversation list and status, supporting both incremental and full synchronization.

Request Body

Required Parameters

uid · string · required

User ID

Optional Parameters

version · integer

Version timestamp for incremental sync

last_msg_seqs · string

Client’s last message sequence numbers, format: channelID:channelType:last_msg_seq|channelID:channelType:last_msg_seq

msg_count · integer

Number of recent messages to return for each conversation

only_unread · integer · default: 0

Whether to return only unread conversations (1=only unread, 0=return all)

exclude_channel_types · array

Array of channel types to exclude

exclude_channel_types[] · integer

Channel type

cURL

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]
  }'

Success Response

[
  {
    "channel_id": "group123",
    "channel_type": 2,
    "unread": 5,
    "timestamp": 1640995200,
    "last_msg_seq": 1005,
    "version": 1640995200000000000,
    "recents": [
      {
        "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,
    "recents": [
      {
        "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:

Conversation Information

channel_id · string · required

Channel ID

channel_type · integer · required

Channel type

• 1 - Personal channel
• 2 - Group channel

unread · integer · required

Number of unread messages

timestamp · integer · required

Last message timestamp

last_msg_seq · integer · required

Last message sequence number

version · integer · required

Conversation version number (nanosecond timestamp)

Message List

recents · array · required

List of latest messages in the conversation

Show Message object fields

recents[].message_id · integer

Message ID

recents[].message_seq · integer

Message sequence number

recents[].client_msg_no · string

Client message number

recents[].from_uid · string

Sender user ID

recents[].timestamp · integer

Message timestamp

recents[].payload · string

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);
});

Unread Badge Update:

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

1. Incremental Sync: Use version-based incremental sync to reduce data transfer
2. Appropriate Message Count: Set reasonable msg_count based on UI needs
3. Error Handling: Handle network errors and implement retry logic
4. Caching: Cache conversation data locally to improve performance
5. Real-time Updates: Combine with WebSocket events for real-time updates
6. Filtering: Use exclude_channel_types to filter out unwanted channel types
7. Batch Processing: Process conversation updates in batches for better performance