Creates a new ChatClient instance for interacting with Ably Chat.
The ChatClient is the main entry point for the Ably Chat SDK. It requires a Realtime client and provides access to chat rooms through the rooms property.
Important: The Ably Realtime client must have a clientId set. This identifies the user in chat rooms and is required for all chat operations.
NOTE: You can provide optional overrides to the ChatClient, these will be merged with the default options. See ChatClientOptions for the available options.
An initialized Ably Realtime client with a configured clientId
OptionalclientOptions: ChatClientOptionsOptional configuration for the chat client
import * as Ably from 'ably';
import { ChatClient, LogLevel } from '@ably/chat';
// Preferred in production: Use auth URL that returns a JWT
const realtimeClientWithJWT = new Ably.Realtime({
authUrl: '/api/ably-auth', // Your server endpoint that returns a JWT with clientId
authMethod: 'POST'
});
const chatClient = new ChatClient(realtimeClientWithJWT)
// Alternative for development and server-side operations: Set clientId directly (requires API key)
const realtimeClientWithKey = new Ably.Realtime({
key: 'your-ably-api-key',
clientId: 'user-123'
});
const chatClient = new ChatClient(realtimeClientWithKey)
const realtimeClient = new Ably.Realtime({
authUrl: '/api/ably-auth',
authMethod: 'POST'
});
// With custom logging configuration: Defaults to LogLevel.Info and console logging
const chatClientWithLogging = new ChatClient(realtimeClient, {
logLevel: LogLevel.Debug,
logHandler: (message, level, context) => {
// Send to your logging service
yourLoggerInstance.log({
level,
message,
context,
timestamp: new Date()
});
}
});
Returns the clientId of the current client, if known.
Important When using an Ably key for authentication, this value is determined immediately. If using a token,
the clientId is not known until the client has successfully connected to and authenticated with
the server. Use the chatClient.connection.status to check the connection status.
The clientId, or undefined if unknown.
The configuration options used to initialize the chat client.
The resolved client options including defaults
Provides access to the underlying connection to Ably for monitoring connectivity.
The Connection instance
const chatClient: ChatClient; // existing ChatClient instance
// Check current connection status
console.log('Status:', chatClient.connection.status);
console.log('Error:', chatClient.connection.error);
// Monitor connection changes
const { off } = chatClient.connection.onStatusChange((change) => {
console.log(`Connection: ${change.previous} -> ${change.current}`);
});
Provides direct access to the underlying Ably Realtime client.
Use this for advanced scenarios requiring direct Ably access. Most chat operations should use the high-level chat SDK methods instead.
Note: Directly interacting with the Ably Realtime client can lead to unexpected behavior.
The underlying Ably Realtime client instance
Provides access to the rooms instance for creating and managing chat rooms.
The Rooms instance for managing chat rooms
const chatClient: ChatClient; // existing ChatClient instance
// Get a room with default options
const room = await chatClient.rooms.get('general-chat');
// Get a room with custom options (merges with defaults)
const configuredRoom = await chatClient.rooms.get('team-chat', {
typing: { heartbeatThrottleMs: 1000 }
});
// Release a room when done
await chatClient.rooms.release('general-chat');
Disposes of the ChatClient instance and releases all resources.
Releases all chat rooms, removes event listeners, and cleans up connections. After calling dispose, the ChatClient instance is no longer usable. This should be called when you're completely done with the chat functionality.
Note: This will release ALL rooms managed by this ChatClient and the ChatClient cannot be reused after disposal.
Promise that resolves when all resources are released
import * as Ably from 'ably';
import { ChatClient } from '@ably/chat';
const chatClient: ChatClient; // existing ChatClient instance
// Use the chat client
const roomOne = await chatClient.rooms.get('general-chat');
const roomTwo = await chatClient.rooms.get('random-chat');
// ... chat operations ...
// Clean up when completely done
try {
await chatClient.dispose();
console.log('Chat client disposed successfully');
} catch (error) {
console.error('Failed to dispose chat client:', error);
}
This is the core client for Ably chat. It provides access to chat rooms.