Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/strophe/strophejs/llms.txt

Use this file to discover all available pages before exploring further.

WebSocket transport implements RFC 7395 — An Extensible Messaging and Presence Protocol (XMPP) Subprotocol for WebSocket. It establishes a persistent, full-duplex connection between the browser and the XMPP server, replacing the HTTP polling loop used by BOSH with a single long-lived socket. Strophe.js activates the WebSocket transport automatically when the service URL begins with ws:// or wss://, or when the protocol option is set to 'ws' or 'wss'.

​
When to Use WebSocket

Use WebSocket when…

  • You need low-latency, real-time message delivery
  • Your server supports the XMPP-over-WebSocket subprotocol
  • Network infrastructure permits WebSocket upgrades
  • You want a persistent connection without HTTP polling overhead

Stick with BOSH when…

  • Corporate proxies or firewalls block WebSocket upgrades
  • You need BOSH session prebinding (attach())
  • Broad compatibility with older infrastructure is required

​
Connection URL Formats

Strophe.js supports both absolute and relative WebSocket URLs.

​
Absolute URL

Pass a fully-qualified ws:// or wss:// URL to bypass any auto-detection logic: 
// Secure WebSocket (recommended for production)
const connection = new Strophe.Connection('wss://xmpp.example.com/websocket');

// Plain WebSocket (development only)
const connection = new Strophe.Connection('ws://localhost:5280/xmpp-websocket');

​
Relative URL with protocol Option

If you omit the scheme and host, Strophe.js constructs the full URL by prepending ws:// or wss:// followed by location.host. Use the protocol option to choose the scheme. When protocol is 'wss' (or when the page is served over HTTPS), Strophe.js always uses wss:// to prevent downgrading security. 
const connection = new Strophe.Connection('/xmpp-websocket/', {
  protocol: 'wss',
});
// Resolves to: wss://current-hostname/xmpp-websocket/

​
Relative URL — Auto-Detection

If you provide a relative path without a protocol option, Strophe.js selects wss whenever the page is loaded over https: and falls back to ws for http: pages: 
const connection = new Strophe.Connection('/xmpp-websocket/');
// On https:// pages → wss://hostname/xmpp-websocket/
// On http:// pages  →  ws://hostname/xmpp-websocket/
Browsers block mixed-content upgrades. If your page is served over https://, a ws:// (non-secure) URL will be rejected. Always use wss:// in production. Strophe.js enforces this automatically for relative URLs, but a hardcoded ws:// absolute URL will still fail.

​
Setting Up a WebSocket Connection

1

Choose a URL

Decide between an absolute wss:// URL and a relative path. For most single-page applications a relative path like /xmpp-websocket/ is the simplest choice.
2

Create a Connection

Pass the URL to new Strophe.Connection(). Optionally set the protocol option for relative paths.
import { Strophe } from 'strophejs';

const connection = new Strophe.Connection('/xmpp-websocket/', {
  protocol: 'wss',
});
3

Connect

Call connection.connect() with your JID, password, and a status callback.
connection.connect('user@example.com', 'password', (status, condition) => {
  switch (status) {
    case Strophe.Status.CONNECTING:
      console.log('Opening WebSocket…');
      break;
    case Strophe.Status.CONNECTED:
      console.log('Connected via WebSocket as', connection.jid);
      break;
    case Strophe.Status.CONNFAIL:
      console.error('WebSocket connection failed:', condition);
      break;
    case Strophe.Status.DISCONNECTED:
      console.log('Disconnected.');
      break;
  }
});
4

Send and Receive Stanzas

Once connected, use the normal Strophe.js API: connection.send(), connection.addHandler(), connection.sendIQ(), etc. The WebSocket transport is transparent — the API is identical to BOSH.

​
Code Examples

import { Strophe } from 'strophejs';

const connection = new Strophe.Connection('wss://xmpp.example.com/websocket');

connection.connect('alice@example.com', 's3cr3t', (status) => {
  if (status === Strophe.Status.CONNECTED) {
    console.log('Connected!');
  }
});

​
Node.js: Installing the ws Peer Dependency

The browser’s native WebSocket global is not available in Node.js. When using Strophe.js outside a browser environment, install the ws package: 
npm install ws
Then pass the WebSocket implementation to the global scope before importing Strophe.js: 
import WebSocket from 'ws';
(global as any).WebSocket = WebSocket;

import { Strophe } from 'strophejs';

const connection = new Strophe.Connection('wss://xmpp.example.com/websocket');

​
WebSocket Stream Framing

The Websocket class sets strip = 'wrapper'. Unlike BOSH — which wraps stanzas in a <body> element — the WebSocket transport does not add an outer wrapper to stanzas delivered to xmlInput/xmlOutput. Each individual XMPP stanza is passed directly. Internally, Strophe.js wraps received messages in a <wrapper> element during parsing to allow multi-stanza frames, but that wrapper is stripped before your callbacks are invoked. When the connection opens, Strophe.js sends an XMPP framing <open> element (RFC 7395 §3.4) and expects the server to respond in kind before proceeding to SASL authentication: 
<!-- Sent by client -->
<open xmlns="urn:ietf:params:xml:ns:xmpp-framing"
      to="example.com"
      version="1.0"/>

<!-- Sent by server -->
<open xmlns="urn:ietf:params:xml:ns:xmpp-framing"
      from="example.com"
      id="session-id"
      version="1.0"/>
This framing differs from BOSH’s <body> wrapper, so xmlInput/xmlOutput callbacks will receive unwrapped stanzas when using WebSocket.
Due to browser XML-parser limitations, the opening and closing <stream> tags for WebSocket connections are passed to xmlInput as self-closing elements. This is expected behaviour and does not affect functionality.

Build docs developers (and LLMs) love

Get started for freeTalk to us