Getting Started

QWELP lets a support agent co-browse your web app with a customer: it captures DOM state and input events in the customer's browser and streams them to the agent over WebRTC. Everything below happens on the customer-facing side of that connection — the "sender".

1. Load the sender script

Add the sender as a module import on any page you want to support. There is nothing to install; the script is loaded directly from the CDN.

<script type="module">
  import { startQwelpSession } from "https://js.qwelp.dev/current/index.js";

  startQwelpSession();
</script>
Copy

This injects the support-request UI (a small floating dialog) and waits for the customer to start a session.

2. Configure the session

sender/src!startQwelpSession takes an optional sender/src!QwelpSettings object:

startQwelpSession({
  customerKey: "base64...",  // the public ECDH key of your company, if you have a company account.
  metaData: {                // arbitrary key/value data attached to the session history, for analysis
    userId: "42",
    plan: "pro",
  },
  branding: {                 // add your branding, see step 3
    dialogTitle: "Need a hand?",
  },
});
Copy

None of the fields are required — call startQwelpSession() with no arguments to use the defaults.

3. Customize the look and feel

Pass a shared/src/QwelpBranding!QwelpBranding object to change colors, logo and copy across all sender dialogs:

startQwelpSession({
  branding: {
    primaryColor: "#0055ff",
    secondaryColor: "#222222",
    logoUrl: "https://example.com/logo.svg",
    dialogTitle: "Need a hand?",
    supportMessage: "Our team can see your screen and help you right now.",
  },
});
Copy

4. Multi-page (non-SPA) sites

If your app is a classic multi-page site rather than an SPA, a running session would otherwise be lost on navigation. Call sender/src!checkQwelpSessionAutoStart once on every page load, alongside startQwelpSession, to resume a session that was already active on the previous page:

import { startQwelpSession, checkQwelpSessionAutoStart } from "https://js.qwelp.dev/current/index.js";

checkQwelpSessionAutoStart();
Copy

It is a no-op unless a session was already running, so it is safe to call on every page. Provide the SessionSettings if there are any.

5. Advanced: reacting to the session

For most integrations, startQwelpSession is all you need. If you want to react to session lifecycle events (for example to show your own UI while support is active), the running session is available as QwelpSenderSession.runningSession — see the sender/src!QwelpSenderSession class reference for its events and methods.

import { QwelpSenderSession } from "https://js.qwelp.dev/current/index.js";

const session = QwelpSenderSession.runningSession;
Copy

runningSession is only set once sender/src!startQwelpSession or sender/src!checkQwelpSessionAutoStart has actually started a session, so guard against undefined if your code can run before that happens.

Listening for events

sender/src!QwelpSenderSession implements an addEventListener / removeEventListener pair for the following events:

Event	Payload	Fired when
start	undefined	The session starts (or resumes after a page navigation).
stop	undefined	The session is stopped, either by the customer or the agent.
reconnect	undefined	The session resumes on a new page during multi-page navigation.
connected	{ connected: boolean }	The WebRTC data channel to the agent opens or closes.
status	SessionStateInfo	The internal connection state machine changes (signalling, connecting, connected, ...).
signallerState	{ connected: boolean, code: string }	The signalling server connection toggles.

const session = QwelpSenderSession.runningSession;

session.addEventListener("connected", ({ connected }) => {
  document.body.classList.toggle("support-active", connected);
});

session.addEventListener("status", (info) => {
  console.log(`Session status: ${info.state} (${info.message})`);
});

session.addEventListener("stop", () => {
  document.body.classList.remove("support-active");
});
Copy

Reading session info

const session = QwelpSenderSession.runningSession;

session.getSupportCode();     // the code the customer reads out to the agent
session.getState();           // current SessionStateInfo, e.g. { state: "Connected", message: "" }
session.getSupportDuration(); // how long the data channel has been open, in ms
Copy

Stopping a session programmatically

Calling sender/src!QwelpSenderSession stop() ends the session and closes the WebRTC connection, the same as the customer closing the support dialog:

QwelpSenderSession.runningSession?.stop();
Copy

Where to go next

• sender/src!startQwelpSession — full parameter reference
• sender/src!QwelpSettings — all session options
• shared/src/QwelpBranding!QwelpBranding — all branding options
• sender/src!QwelpSenderSession — the session object and its events