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.
- macOS 11 and above
- iOS 14 and above
- tvOS 14 and above
Xcode 16 or later.
The SDK is distributed as a Swift package and can hence be installed using Xcode (search for github.com/ably/ably-chat-swift package) or by adding it as a dependency in your package’s Package.swift:
.package(url: "https://github.com/ably/ably-chat-swift", from: "0.1.0")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.
To instantiate the Chat SDK, create an Ably client and pass it into the Chat constructor:
import Ably
import AblyChat
let realtimeOptions = ARTClientOptions()
realtimeOptions.key = "<API_KEY>"
realtimeOptions.clientId = "<clientId>"
let realtime = ARTRealtime(options: realtimeOptions)
let chatClient = DefaultChatClient(realtime: realtime, clientOptions: nil)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 users are
identifiable.
At the end of this tutorial, you will have initialized the Ably Chat client and sent your first message.
First of all, start by creating a Swift project and installing the Chat SDK using the instructions described above. Next, replace the contents of your main.swift file with
the following code. This simple script initializes the Chat client, creates a chat room and sends a message, printing it to the console when it is received over the websocket connection.
import Ably
import AblyChat
import Foundation
// Create the Ably Realtime client using your API key and use that to instantiate the Ably Chat client.
// You can re-use these clients for the duration of your application
let realtimeOptions = ARTClientOptions()
realtimeOptions.key = "<API_KEY>"
realtimeOptions.clientId = "ably-chat"
let realtime = ARTRealtime(options: realtimeOptions)
let chatClient = DefaultChatClient(realtime: realtime, clientOptions: nil)
// Subscribe to connection state changes
let connectionStateSubscription = chatClient.connection.onStatusChange()
Task {
for await stateChange in connectionStateSubscription {
print("Connection status changed: \(stateChange.current)")
}
}
// Get a chat room for the tutorial - using the defaults to enable all features in the chat room
let room = try await chatClient.rooms.get(
roomID: "readme-getting-started", options: RoomOptions.allFeaturesEnabled)
// Add a listener to observe changes to the chat rooms status
let statusSubscription = await room.onStatusChange()
Task {
for await status in statusSubscription {
print("Room status changed: \(status.current)")
}
}
// Attach the chat room - this means we will begin to receive messages from the server
try await room.attach()
// Add a listener for new messages in the chat room
let messagesSubscription = try await room.messages.subscribe()
Task {
// Subscribe to messages
for await message in messagesSubscription {
print("Message received: \(message.text)")
}
}
// Send a message
_ = try await room.messages.send(
params: .init(text: "Hello, World! This is my first message with Ably Chat!"))
// Wait 5 seconds before closing the connection so we have plenty of time to receive the message we just sent
// This disconnects the client from Ably servers
try await Task.sleep(nanoseconds: 5 * NSEC_PER_SEC)
await chatClient.rooms.release(roomID: "readme-getting-started")
realtime.close()
print("Connection closed")Now run your script:
swift runAll being well, you should now see the following in your terminal:
Room status changed: attaching(error: nil)
Connection status changed: connected
Room status changed: attached
Message received: Hello, World! This is my first message with Ably Chat!
Room status changed: releasing
Room status changed: released
Connection closed
Congratulations! You have sent your first message using the Ably Chat SDK!
This repository contains an example app, written using SwiftUI, which demonstrates how to use the SDK. The code for this app is in the Example directory.
In order to allow the app to use modern SwiftUI features, it supports the following OS versions:
- macOS 14 and above
- iOS 17 and above
- tvOS 17 and above
To run the app, open the AblyChat.xcworkspace workspace in Xcode and run the AblyChatExample target. If you wish to run it on an iOS or tvOS device, you’ll need to set up code signing.
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.
Share feedback or request a new feature.