Skip to main content

Getting Started

This guide walks you through installing the SDK for Swyx Web Extensions and making your first API call.

Handle all SDK data as untrusted input

Every name, number and text the SDK delivers — from calls, the call journal, the phonebook and presence — can be chosen by someone else, for example by any external caller. Always display it as text:

element.textContent = line.peerName; // ✅ safe
element.innerHTML = line.peerName; // ❌ runs attacker code

See Security: Handling SDK Data Safely for details and a checklist.

Installation​

Prerequisites​

  • npm or yarn package manager
  • A Swyx Web Extension environment

Via npm/yarn​

npm install @enreachde/swyx-web-extension-sdk
# or
yarn add @enreachde/swyx-web-extension-sdk

Quickstart​

Here's a minimal example to connect and retrieve the logged-in user:

import {
CreateWebExtensionClient,
ConnectionEvent,
ConnectionReason,
ConsoleLogger,
} from '@enreachde/swyx-web-extension-sdk';

// Step 1: Create and wire all core SDK components
const client = CreateWebExtensionClient();
const { connection, hub, hubBack } = client;
const logger = new ConsoleLogger();

// Step 2: Listen to connection state changes
hubBack.onConnectionStateChanged((event: ConnectionEvent, reason: ConnectionReason) => {
logger.info('HubBack', 'onConnectionStateChanged', `Connection state changed: ${event}, ${reason}`);
});

// Step 3: Connect to the server
await connection.Connect();

// Step 4: Call an API method
const user = await hub.GetLoggedInUser();
logger.info('Hub', 'GetLoggedInUser', `Logged in user: ${user.userName}`);

// Step 5: Clean up when done
await connection.Disconnect(ConnectionReason.Shuttingdown, true);

Web Extension Configuration File​

Start from sample-configuration.typical.json as a practical base and adapt it to your environment. The final configuration.json must be uploaded to the Swyx server via Swyx Control Center for deployment.

See Configuration Reference for complete field definitions, constraints, and examples.

Core Components​

SDK Factory​

Create and wire connection, request hub, and event hub with one call:

const client = CreateWebExtensionClient();
const { connection, hub, hubBack } = client;

Hub (Request/Response)​

The main hub is used to call server methods:

const user = await hub.GetLoggedInUser();
const language = await hub.GetLanguage();

HubBack (Events)​

The back-channel hub subscribes to server-pushed notifications:

const logger = new ConsoleLogger();

hubBack.onLineStateChanged((lineIndex, lineState) => {
logger.info('HubBack', 'onLineStateChanged', `Line state changed: ${lineIndex}, ${lineState}`);
});

Connection​

The connection manages the underlying transport:

await connection.Connect();

// ... use hub methods ...

await connection.Disconnect(ConnectionReason.Shuttingdown, true);

Common Tasks​

Get User Information​

// Get the logged-in user
const user = await hub.GetLoggedInUser();

// Get UI language
const language = await hub.GetLanguage();

// Get groups assigned to the user
const groups = await hub.GetUserGroups();

Monitor Call State​

const logger = new ConsoleLogger();

// Subscribe to line state changes
hubBack.onLineStateChanged((lineIndex, lineState) => {
logger.info('HubBack', 'onLineStateChanged', `Line ${lineIndex} state: ${lineState}`);
});

// Subscribe to line selection changes
hubBack.onLineSelectionChanged((lineIndex) => {
logger.info('HubBack', 'onLineSelectionChanged', `Selected line: ${lineIndex}`);
});

Control Calls​

await hub.Dial(0, '+491701234567');
await hub.HoldCall(0);
await hub.ActivateCall(0);

Handle Events​

The SDK provides rich event subscriptions for presence, call state, and more:

warning

Event payloads carry values entered by other people — for example statusText of a presence or peerName of a notification call. Render them with textContent, never with innerHTML. See Security.

const logger = new ConsoleLogger();

hubBack.onUserPresenceChanged((presence) => {
logger.info('HubBack', 'onUserPresenceChanged', `User presence updated: ${presence.userId}, ${presence.presenceStatus}`);
});

hubBack.onNotificationCallsChanged((notificationCalls) => {
logger.info('HubBack', 'onNotificationCallsChanged', `Notification calls count: ${notificationCalls.length}`);
});

Error Handling​

The SDK throws exceptions for connection errors and API failures. Wrap calls in try/catch:

const logger = new ConsoleLogger();

try {
const user = await hub.GetLoggedInUser();
} catch (error) {
logger.error('Hub', 'GetLoggedInUser', `Failed to get user: ${String(error)}`);
}

Connection state can be monitored via the HubBack:

const logger = new ConsoleLogger();

hubBack.onConnectionStateChanged((event, reason) => {
if (event === ConnectionEvent.Disconnected) {
logger.info('HubBack', 'onConnectionStateChanged', `Disconnected! Reason: ${reason}`);
}
});

Enabling DevTools​

During development, you can enable the Chromium DevTools for the Web Extension iframe in SwyxIt!.

Open settings.json at:

%LocalAppData%\Programs\SwyxIt!\settings.json

Add the following configuration:

{
"traceSettings": {
"traceLevel": "notice"
},
"developerMode": {
"enableDevTools": true,
"openDevToolsOnStart": true
}
}
FieldRequiredDescription
traceSettings.traceLevelYesSets the trace level for SwyxIt! tracing
developerMode.enableDevToolsYesEnables DevTools for the Web Extension
developerMode.openDevToolsOnStartNoIf true, DevTools opens automatically on app start. If omitted or false, open it manually via Settings → App Information → Open DevTools

Next Steps​