Data Import and Migration

Migrate users, messages, groups, and conversations into CometChat with historical import or live migration workflows.

Data import and migration enables you to transfer existing chat data from your own servers or another chat provider to CometChat. This ensures continuity of service and preserves your users’ conversation history during the transition.

What Can Be Migrated?

CometChat’s migration capabilities cover:

• Users: User profiles, metadata, and account information
• Messages: Complete message history including text, media, and metadata
• Groups: Group configurations and membership information
• Conversations: Conversation threads and their associated data

Migration Approaches

CometChat offers two approaches to data migration, depending on your needs:

Historical Data Import

Import all your existing data at rest—stored messages, users, and groups—into CometChat before going live. This approach is ideal when:

• You’re doing a complete platform switch
• You want all historical data available from day one
• Your migration can happen during a maintenance window

The Data Import APIs handle bulk ingestion of historical chat data through four endpoints — users, groups, group members, and messages.

Import in dependency order so every reference resolves: users → groups → members → messages.

Throughput and batching. Each request accepts up to 50 entities, and the data-import endpoints are rate-limited to 60 requests per minute (see Rate Limits). To ingest large volumes, batch your records into groups of 50 and pace requests to stay under the limit; a ERR_TOO_MANY_REQUESTS response tells you to retry after the indicated time.

Timestamps are preserved. Each imported message carries a required sentAt field (a 10-digit UNIX timestamp), so conversation ordering and history reflect the original send times rather than the ingestion time.

Media. Message media and attachments are supplied in the message’s data.attachments object. For the full per-entity schema and field limits, see the Import Messages reference and Properties and Constraints.

Live Data Migration

Maintain communication between users on your old system and users who have already migrated to CometChat. This approach is ideal when:

• You need zero downtime during migration
• Users will upgrade to the new app version gradually
• Seamless communication must continue throughout the transition period

Live migration bridges both systems during the upgrade cycle, ensuring no messages are lost regardless of which system a user is currently on.

Getting Started

Historical Data Import

All Data Import REST API requests go to your app’s region-specific base URL and authenticate with the apikey header:

https://<appId>.api-<region>.cometchat.io/v3/data_import

A message import request wraps each message by its unique muid. The minimum required fields per message are muid, sender, receiverType, receiver, and sentAt:

curl -X POST "https://<appId>.api-<region>.cometchat.io/v3/data_import/messages" \
  -H "apikey: YOUR_REST_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "guid": "support-group",
    "name": "Support Group",
    "type": "group",
    "messages": {
      "msg-1001": {
        "muid": "msg-1001",
        "sender": "cometchat-uid-1",
        "receiverType": "group",
        "receiver": "support-group",
        "category": "message",
        "type": "text",
        "sentAt": 1700000000,
        "data": { "text": "Hello from the migrated history" }
      }
    }
  }'

Import in order — users → groups → members → messages — batching up to 50 entities per request.

Live Data Migration

Contact our Sales team to scope your migration and set up the bridge that keeps your old system and CometChat in sync during a gradual rollout.

Looking to upgrade an existing CometChat app from v2 to v3 (rather than import from another provider)? See the Migration Guide.