AblyDocs

Chat SDK setup

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

Authentication

Chat requires an authenticated client with a clientId to identify users. The recommended approach is:

  1. Client-side apps (browsers, iOS, Android): Use JWT authentication with authCallback to fetch JWTs from your server
  2. Server-side apps (Node.js, Python, etc.): Use your API key directly

Sign up to Ably to create an API key in the dashboard or use the Control API to create an API key programmatically. Your server will use this key to issue tokens to clients.

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:

FeatureCapabilities
Send messagespublish
Receive messagessubscribe
Update messagemessage-update-any or message-update-own
Delete messagemessage-delete-any or message-delete-own
Message historysubscribe, history
Message reactionsannotation-publish, optionally annotation-subscribe
Presencesubscribe, presence
Room occupancysubscribe, channel-metadata
Typing indicatorspublish, subscribe
Room reactionspublish, subscribe

When setting the capabilities for Chat, you can apply them to specific chat rooms, a group of chat rooms in a common namespace, or all chat rooms:

  • my-chat-room - a specific room
  • dms:* - all rooms in the dms: namespace
  • * - all chat rooms

For more guidance, see the capabilities documentation and Chat authentication for room-scoped examples.

Client identification

Every Chat client must have a clientId - this is a hard requirement. The Chat SDK uses the clientId to identify who sends messages, who is present in a room, and who is typing.

Your auth server sets the clientId when creating tokens. This ensures users can't impersonate each other - the identity is controlled server-side, not by the client.

If you try to connect without a clientId, the connection will fail.

User claims

User claims enable you to attach server-signed metadata to a user's authentication token that is automatically included on all events they produce in a chat room. This metadata is set server-side via JWT claims and cannot be modified by clients, making it suitable for trusted information such as display names, roles, or custom attributes.

User claims are scoped to individual chat rooms using the ably.room.<roomName> key in the JWT payload. The value is an arbitrary string, commonly a JSON-encoded object. When a user publishes a message, enters presence, sends a typing indicator, or sends a reaction in a matching room, the claim is automatically copied by Ably servers into the userClaim field of the event.

Set user claims in your JWT

Include an ably.room.<roomName> key in your JWT claims when generating tokens on your server:

JavaScript

1

2

3

4

5

6

7

const claims = {
  'x-ably-capability': JSON.stringify({ '*': ['*'] }),
  'x-ably-clientId': 'user-123',
  'ably.room.my-chat-room': JSON.stringify({ display_name: 'Alice', role: 'moderator' }),
  iat: Math.floor(Date.now() / 1000),
  exp: Math.floor(Date.now() / 1000) + 3600,
};

You can also use wildcard patterns to apply claims across multiple rooms:

PatternDescription
ably.room.my-chat-roomApplies to the my-chat-room room only.
ably.room.support:*Applies to all rooms in the support namespace.
ably.room.*Applies to all rooms.

When multiple patterns match a room, the most specific claim is used.

Read user claims from events

The userClaim field is available on messages, presence members, typing events, room reactions, and message reactions. For example, to read the claim from a message:

1

2

3

4

5

6

7

room.messages.subscribe((event) => {
  const { userClaim } = event.message;
  if (userClaim) {
    const parsed = JSON.parse(userClaim);
    console.log(`Message from ${parsed.display_name} (${parsed.role})`);
  }
});

Install

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

NPM