Strophe.js ConnectionOptions — Configuration Reference

ConnectionOptions is the configuration interface accepted as the second argument to new Strophe.Connection(service, options). Every field is optional; omitting the entire object produces sensible defaults. Options that are transport-specific (BOSH-only or WebSocket-only) are clearly marked below.

All Options

A map of cookie names to cookie descriptor objects to be included in every HTTP request made by Strophe. Applies to both BOSH and WebSocket transports.Each cookie descriptor has the following shape:

type Cookies = Record<string, {
  value:   string;
  domain?: string;
  path?:   string;
  expires?: Date;
}>;

Browser security restrictions prevent Strophe from setting cookies for domains other than the one serving the page. Cross-domain cookies must be set server-side (e.g. via a pre-flight XHR to the target domain).

const conn = new Strophe.Connection("/http-bind/", {
  cookies: {
    authToken: {
      value:   "eyJhbGci...",
      domain:  ".example.com",
      path:    "/",
      expires: new Date("2025-12-31"),
    },
  },
});

mechanisms

(new (...args: any[]) => SASLMechanism)[]

An array of SASL mechanism constructor functions that this connection will offer during authentication. When omitted, Strophe registers all built-in mechanisms with the following default priorities (higher = preferred):

Mechanism	Priority
`SCRAM-SHA-512`	72
`SCRAM-SHA-384`	71
`SCRAM-SHA-256`	70
`SCRAM-SHA-1`	60
`PLAIN`	50
`OAUTHBEARER`	40
`X-OAUTH2`	30
`ANONYMOUS`	20
`EXTERNAL`	10

Pass a subset (or a custom mechanism) to restrict what the client advertises.

Restricting mechanisms to only SCRAM variants (SASLSHA256, SASLSHA512) prevents the client from falling back to PLAIN over non-TLS connections.

import { SASLSHA256, SASLSHA512 } from "strophejs";

const conn = new Strophe.Connection("/http-bind/", {
  mechanisms: [SASLSHA256, SASLSHA512],
});

explicitResourceBinding

boolean

When true, Strophe will not automatically bind a JID resource after authentication. Instead it fires Strophe.Status.BINDREQUIRED via the connect callback, giving you a chance to perform other stream-level setup (such as enabling XEP-0198 Stream Management) before calling connection.bind() manually.Defaults to false (automatic resource binding).

const conn = new Strophe.Connection("/http-bind/", {
  explicitResourceBinding: true,
});

conn.connect("alice@example.com", "pass", (status) => {
  if (status === Strophe.Status.BINDREQUIRED) {
    // Negotiate XEP-0198 first, then bind
    setupStreamManagement(conn);
    conn.bind();
  }
});

protocol

'ws' | 'wss'

WebSocket connections only.Forces WebSocket transport for relative service URLs. Without this option, a relative URL (e.g. "/xmpp-websocket/") is treated as a BOSH endpoint. Set to "ws" for plain WebSocket or "wss" for Secure WebSocket.

