Connecting a Realtime Client

This page covers Realtime V2. Legacy Realtime uses a different connection route and protocol; see Realtime (Legacy).

Prerequisites

A realtime server, such as chat from Servers & Channels. This guide creates a separate demo channel on it.
The server’s canonical, copied from its settings or pulled XanoScript. Script references use the server name; the client URL uses the canonical.
An instance with the V2 WebSocket service and /ws/ route enabled.
An application user JWT only if you configure the demo channel or handler to require authentication.

Connection address

wss://{instance-host}/ws/{server-canonical}

wss://x8ki-letl-twmt.n7.xano.io/ws/67Dx5RNL

The example address is illustrative; use your own instance and preserved server canonical. /ws/ targets V2. /rt/ targets legacy Realtime.

Create a demo channel

Create this channel on the chat server. It allows anonymous test clients and uses at_most_once delivery:

XanoScript

channel "demo/{room_id}" {
  realtime_server = "chat"
  access = {anonymous: true, presence: false}
  publish = {who: "anyone", direct: false}
  delivery = {guarantee: "at_most_once", per_recipient: false}
  input {
    int room_id
  }
}

The minimal client below does not implement acknowledgement or replay handling for at_least_once. Use this demo channel instead of pointing it at a channel configured for durable delivery. For application use, choose access rules appropriate to your users.

Create an echo handler

Create this message on the chat server’s demo/{room_id} channel:

XanoScript

message echo {
  realtime_server = "chat"
  channel = "demo/{room_id}"
  deliver_to = "sender"
  input {
    text body
  }
  stack {
    realtime.get_session as $session
  }
  response = {body: $input.body, session: $session}
}

The response goes only to the invoking client. Changing deliver_to to channel broadcasts the response to the subscribed clients; others excludes the sender.

Connect and join

Save this module as socket.js. It sends a join request after opening, retries only the initial Connection is not ready error, and resolves ready only after the join acknowledgement. Other errors are surfaced rather than retried indefinitely.

socket.js

// Native Realtime V2 protocol. Shared by the demo and the live verification.
export function connectClient({url, channel, token, onFrame = () => {}, onState = () => {}}) {
  const socket = token ? new WebSocket(url, [token]) : new WebSocket(url);
  let joined = false, attempts = 0, retry, heartbeat, deadline;
  let resolveReady, rejectReady;
  const ready = new Promise((resolve, reject) => { resolveReady = resolve; rejectReady = reject; });
  const send = frame => {
    if (socket.readyState !== WebSocket.OPEN) throw new Error('Socket is not open');
    socket.send(JSON.stringify(frame));
  };
  const clear = () => { clearTimeout(retry); clearTimeout(deadline); clearInterval(heartbeat); };
  const join = () => {
    if (socket.readyState !== WebSocket.OPEN || joined) return;
    attempts++;
    send({action: 'join', channel});
  };
  deadline = setTimeout(() => {
    rejectReady(new Error('Timed out joining the V2 channel'));
    clear(); socket.close();
  }, 10000);
  socket.addEventListener('open', () => { onState('Joining'); join(); });
  socket.addEventListener('message', event => {
    let frame;
    try { frame = JSON.parse(event.data); } catch { return; }
    onFrame(frame);
    if (!joined && frame.action === 'error') {
      if (frame.payload?.message === 'Connection is not ready' && attempts < 10) {
        clearTimeout(retry); retry = setTimeout(join, 250);
      } else {
        rejectReady(new Error(frame.payload?.message || 'Join refused'));
        clear(); socket.close();
      }
    }
    if (frame.action === 'join' && frame.channel === channel && frame.payload?.joined) {
      joined = true; clearTimeout(retry); clearTimeout(deadline);
      heartbeat = setInterval(() => { if (socket.readyState === WebSocket.OPEN) send({action:'ping'}); }, 20000);
      onState('Joined'); resolveReady(frame);
    }
  });
  socket.addEventListener('error', () => {
    rejectReady(new Error('WebSocket connection failed. Check the V2 /ws/ route and server canonical.'));
  });
  socket.addEventListener('close', event => {
    clear(); joined = false; onState('Offline');
    rejectReady(new Error(`Connection closed (${event.code})`));
  });
  return {
    ready, socket,
    get joined() { return joined; },
    broadcast(type, payload) {
      if (!joined) throw new Error('Join the channel before publishing');
      send({action: 'broadcast', channel, type, payload});
    },
    send,
    close() { clear(); socket.close(); }
  };
}

