Skip to main content

Swyx Web Extension SDK Documentation

Welcome to the Swyx Web Extension SDK documentation! This is the complete guide to using the TypeScript SDK for Swyx Web Extensions.

What is Swyx Web Extension SDK?​

The SDK provides typed APIs for building Web Extensions that integrate with SwyxIt!. It enables you to:

  • Control calls — Dial, hold, transfer, and manage active calls
  • Monitor presence — Track user availability and presence states
  • Access phonebook — Search and browse contact directories
  • Access call journal - Track call history
  • Handle events — React to real-time server-pushed notifications
Handle all SDK data as untrusted input

Caller names, numbers, phonebook entries and presence texts are controlled by other people — any external caller can choose their own display name. Display them with textContent or your framework's default text binding, never with innerHTML. Otherwise a single phone call can run attacker code inside your Web Extension.

Read Security: Handling SDK Data Safely before you display any SDK data.

Requirements​

  • A compatible Swyx server (version 15.00 or higher)
  • Basic knowledge of TypeScript/JavaScript

Key Concepts​

Connection Model​

The SDK uses a request/response + event model:

  • Requests flow from client to server via the main hub (IWebExtensionHub)
  • Events flow from server to client via the back-channel (IWebExtensionHubBack)
  • Both require an active IWebExtensionConnection

Public Surface​

  • Factory function CreateWebExtensionClient to create connection, hub, and event handler instances
  • Enums for states (CallState, UserState, LineState, etc.)
  • Type definitions for complex objects (UserPresence, LineDetails, etc.)

Next: Start with Getting Started to install and use the SDK, then continue with Configuration Reference for deployment setup.