@ably/chat

Ably Chat JavaScript, TypeScript and React SDK

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.

Getting started

Everything you need to get started with Ably:

• About Ably Chat.
• Getting started with Ably Chat in JavaScript.
• Getting started with Ably Chat in React.
• Getting started with Ably Chat React UI kit.
• SDK and usage docs in JavaScript.
• SDK and usage docs in React.
• SDK and usage docs for React UI kit.
• API documentation (JavaScript).
• API documentation (React Hooks).
• API documentation (React UI kit).
• Chat Example App.
• Chat Example App using Ably Chat React UI kit.
• Play with the livestream chat demo.

Supported platforms

Ably aims to support a wide range of platforms. If you experience any compatibility issues, open an issue in the repository or contact Ably support.

This SDK supports the following platforms:

Platform	Support
Browsers	All major desktop and mobile browsers, including Chrome, Firefox, Edge, Safari (iOS/macOS), Opera, and Android. Internet Explorer is not supported.
Node.js	Version 20 or newer.
TypeScript	Fully supported, the library is written in TypeScript.
React	Includes providers and hooks for deep integration with the React ecosystem.
React Native	All React Native platforms. Issues can be reported or support requested.
Android	Supported via the Ably Chat Kotlin SDK.
iOS	Supported via the Ably Chat Swift SDK.

Installation

The Chat SDK is built on top of the Ably Pub/Sub SDK and uses that to establish a connection with Ably.

JavaScript/React

Install the Pub/Sub SDK and the Chat SDK:

npm install ably @ably/chat

Usage

JavaScript / TypeScript

The following code connects to Ably's chat service, subscribes to a chat room, and sends a message to that room:

import * as Ably from 'ably';
import { ChatClient, RoomStatus, RoomStatusChange } from '@ably/chat';

// Initialize Ably Realtime client
// Note: For client-side applications, token authentication is recommended.
// See: https://ably.com/docs/auth
const realtimeClient = new Ably.Realtime({
  key: '<your-ably-api-key>',
  clientId: 'your-client-id',
});

// Create a chat client
const chatClient = new ChatClient(realtimeClient);

// Get a chat room
const room = await chatClient.rooms.get('my-room');

// Monitor room status
room.onStatusChange((statusChange: RoomStatusChange) => {
  switch (statusChange.current) {
    case RoomStatus.Attached:
      console.log('Room is attached');
      break;
    case RoomStatus.Detached:
      console.log('Room is detached');
      break;
    case RoomStatus.Failed:
      console.log('Room failed:', statusChange.error);
      break;
    default:
      console.log('Room status:', statusChange.current);
  }
});

// Subscribe to messages
const subscription = room.messages.subscribe((event) => {
  console.log('Received message:', event.message.text);
});

// Attach to the room
await room.attach();

// Send a message
await room.messages.send({ text: 'Hello, World!' });

React

For React applications, the SDK provides hooks and providers for seamless integration:

import * as Ably from 'ably';
import { ChatClient } from '@ably/chat';
import { ChatClientProvider, ChatRoomProvider, useMessages } from '@ably/chat/react';

// Initialize clients
// Note: For client-side applications, token authentication is recommended.
// See: https://ably.com/docs/auth
const realtimeClient = new Ably.Realtime({
  key: '<your-ably-api-key>',
  clientId: 'your-client-id',
});
const chatClient = new ChatClient(realtimeClient);

// Wrap your app with providers
function App() {
  return (
    <ChatClientProvider client={chatClient}>
      <ChatRoomProvider name="my-room">
        <ChatComponent />
      </ChatRoomProvider>
    </ChatClientProvider>
  );
}

// Use hooks to interact with chat
function ChatComponent() {
  const { sendMessage } = useMessages({
    listener: (event) => {
      console.log('Received message:', event.message.text);
    },
  });

  const handleSend = async () => {
    await sendMessage({ text: 'Hello, World!' });
  };

  return <button onClick={handleSend}>Send Message</button>;
}

Releases

The CHANGELOG.md contains details of the latest releases for this SDK. You can also view all Ably releases on changelog.ably.com.

Contribute

Read the CONTRIBUTING.md guidelines to contribute to Ably or Share feedback or request a new feature.

Support, feedback, and troubleshooting

For help or technical support, visit Ably's support page. You can also view the community reported Github issues or raise one yourself.