SDK setup

Use these instructions to install, authenticate and instantiate the Chat SDK.

Authentication

Copied!

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 token authentication.

Sign up to Ably to create an API key in the dashboard or use the Control API to create an API key programmatically.

API keys and tokens have a set of capabilities assigned to them that specify which operations, such as subscribe or publish can be performed on which resources. To use the Chat SDK, the API key requires the following capabilities depending on which features are being used:

Feature Capabilities
Send and receive messages Publish, Subscribe
Message history Subscribe, History
Online status Subscribe, Presence
Room occupancy Subscribe, Channel Metadata
Typing indicators Publish, Subscribe, Presence
Room reactions Publish, Subscribe

When setting the capabilities for Chat, you need to apply them to either a wildcard resource, or a wildcard resource prefixed with the chat namespace, for example:

  • [chat]* and *, or
  • [*]*

Install

Copied!

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

Both SDKs are available as NPM modules and via CDN.

NPM

Copied!

Install the Pub/Sub SDK and the Chat SDK:


npm install @ably/chat


Copied!

Import the SDKs into your project:

Select...

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


Copied!

React Native

Copied!

If you’re using React Native, you may need to perform extra steps to use the Chat SDK.

The React package is exported as an ESM module called @ably/chat/react, which makes use of the exports field in package.json. The Metro bundler used by React Native does not utilize this field by default which results in the imports not being found.

To fix this issue:

  • Set the type field of your React Native project to module
  • Update your tsconfig.json to set "moduleResolution": "Bundler"
  • Include the unstable_enablePackageExports field in your metro.config.cjs

The following is an example of setting unstable_enablePackageExports in metro.config.cjs:

Select...

const { getDefaultConfig } = require('expo/metro-config');


const defaultConfig = getDefaultConfig(__dirname);


module.exports = {
  ...defaultConfig,
  resolver: {
    ...defaultConfig.resolver,
    unstable_enablePackageExports: true, // Enable 'exports' field in package.json,
  },
};


Copied!

Instantiate a client

Copied!

Instantiate a realtime client using the Pub/Sub SDK and pass the generated client into the Chat constructor.

Pass the ChatClient into the ChatClientProvider. The ChatClient instance will be available to all child components in your React component tree.

Select...

const realtimeClient = new Ably.Realtime({ key: '<loading API key, please wait>', clientId: '<clientId>'});
const chatClient = new ChatClient(realtimeClient);


Demo Only
Copied!

A ClientOptions object may be passed to the Pub/Sub SDK instance to further customize the connection, however at a minimum you must set an API key and provide a clientId to ensure that the client is identified.

Additional options can also be passed to the Chat client to customize the following properties:

Property Description
logHandler The function to call for each line of log output. The default is console.log.
logLevel The verbosity of the log output. Options are; trace, debug, info, warn, error or silent. The default is error.

Logging

Copied!

Set the logHandler and logLevel properties when instantiating a client to configure your log handler:

Select...

const ably = new Ably.Realtime({ key: '<loading API key, please wait>', clientId: '<clientId>'});
const chatClient = new ChatClient(ably, {logHandler: logWriteFunc, logLevel: 'debug' });


Demo Only
Copied!

The logHandler property is your own function that will be called for each line of log output generated by the Chat SDK.

The logLevel sets the verbosity of logs that will be output by the SDK. The following log levels are available to set:

Level Description
trace Something routine and expected has occurred. This level will provide logs for the vast majority of operations and function calls.
debug Development information, messages that are useful when trying to debug library behavior, but superfluous to normal operation.
info Informational messages. Operationally significant to the library but not out of the ordinary.
warn Anything that is not immediately an error, but could cause unexpected behavior in the future. For example, passing an invalid value to an option. Indicates that some action should be taken to prevent future errors.
error A given operation has failed and cannot be automatically recovered. The error may threaten the continuity of operation.
silent No logging will be performed.
Authentication
v2.0