Chat Kotlin SDK: ChatClient
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.
1
2
3
4
5
6
7
8
9
10
11
12
13
import com.ably.chat.createChatClient
import com.ably.chat.LogLevel
import io.ably.pubsub.device.PubSubDevice
import io.ably.pubsub.types.ClientOptions
val pubsubDeviceClient = PubSubDevice.clientBuilder()
.key("demokey:*****")
.clientId("<clientId>")
.build()
val chatClient = createChatClient(pubsubDeviceClient) {
logLevel = LogLevel.Error
}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:
roomsRoomsconnectionConnectionclientIdString?pubsubClientPubSubRealtimeClientclientOptionsChatClientOptionsCreate a chat client
createChatClient(pubsubClient: PubSubRealtimeClient, clientOptions: ChatClientOptions = buildChatClientOptions()): ChatClientCreate a new ChatClient instance by passing a Pub/Sub realtime client and optional configuration options to the top-level createChatClient() factory function.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
import com.ably.chat.createChatClient
import com.ably.chat.buildChatClientOptions
import com.ably.chat.LogLevel
import io.ably.pubsub.device.PubSubDevice
import io.ably.pubsub.types.ClientOptions
val pubsubDeviceClient = PubSubDevice.clientBuilder(ClientOptions().apply {
key = "demokey:*****"
clientId = "user-123"
}).build()
val chatClient = createChatClient(pubsubDeviceClient, buildChatClientOptions {
logLevel = LogLevel.Debug
})A DSL builder overload is also available:
createChatClient(pubsubClient: PubSubRealtimeClient, init: MutableChatClientOptions.() -> Unit): ChatClient1
2
3
val chatClient = createChatClient(pubsubDeviceClient) {
logLevel = LogLevel.Debug
}Parameters
The createChatClient() factory function takes the following parameters:
pubsubClientrequiredPubSubRealtimeClientclientId. The clientId is required for all chat operations.clientOptionsoptionalChatClientOptionsChatException
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.
errorInfoErrorInfomessageString?causeThrowable?1
2
3
4
5
6
7
8
9
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.
codeIntstatusCodeIntmessageStringhrefString?causeErrorInfo?requestIdString?Example
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
import com.ably.chat.createChatClient
import com.ably.chat.LogLevel
import io.ably.pubsub.device.PubSubDevice
import io.ably.pubsub.types.ClientOptions
val pubsubDeviceClient = PubSubDevice.clientBuilder(ClientOptions().apply {
key = "demokey:*****"
clientId = "user-123"
}).build()
val chatClient = createChatClient(pubsubDeviceClient) {
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)