Import it from your frontend module and substitute your own connection address:

import {connectClient} from "./socket.js";

const client = connectClient({
  url: "wss://x8ki-letl-twmt.n7.xano.io/ws/67Dx5RNL",
  channel: "demo/42",
  onFrame(frame) {
    if (frame.action === "message") {
      console.log(frame.type, frame.payload);
    } else if (frame.action === "error") {
      console.error(frame.payload?.message);
    }
  }
});

try {
  await client.ready;
  client.broadcast("echo", {body: "Hello from the client"});
} catch (error) {
  client.close();
  console.error(error);
}

window.addEventListener("pagehide", () => client.close());

The demo channel allows anonymous access, so this call omits token. For an authenticated channel, add token: userJwt to the options using a token obtained from your application login flow. For a component-based application, also call client.close() during component teardown. The echo arrives as action: "message", type: "echo", with the body and session in payload. A socket’s open event alone is not a join acknowledgement, and a broadcast receipt is not a delivered message.

Wire frames

{"action":"join","channel":"demo/42"}

{"action":"join","channel":"demo/42","payload":{"joined":true,"params":{"room_id":"42"}}}

{"action":"broadcast","channel":"demo/42","type":"echo","payload":{"body":"Hello from the client"}}

The invocation’s type selects the named message handler; payload supplies its inputs. Use the resolved channel path (demo/42), not the declaration template (demo/{room_id}). Keep type at the top level of the frame.

Authentication

The module passes an application user JWT as the WebSocket subprotocol, equivalent to:

const socket = new WebSocket(url, [userJwt]);

This is a user token from an auth-enabled table, not an administrative Metadata API token. Never put the CLI’s administrative token in frontend code. Message-level authentication and channel join authorization are described in Access Control.

Verify delivery

Open two independent clients and wait for both join acknowledgements.
Invoke a message with deliver_to = "channel"; verify that both clients receive its response.
Invoke the echo handler above; verify that only its sender receives it.
Publish from an API using realtime.publish and verify the incoming message frames on the subscribed clients.

Do not treat a successful import, an HTTP publish response, or a broadcast receipt as proof that a recipient received a message.

Troubleshooting

Symptom	Check
WebSocket upgrade returns HTML instead of HTTP 101	Confirm the instance has the V2 service and `/ws/` route enabled. Importing V2 XanoScript alone does not provision a working socket route.
`Unknown connection hash`	Check the server canonical. A later push that omits it can regenerate the address; pull and preserve it.
`Connection is not ready` immediately after open	Retry the join with a bounded deadline, as the module does. Wait for its acknowledgement before sending messages.
Join is refused	Check the resolved path, channel access settings, token, and join trigger decision. Surface `payload.message` from the error frame.
A path parameter is text instead of a number	Join acknowledgement and session `params` can contain strings despite the declared input type. Validate or convert before numeric use.

Build

Test & Deploy

Team Collaboration

Integrations

Security

Tutorials

Enterprise

Agencies

Account and Settings

Legal

Prerequisites

Connection address

Create a demo channel

Create an echo handler

Connect and join

Wire frames

Authentication

Verify delivery

Troubleshooting

Next steps

Messages

Realtime Triggers

​Prerequisites

​Connection address

​Create a demo channel

​Create an echo handler

​Connect and join

​Wire frames

​Authentication

​Verify delivery

​Troubleshooting

​Next steps

Messages

Realtime Triggers

Prerequisites

Connection address

Create a demo channel

Create an echo handler

Connect and join

Wire frames

Authentication

Verify delivery

Troubleshooting

Next steps