ChatClient

Open in

The ChatClient interface is the main entry point for using the Ably Chat SDK. It provides access to chat rooms, connection management, and the underlying Ably Realtime client.

The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably. Instantiate a realtime client using the Pub/Sub SDK and pass the generated client into the Chat factory function.

Kotlin

import com.ably.chat.ChatClient
import com.ably.chat.LogLevel
import io.ably.lib.realtime.AblyRealtime
import io.ably.lib.types.ClientOptions

val realtimeClient = AblyRealtime(ClientOptions().apply {
    key = "demokey:*****"
    clientId = "<clientId>"
})
val chatClient = ChatClient(realtimeClient) {
    logLevel = LogLevel.Error
}

API key:

DEMO ONLY

An API key is required to authenticate with Ably. API keys are used either to authenticate directly with Ably using basic authentication, or to generate tokens for untrusted clients using JWT authentication.

Properties

The ChatClient interface has the following properties:

roomsRooms

The rooms object, used to get or create chat room instances.

connectionConnection

The connection object, used to monitor the connection status with Ably.

clientIdString?

The client ID configured on the underlying Ably Realtime client. Used to identify the current user.

realtimeAblyRealtime

The underlying Ably Realtime client instance. Note: this property is experimental and may change in a future release.

clientOptionsChatClientOptions

The resolved configuration options with defaults applied.

Create a chat client

ChatClient(realtimeClient: AblyRealtime, clientOptions: ChatClientOptions = buildChatClientOptions()): ChatClient

Create a new ChatClient instance by passing an Ably Realtime client and optional configuration options. ChatClient is a top-level factory function, not a class constructor.

Kotlin

import com.ably.chat.ChatClient
import com.ably.chat.buildChatClientOptions
import com.ably.chat.LogLevel
import io.ably.lib.realtime.AblyRealtime
import io.ably.lib.types.ClientOptions

val realtimeClient = AblyRealtime(ClientOptions().apply {
    key = "demokey:*****"
    clientId = "user-123"
})

val chatClient = ChatClient(realtimeClient, buildChatClientOptions {
    logLevel = LogLevel.Debug
})

API key:

DEMO ONLY

A DSL builder overload is also available:

ChatClient(realtimeClient: AblyRealtime, init: MutableChatClientOptions.() -> Unit): ChatClient

Kotlin

val chatClient = ChatClient(realtimeClient) {
    logLevel = LogLevel.Debug
}

Parameters

The ChatClient() factory function takes the following parameters:

realtimeClientrequiredAblyRealtime

An instance of the Ably Realtime client, configured with your API key and a clientId. The clientId is required for all chat operations.

clientOptionsoptionalChatClientOptions

Configuration options for the Chat client.

ChatException

A specialized exception class for errors that occur during chat operations. ChatException extends RuntimeException and wraps an ErrorInfo object containing detailed error information. All suspend functions in the SDK throw ChatException on failure.

errorInfoErrorInfo

Detailed error information including Ably-specific error codes and HTTP status codes.

messageString?

The exception message.

causeThrowable?

The underlying cause of the exception, if any.

Kotlin

import com.ably.chat.ChatException

try {
    room.messages.send(text = "Hello!")
} catch (e: ChatException) {
    println("Error code: ${e.errorInfo.code}")
    println("Message: ${e.errorInfo.message}")
    println("Status: ${e.errorInfo.statusCode}")
}

ErrorInfo

A standardized, generic Ably error object that contains an Ably-specific status code, and a generic HTTP status code. All errors thrown by the SDK are compatible with the ErrorInfo structure.

codeInt

Ably-specific error code.

statusCodeInt

HTTP status code corresponding to this error, where applicable.

messageString

Additional information about the error.

hrefString?

A URL providing more information about the error.

causeErrorInfo?

The underlying cause of the error.

requestIdString?

The request ID if the error originated from an API request.

Example

Kotlin

import com.ably.chat.ChatClient
import com.ably.chat.LogLevel
import io.ably.lib.realtime.AblyRealtime
import io.ably.lib.types.ClientOptions

val realtimeClient = AblyRealtime(ClientOptions().apply {
    key = "demokey:*****"
    clientId = "user-123"
})

val chatClient = ChatClient(realtimeClient) {
    logLevel = LogLevel.Debug
}

// Access rooms
val room = chatClient.rooms.get("my-room")

// Check connection status
println(chatClient.connection.status)

// Get current user ID
println(chatClient.clientId)

API key:

DEMO ONLY