Getting Started
This guide walks you through installing the SDK for Swyx Web Extensions and making your first API call.
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:
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
}
}
| Field | Required | Description |
|---|---|---|
traceSettings.traceLevel | Yes | Sets the trace level for SwyxIt! tracing |
developerMode.enableDevTools | Yes | Enables DevTools for the Web Extension |
developerMode.openDevToolsOnStart | No | If true, DevTools opens automatically on app start. If omitted or false, open it manually via Settings → App Information → Open DevTools |
Next Steps
- Explore the API Reference for all available methods and types
- Read the Architecture guide for design details
- Check Compatibility for version requirements
- Read Configuration Reference for deployment and
configuration.jsonguidance