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".
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>
This injects the support-request UI (a small floating dialog) and waits for the customer to start a 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.
persistentMetaData: { // 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?",
},
});
None of the fields are required — call startQwelpSession() with no arguments to use the
defaults.
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.",
},
});
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();
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.
Both features are on by default and need no extra code. Use sender/src!QwelpSettings to switch them off or restrict them per site.
When the problem is outside the browser, the support agent can ask to see the customer's entire screen. Before anything is shared, the customer sees a consent dialog. It explains that the agent will see everything on the chosen screen, including other programs and notifications. Only after the customer agrees does the browser's own screen picker open. Sharing a single window or browser tab is rejected, and the customer is asked to pick a whole screen. The customer can stop sharing at any time, and while sharing is active the agent sees the video instead of the page replica. The capture belongs to the current page, so leaving or reloading the page ends the share. Before that happens, the customer gets the browser's "leave site?" prompt.
Screen sharing needs:
getDisplayMedia (mobile browsers usually can't share the screen),display-capture Permissions Policy
feature. If the sender runs inside an iframe, add allow="display-capture" to it.If one of these is missing, the agent sees why screen sharing isn't available. Nothing is shown to the customer.
To never offer screen sharing on a site:
startQwelpSession({
screenSharing: false,
});
The customer and the agent can send files to each other during a session, for example a screenshot, a log file or a document. When the customer drags a file over the page, a drop card appears. Only drops on that card are taken; drops anywhere else reach your page as usual. The agent sends files from the support portal.
Configure it with fileTransfer: false turns it off, and a
sender/src!FileTransferSettings object controls each direction and the size limit:
startQwelpSession({
fileTransfer: {
toAgent: true, // the customer may send files to the agent (default: true)
toCustomer: false, // the agent may send files to the customer (default: true)
maxFileSize: 20 * 1024 * 1024, // largest file the customer accepts, in bytes (default: 100 MB)
},
});
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;
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.
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");
});
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
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();