Browsers will automatically upgrade "ws" to "wss" when the current page is served over HTTPS, because downgrading security is not permitted. Absolute WebSocket URLs (ws://… / wss://…) are detected automatically and do not require this option.

// Connect to wss://CURRENT_HOST/xmpp-websocket/
const conn = new Strophe.Connection("/xmpp-websocket/", {
  protocol: "wss",
});

worker

string

WebSocket connections only.URL pointing to the shared worker script (src/shared-connection-worker.js or its compiled equivalent). When set, Strophe uses a SharedWorker to host a single WebSocket connection that can be shared across multiple tabs or Connection instances in the same browser session.

const conn = new Strophe.Connection("wss://xmpp.example.com/ws/", {
  worker: "/static/js/strophe-shared-worker.js",
});

Using a shared worker means that only one WebSocket handshake is made even when the user has several browser tabs open on the same application, significantly reducing server-side connection overhead.

sync

boolean

BOSH connections only.When true, BOSH HTTP requests are made synchronously (blocking the main thread). The default is false (asynchronous). You can also toggle this on an already-established connection:

conn.options.sync = true;

Synchronous XHR on the main thread is deprecated by browsers and will block all JavaScript execution until the request completes. Use this only in server-side or worker environments, never in production browser UIs.

const conn = new Strophe.Connection("/http-bind/", { sync: true });

customHeaders

string[]

BOSH connections only.An array of extra HTTP header strings to append to every BOSH request. Useful for passing authentication tokens or other metadata to a custom BOSH connection manager.

const conn = new Strophe.Connection("/http-bind/", {
  customHeaders: [
    "X-App-Version: 2.1.0",
    "X-Request-ID: abc123",
  ],
});

keepalive

boolean

BOSH connections only.When true, Strophe caches the BOSH session tokens (rid and sid) in sessionStorage after every request. If the page is reloaded, calling connection.restore() instead of connect() will attempt to resume the cached session transparently.Defaults to false.

const conn = new Strophe.Connection("/http-bind/", { keepalive: true });

conn.connect("alice@example.com", "pass", onConnect);

// On a subsequent page load, attempt to restore before prompting for login:
conn.restore("alice@example.com", (status) => {
  if (status === Strophe.Status.CONNFAIL) {
    conn.connect("alice@example.com", password, onConnect);
  }
});

withCredentials

boolean

BOSH connections only.When true, the withCredentials flag is set on every BOSH XMLHttpRequest, causing the browser to include cookies and HTTP authentication headers in cross-origin requests.Defaults to false.

For cross-origin requests with withCredentials: true, the BOSH server must respond with Access-Control-Allow-Credentials: true and must set Access-Control-Allow-Origin to the exact page origin (not *). Most same-origin deployments do not need this option.

const conn = new Strophe.Connection("https://xmpp.otherdomain.com/http-bind/", {
  withCredentials: true,
});

contentType

string

BOSH connections only.Overrides the default Content-Type header value sent with BOSH HTTP requests. The default is "text/xml; charset=utf-8".Changing this to a simple content type (e.g. "text/plain") can eliminate CORS preflight (OPTIONS) requests on cross-origin BOSH endpoints, because simple content types do not trigger preflights.

const conn = new Strophe.Connection("https://xmpp.example.com/http-bind/", {
  contentType: "text/plain",
});

Common Option Combinations

Secure WebSocket
BOSH with keepalive
Multi-tab WebSocket
Explicit resource binding
Cross-origin BOSH

// Absolute WSS URL — no extra options needed
const conn = new Strophe.Connection(
  "wss://xmpp.example.com/xmpp-websocket/",
  {
    mechanisms: [SASLSHA256, SASLSHA512], // strong SASL only
  }
);

// Survive page reloads without re-authenticating
const conn = new Strophe.Connection("/http-bind/", {
  keepalive: true,
});

function init() {
  conn.restore(undefined, (status) => {
    if (status === Strophe.Status.CONNECTED) {
      onConnected();
    } else if (status === Strophe.Status.CONNFAIL) {
      conn.connect(jid, password, onConnect);
    }
  });
}

// Share one WebSocket across browser tabs via a SharedWorker
const conn = new Strophe.Connection(
  "wss://xmpp.example.com/ws/",
  {
    worker: "/static/strophe-worker.js",
  }
);

// Defer resource binding to set up XEP-0198 first
const conn = new Strophe.Connection("/http-bind/", {
  explicitResourceBinding: true,
});

conn.connect("alice@example.com", password, (status) => {
  if (status === Strophe.Status.BINDREQUIRED) {
    enableStreamManagement(conn); // XEP-0198
    conn.bind();
  } else if (status === Strophe.Status.CONNECTED) {
    onConnected();
  }
});

// BOSH on a different origin with cookie credentials
const conn = new Strophe.Connection(
  "https://xmpp.otherdomain.com/http-bind/",
  {
    withCredentials: true,
    contentType: "text/plain", // avoid OPTIONS preflight
  }
);

Connection

Stanza Building

SASL Mechanisms

Utilities & Constants

Strophe.js ConnectionOptions — Configuration Reference

All Options

Common Option Combinations

Build docs developers (and LLMs) love

Connection

Stanza Building

SASL Mechanisms

Utilities & Constants

Documentation Index

​All Options

​Common Option Combinations

Build docs developers (and LLMs) love

All Options

Common Option Combinations