User Sync

Sync users with CometChat Calls so app users can authenticate, join sessions, appear in participants, and use calling features.

Users must exist in CometChat before they can make or receive calls. This page explains how to create and authenticate users for the Calls SDK.

Why User Sync?

CometChat needs to know about your users to:

• Route calls — Connect callers to the right recipients
• Identify participants — Display names and avatars in calls
• Track history — Associate call logs with specific users
• Manage permissions — Control who can call whom

Creating Users

Choose the method that best fits your workflow:

Dashboard

Add users manually via the CometChat Dashboard. Ideal for quick testing or small teams.

SDK

Create users programmatically via SDK methods. Perfect for auto-provisioning during sign-up.

REST API

Create users using the REST API. Best for batch imports or backend workflows.

User Requirements

Required Fields

Field	Type	Description
uid	String	Unique user identifier. Alphanumeric, max 100 characters. Must be unique across your app.

Optional Fields

Field	Type	Description
name	String	Display name shown in calls and participant lists
avatar	String	URL to profile image
metadata	Object	Custom JSON data for your application
role	String	User role (default, admin, etc.)
tags	Array	Tags for categorization and filtering

Example User Object

{
  "uid": "user_123",
  "name": "John Doe",
  "avatar": "https://example.com/avatars/john.png",
  "metadata": {
    "department": "Engineering",
    "location": "San Francisco"
  }
}

Authentication Flow

1. Create User (One-time)

   Create the user in CometChat when they sign up for your app. This only needs to happen once per user.

   Server-side (recommended):

   curl -X POST "https://api-{region}.cometchat.io/v3/users" \
     -H "apiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"uid": "user_123", "name": "John Doe"}'
   
2. Generate Auth Token

   Generate an authentication token for the user on your server. This token is used to log in the user on the client.

   Server-side:

   curl -X POST "https://api-{region}.cometchat.io/v3/users/{uid}/auth_tokens" \
     -H "apiKey: YOUR_API_KEY" \
     -H "Content-Type: application/json"
   

   Response:

   {
     "data": {
       "uid": "user_123",
       "authToken": "user_123_abc123xyz..."
     }
   }
   
3. Login User (Client-side)

   Use the auth token to log in the user via the SDK. This establishes a session for making calls.

   JavaScript:

   CometChatCalls.login(authToken).then(
     user => console.log("Login successful:", user),
     error => console.log("Login failed:", error)
   );
   
4. Ready for Calls

   Once logged in, the user can initiate and receive calls. The SDK handles all session management automatically.

Authentication Methods

Auth Token (Recommended for Production)

Generate tokens server-side using the REST API. This is the secure method for production apps.

Pros:

• Secure — API key never exposed to clients
• Controlled — You decide when tokens are issued
• Auditable — Token generation can be logged

Flow:

1. User logs into your app
2. Your server generates a CometChat auth token
3. Token is sent to the client
4. Client uses token to log into CometChat

Auth Key (Development Only)

Use the Auth Key directly in client code for quick testing. Never use in production.

JavaScript:

CometChatCalls.login(uid, authKey).then(
  user => console.log("Login successful:", user),
  error => console.log("Login failed:", error)
);

Security Warning: Never expose your Auth Key in production client code. Auth Keys have full access to create users and perform admin operations. Always use auth tokens generated server-side for production apps.

Sync Strategies

Just-in-Time Provisioning

Create CometChat users when they first need calling functionality:

// When user initiates their first call
async function ensureUserExists(user) {
  try {
    // Try to get auth token (user exists)
    return await getAuthToken(user.id);
  } catch (error) {
    // User doesn't exist, create them first
    await createCometChatUser(user);
    return await getAuthToken(user.id);
  }
}

Best for: Apps where not all users need calling

Batch Import

Import existing users via REST API when integrating CometChat:

# Create multiple users
curl -X POST "https://api-{region}.cometchat.io/v3/users" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '[
    {"uid": "user_1", "name": "Alice"},
    {"uid": "user_2", "name": "Bob"},
    {"uid": "user_3", "name": "Charlie"}
  ]'

Best for: Migrating existing user bases

Webhook Sync

Use webhooks to keep CometChat users in sync with your database:

1. User signs up → Create CometChat user
2. User updates profile → Update CometChat user
3. User deletes account → Delete CometChat user

Best for: Apps with frequent user changes

User Lifecycle

Creating Users

Users can be created via:

• REST API (server-side)
• SDK createUser method
• Dashboard (manual)

Updating Users

Update user details when they change in your app:

curl -X PUT "https://api-{region}.cometchat.io/v3/users/{uid}" \
  -H "apiKey: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "John Smith", "avatar": "https://new-avatar.png"}'

Deleting Users

Remove users when they leave your platform:

curl -X DELETE "https://api-{region}.cometchat.io/v3/users/{uid}" \
  -H "apiKey: YOUR_API_KEY"

Soft Delete: By default, deleted users are soft-deleted and can be restored. Use permanent=true query parameter for permanent deletion.

Best Practices

Do

• Generate auth tokens server-side
• Use consistent UIDs across your app
• Keep user data in sync
• Handle token expiration gracefully

Don’t

• Expose API keys in client code
• Use Auth Key in production
• Create duplicate users
• Store auth tokens long-term

Next Steps

Compatibility

Check platform and browser support

REST API Reference

Full API documentation for user management