Skip to main content

Sync APIs - Implementation and Usage

Overview​

This document provides a comprehensive guide to the Kettle Sync APIs. It covers usage, key concepts like their request parameters, response structures and its ordering. This is intended for developers integrating these APIs into applications, assuming familiarity with RESTful APIs and authentication tokens.

Configuring Sync APIs​

API endpoints​

Sync Chatroom API: GET /chatroom/sync​

Description: Synchronizes a list of chatrooms for a user, useful for populating home feeds, DM feeds, or joined chatrooms.

Request Parameters:

  • page: Int | Page number (default: 1)
  • page_size: Int | Items per page
  • max_timestamp: Timestamp | Max epoch timestamp for filtering (supports ms in x-api-version >= 2)
  • min_timestamp: Timestamp | Min epoch timestamp for filtering (supports ms in x-api-version >= 2)
  • is_local_db: Bool | Local DB mode (default: true)
  • chatroom_types: [Int] | Types of chatrooms (disabled in the request)
  • included_conversation_states: [Int] | Conversation states to be included while fetching the data
  • chatroom_id: Int | Specific chatroom ID to sync

Response:

  • card_attachments_meta: Object | Map of community ID to list of attachments metadata
  • community_meta: Object | Community basic information
  • chatrooms_data: Array | Chatrooms with their details
  • conv_attachments_meta: Object | Map of conversation ID to list of attachments metadata
  • conv_polls_meta: Object | Map of conversation id to polls metadata
  • conversation_meta: Object | Map of conversation ID to conversation metadata
  • sync_meta: Object | Sync information (x-api-version >= 1)
  • user_meta: Object | Map of user id to user metadata
  • widgets: Object | Map of widget id to widget metadata

Sync Conversation API: GET /conversation/sync​

Description: Synchronizes conversations within a specific chatroom, ideal for loading message histories or near real-time updates.

Request Parameters:

  • page: Integer | Page number (default: 1)
  • page_size: Integer | Items per page
  • max_timestamp: Timestamp | Max epoch timestamp for filtering (supports milliseconds format in x-api-version >= 2)
  • min_timestamp: Timestamp | Min epoch timestamp for filtering (supports milliseconds format in x-api-version >= 2)
  • is_local_db: Boolean | Local DB mode (default: true)
  • order_by: String | Ordering of results
  • excluded_conversation_states: [Integer] | Conversation states to be excluded while fetching the data
  • conversation_id: Integer | Specific conversation to sync

Response:

  • chatroom_reactions_meta: Object | Details of reactions over conversations in a chatroom
  • community_meta: Object | Community basic information
  • conv_reactions_meta: Object | Details of reactions over a conversation
  • conv_attachments_meta: Object | Map of conversation ID to list of attachments metadata
  • conv_polls_meta: Object | Map of conversation id to polls metadata
  • conversation_meta: Object | Map of conversation ID to conversation metadata
  • conversations_data: Object | Conversation details
  • user_meta: Object | Map of user id to user metadata
  • widgets: Object | Map of widget id to widget metadata

Fetching response for local/non-local DB​

The primary usage of is_local_db query parameter (Boolean, default: true) is in ordering of response.

is_local_db = true​

  • Description: Calls the API for local DB. Response of chatrooms will be ordered based on the chatrooms updated_at (from chatroom schema) .
  • Use Cases:
    • When user use storage of the app for ordering.

is_local_db = false​

  • Description: Calls the API for non-local DB. Response of chatrooms will be ordered by last conversation’s created_at (from chatroom schema) in descending order, only for chatrooms of type 0 (text), 10 (micro-poll).
  • Use Cases:
    • When user doesn't use storage of the app for ordering.

Example Use Cases​

Below are practical, developer-focused scenarios explaining why and when to call each Sync API and whether to use is_local_db=true or false.

1. Home feed / Joined chatrooms (fast, frequent updates)​

Note: Chatroom types available for is_local_db=true are 0 (text), 1 (header), and 10 (micropoll).

Scenario:
User opens the app and the home feed must show chatrooms they’ve joined and recent activity quickly.

API: GET /chatroom/sync

Request Example:

curl --location --globoff 'https://betaauth.likeminds.community/chatroom/sync?page=1&page_size=50&max_timestamp=1760350227&min_timestamp=0&chatroom_types=[0,7,10]&is_local_db=true' \
--header 'Authorization: <your_access_token>' \
--header 'x-platform-code: an' \
--header 'x-version-code: 318'

2. Conversation view (read history / fast scroll)​

Scenario: User opens a conversation to read recent messages and scrolls through history. \ API: GET /conversation/sync \ Request url :

curl --location 'https://betaauth.likeminds.community/conversation/sync?chatroom_id=74936&page=1&page_size=200&min_timestamp=0&max_timestamp=1760350434000&is_local_db=false' \
--header 'Authorization: <your_access_token>' \
--header 'x-api-key: b1f10c5c-778c-4a07-b******d54da9' \