Persistent sessions

CloudSignal's persistent sessions queue messages for offline clients and restore subscriptions on reconnect.

Persistent sessions let CloudSignal remember a client's subscriptions and queue messages while it's offline. When the client reconnects, queued messages are delivered, useful for clients with intermittent connectivity, like mobile apps, agents that go idle, and remote devices.

How it works

When a client connects with clean_session=false (MQTT 3.1.1) or session_expiry_interval > 0 (MQTT 5.0):

Step	What happens
CloudSignal stores the session	Subscriptions and client state are saved
Messages are queued	While offline, messages matching subscriptions are held
Delivery on reconnect	Queued messages are delivered when the client reconnects
Session expires	After the configured expiry, the session and queued messages are deleted

Session lifecycle

Client

CloudSignal

Publisher

CONNECT clean_session=false, SUBSCRIBE agents/#

DISCONNECT (client goes offline)

PUBLISH agents/agent-01/state (queued)

CONNECT (reconnect with same clientId)

Deliver queued messages

Configuration

MQTT 3.1.1

Set clean_session to false when connecting:

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({
  preset: 'desktop',
  clientId: 'agent-01',
  clean: false, // Enable persistent session
});

await client.connectWithToken({ organizationId, externalToken });

MQTT 5.0

Use session_expiry_interval for finer control:

import CloudSignal from '@cloudsignal/mqtt-client';

const client = new CloudSignal({
  preset: 'desktop',
  clientId: 'agent-01',
  clean: false,
  properties: {
    sessionExpiryInterval: 3600, // Session expires 1 hour after disconnect
  },
});

await client.connectWithToken({ organizationId, externalToken });

The client ID is critical. The same client ID must be used on reconnect to restore the session. Use stable, unique identifiers like agent IDs or device serial numbers.

Queue limits

Message queues have size limits based on your plan.

Plan	Queue size
Free	100 messages
Pro	1,000 messages
Max	10,000 messages

When the queue is full, the oldest messages are dropped (FIFO).

Session expiry

Sessions are cleaned up after inactivity.

Plan	Session expiry
Free	1 hour
Pro	24 hours
Max	7 days

For longer session expiry or larger queues, contact us about Enterprise plans.

Best practices

Use stable client IDs

// Good: stable identifier
const clientId = `agent-${agentId}`;

// Bad: random ID, session can never be restored
const clientId = `agent-${Math.random()}`;

Handle the session-present flag

When connecting, check whether a previous session exists:

client.on('connect', (connack) => {
  if (connack.sessionPresent) {
    // Session restored, subscriptions still active
    console.log('Resumed previous session');
  } else {
    // New session, need to subscribe
    client.subscribe('agents/agent-01/inbox');
  }
});

Choose appropriate QoS

Persistent sessions only queue QoS 1 and QoS 2 messages.

QoS	Queued?	Notes
0	No	Fire and forget
1	Yes	Delivered at least once
2	Yes	Delivered exactly once

For messages that must arrive after reconnect, use QoS 1 or higher.

Use cases

Use case	Why persistent sessions help
Agents with idle periods	Commands sent during downtime are delivered when the agent reconnects
Mobile applications	Users don't miss notifications when switching networks or entering tunnels
Remote or edge clients	Buffered upstream messages aren't lost during cloud connectivity issues

Message retention - Store last-known-state
Quality of Service - QoS levels explained

On this page