Sync User Conversations

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

const response = await fetch('http://localhost:5001/conversation/sync', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uid: 'user123',
    version: 1640995200000000000,
    last_msg_seqs: 'user1:1:100|group1:2:200',
    msg_count: 10,
    only_unread: 0,
    exclude_channel_types: [3, 4]
  })
});

const data = await response.json();
console.log(data);

import requests

data = {
    "uid": "user123",
    "version": 1640995200000000000,
    "last_msg_seqs": "user1:1:100|group1:2:200",
    "msg_count": 10,
    "only_unread": 0,
    "exclude_channel_types": [3, 4]
}

response = requests.post('http://localhost:5001/conversation/sync', json=data)
result = response.json()
print(result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    data := map[string]interface{}{
        "uid":                    "user123",
        "version":                1640995200000000000,
        "last_msg_seqs":          "user1:1:100|group1:2:200",
        "msg_count":              10,
        "only_unread":            0,
        "exclude_channel_types":  []int{3, 4},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/conversation/sync",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result []map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
}

[
  {
    "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="
      }
    ]
  }
]

POST

conversation

sync

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

const response = await fetch('http://localhost:5001/conversation/sync', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uid: 'user123',
    version: 1640995200000000000,
    last_msg_seqs: 'user1:1:100|group1:2:200',
    msg_count: 10,
    only_unread: 0,
    exclude_channel_types: [3, 4]
  })
});

const data = await response.json();
console.log(data);

import requests

data = {
    "uid": "user123",
    "version": 1640995200000000000,
    "last_msg_seqs": "user1:1:100|group1:2:200",
    "msg_count": 10,
    "only_unread": 0,
    "exclude_channel_types": [3, 4]
}

response = requests.post('http://localhost:5001/conversation/sync', json=data)
result = response.json()
print(result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    data := map[string]interface{}{
        "uid":                    "user123",
        "version":                1640995200000000000,
        "last_msg_seqs":          "user1:1:100|group1:2:200",
        "msg_count":              10,
        "only_unread":            0,
        "exclude_channel_types":  []int{3, 4},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/conversation/sync",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result []map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
}

[
  {
    "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

string

required

User ID

Optional Parameters

integer

Version timestamp for incremental sync

string

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

integer

Number of recent messages to return for each conversation

integer

default:0

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

array

Array of channel types to exclude

integer

Channel type

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

const response = await fetch('http://localhost:5001/conversation/sync', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    uid: 'user123',
    version: 1640995200000000000,
    last_msg_seqs: 'user1:1:100|group1:2:200',
    msg_count: 10,
    only_unread: 0,
    exclude_channel_types: [3, 4]
  })
});

const data = await response.json();
console.log(data);

import requests

data = {
    "uid": "user123",
    "version": 1640995200000000000,
    "last_msg_seqs": "user1:1:100|group1:2:200",
    "msg_count": 10,
    "only_unread": 0,
    "exclude_channel_types": [3, 4]
}

response = requests.post('http://localhost:5001/conversation/sync', json=data)
result = response.json()
print(result)

package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "net/http"
)

func main() {
    data := map[string]interface{}{
        "uid":                    "user123",
        "version":                1640995200000000000,
        "last_msg_seqs":          "user1:1:100|group1:2:200",
        "msg_count":              10,
        "only_unread":            0,
        "exclude_channel_types":  []int{3, 4},
    }
    
    jsonData, _ := json.Marshal(data)
    
    resp, err := http.Post(
        "http://localhost:5001/conversation/sync",
        "application/json",
        bytes.NewBuffer(jsonData),
    )
    if err != nil {
        panic(err)
    }
    defer resp.Body.Close()
    
    var result []map[string]interface{}
    json.NewDecoder(resp.Body).Decode(&result)
    fmt.Printf("%+v\n", result)
}

[
  {
    "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

string

required

Channel ID

integer

required

Channel type

1 - Personal channel
2 - Group channel

integer

required

Number of unread messages

integer

required

Last message timestamp

integer

required

Last message sequence number

integer

required

Conversation version number (nanosecond timestamp)

Message List

array

required

List of latest messages in the conversation

Show Message object fields

integer

Message ID

integer

Message sequence number

string

Client message number

string

Sender user ID

integer

Message timestamp

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

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

Remove System User IDs Clear Unread Messages

Route Management

Message Management

Channel Management

User Management

Conversation Management

Connection Management

Event Management

Monitoring

System

Integration APIs

Administrator

Sync User Conversations

Overview

Request Body

Required Parameters

Optional Parameters

Response Fields

Conversation Information

Message List

Status Codes

Parameter Details

Message Count (msg_count)

Version-based Incremental Sync

Last Message Sequence Tracking

Use Cases

Chat List Display

Real-time Sync

Offline Recovery

Best Practices

​Overview

​Request Body

​Required Parameters

​Optional Parameters

​Response Fields

​Conversation Information

​Message List

​Status Codes

​Parameter Details

​Message Count (msg_count)

​Version-based Incremental Sync

​Last Message Sequence Tracking

​Use Cases

​Chat List Display

​Real-time Sync

​Offline Recovery

​Best Practices

Overview

Request Body

Required Parameters

Optional Parameters

Response Fields

Conversation Information

Message List

Status Codes

Parameter Details

Message Count (msg_count)

Version-based Incremental Sync

Last Message Sequence Tracking

Use Cases

Chat List Display

Real-time Sync

Offline Recovery

Best Practices