Ably Chat is a set of purpose-built APIs for a host of chat features enabling you to create 1:1, 1:Many, Many:1 and Many:Many chat rooms for any scale. It is designed to meet a wide range of chat use cases, such as livestreams, in-game communication, customer support, or social interactions in SaaS products. Built on Ably's core service, it abstracts complex details to enable efficient chat architectures.
Get started using the 📚 documentation.
This SDK works on Android 7.0+ (API level 24+) and Java 8+.
This project is under development so we will be incrementally adding new features. At this stage, you'll find APIs for the following chat features:
- Chat rooms for 1:1, 1:many, many:1 and many:many participation.
- Sending and receiving chat messages.
- Online status aka presence of chat participants.
- Chat room occupancy, i.e total number of connections and presence members.
- Typing indicators
- Room-level reactions (ephemeral at this stage)
If there are other features you'd like us to prioritize, please let us know.
You will need the following prerequisites:
- An Ably account
- You can sign up to the generous free tier.
- An Ably API key
- Use the default or create a new API key in an app within your Ably account dashboard.
- Make sure your API key has the
following capabilities:
publish,subscribe,presence,historyandchannel-metadata.
The Ably Chat SDK is available on the Maven Central Repository. To include the dependency in your project, add the following to your build.gradle file:
For Groovy:
implementation 'com.ably.chat:chat-android:0.2.0'For Kotlin Script (build.gradle.kts):
implementation("com.ably.chat:chat-android:0.2.0")Key functionality such as sending and receiving messages is powered by the ably-android library.
The ably-android library is included as an api dependency within the Chat SDK, so there is no need to manually add it to your project.
The Ably client library follows Semantic Versioning. See https://github.com/ably/ably-chat-kotlin/tags for a list of tagged releases.
To instantiate the Chat SDK, create an Ably client and pass it into the Chat constructor:
import com.ably.chat.ChatClient
import io.ably.lib.realtime.AblyRealtime
import io.ably.lib.types.ClientOptions
val realtimeClient = AblyRealtime(
ClientOptions().apply {
key = "<api-key>"
clientId = "<client-id>"
},
)
val chatClient = ChatClient(realtimeClient)You can use basic authentication i.e. the API Key directly for testing purposes, however it is strongly recommended that you use token authentication in production environments.
To use Chat you must also set a clientId so that clients are
identifiable. If you are prototyping, you can use java.util.UUID to generate an ID.
In most cases, clientId can be set to userId, the user’s application-specific identifier, provided that userId
is unique within the context of your application.
At the end of this tutorial, you will have initialized the Ably Chat client and sent your first message.
Start by creating a new Android project and installing the Chat SDK using the instructions described above. Then add the code in the following snippet to your app and call it in your code. This simple script initializes the Chat client, creates a chat room and sends a message, printing it to logcat when it is received over the websocket connection.
import kotlinx.coroutines.delay
import io.ably.lib.realtime.AblyRealtime
import io.ably.lib.types.ClientOptions
import com.ably.chat.ChatClient
import com.ably.chat.ConnectionStatusChange
import com.ably.chat.RoomOptions
import com.ably.chat.RoomStatusChange
suspend fun getStartedWithChat() {
// Create an Ably Realtime client that will be passed to the chat client
val realtimeClient = AblyRealtime(
ClientOptions().apply {
key = "<API_KEY>"
clientId = "ably-chat"
},
)
// Create the chat client
// The two clients can be re-used for the duration of your application.
val chatClient = ChatClient(realtimeClient)
// Subscribe to connection state changes
val connectionSubscription = chatClient.connection.onStatusChange { statusChange: ConnectionStatusChange ->
println("Connection status changed: ${statusChange.current}")
}
// Get our chat room and subscribe to status changes
val room = chatClient.rooms.get("readme-getting-started", RoomOptions.default)
val roomSubscription = room.onStatusChange {statusChange: RoomStatusChange ->
println("Room status changed: ${statusChange.current}")
}
// Subscribe to incoming messages
val messageSubscription = room.messages.subscribe { event ->
println("Message received: ${event.message.text}")
}
// Attach the room - meaning we'll start receiving events from the server
room.attach()
// Send a message
room.messages.send(text = "Hello, World! This is my first message with Ably Chat!")
// Wait for 5 seconds to make sure the message has time to be received.
delay(5000)
// Now release the room and close the connection
chatClient.rooms.release("readme-getting-started")
realtimeClient.close()
}All being well, you should see lines in logcat resembling the following:
Connection status changed: Connected
Room status changed: Attaching
Room status changed: Attached
Message received: Hello, World! This is my first message with Ably Chat!
Room status changed: Releasing
Room status changed: Released
Congratulations! You have sent your first message using the Ably Chat SDK!
Click 📚 here to view the complete documentation for the Ably Chat SDKs.
For guidance on how to contribute to this project, see the contributing guidelines.
Please visit http://support.ably.com/ for access to our knowledge base and to ask for any assistance. You can also view the community reported Github issues or raise one yourself.
To see what has changed in recent versions, see the changelog.
- See a simple chat example in this repo.
- Share feedback or request a new feature.