Connections

When you instantiate a client, a realtime connection is established and maintained with Ably. You can interact with the connection using the ChatClient.connection object in order to monitor a client’s connection status.

Connection statuses

Copied!

A connection can have any of the following statuses:

Status	Description
initialized	A connection object has been initialized but not yet connected.
connecting	A connection attempt has been initiated, this status is entered as soon as the SDK has completed initialization, and is re-entered each time connection is re-attempted following disconnection.
connected	A connection exists and is active.
disconnected	A temporary failure condition when no current connection exists. The disconnected status is entered if an established connection is dropped, or if a connection attempt is unsuccessful.
suspended	A long term failure condition when no current connection exists because there is no network connectivity or available host. The suspended status is entered after a failed connection attempt if there has then been no connection for a period of two minutes. In the suspended status, an SDK will periodically attempt to open a new connection every 30 seconds. Rooms will be reattached on a successful reconnection, however message history will not be automatically recovered.
failed	This status is entered if the SDK encounters a failure condition that it cannot recover from. This may be a fatal connection error received from the Ably service, such as an attempt to connect with an incorrect API key, or some local terminal error, such as that the token in use has expired and the SDK does not have any way to renew it.

Use the current property to check which status a connection is currently in:

Select...

const connectionStatus = chatClient.connection.status.current;

Copy
Copied!

Hooks related to chat features, such as useMessages and useTyping, also return the current connectionStatus in their response.

Select...

import { useMessages } from '@ably/chat/react';


const MyComponent = () => {
  const { connectionStatus } = useMessages({
    listener: (message) => {
      console.log('Received message: ', message);
    },
  });


  return <div>Current connection status is: {connectionStatus}</div>;
};

Copy
Copied!

Use the connection.status.onChange() method to register a listener for status change updates:

Select...

const { off } = chatClient.connection.status.onStatusChange((change) => console.log(change));

Copy
Copied!

To remove the connection status listener, call the off() function returned in the subscribe() response:

Select...

off();

Copy
Copied!

Use the connection.status.offAll() method to remove all connection status listeners:

Select...

chatClient.connection.status.offAll();

Copy
Copied!

Handle connection discontinuity

Copied!

If a client briefly loses connection to Ably, for example when driving through a tunnel, the SDK will attempt to recover the connection. If the disruption lasts for less than 2 minutes, then on reconnection the SDK will automatically reattach to any rooms and replay any missed messages.

During periods of discontinuity greater than 2 minutes then you will need to take steps to recover any missed messages, such as by calling history.

Each feature of the Chat SDK provides an onDiscontinuity() handler to assist with this. These methods enable you to register a listener that will be notified when discontinuity occurs in that feature so that you can handle it, as needed.

For example, for messages:

Select...

const { off } = room.messages.onDiscontinuity((reason?: ErrorInfo) => {
  // Recover from the discontinuity
});

Copy
Copied!