SWMLService | SignalWire

SWMLService is a lightweight HTTP service for serving non-AI SWML documents. Unlike AgentBase (which always produces an AI block), SWMLService generates pure SWML call-flow documents: IVR menus, voicemail, call recording, etc.

It uses a SwmlBuilder internally for verb construction and Hono for HTTP serving.

SWMLService generates and serves SWML documents over HTTP. See the SWML reference for the full document specification.

Constructor

opts

SWMLServiceOptionsRequired

Configuration object.

opts.name

stringRequired

Service display name used in logging and startup messages. Required to match the Python SDK, where name is a positional required parameter.

opts.route

stringDefaults to /

HTTP route path where the service is accessible.

opts.host

stringDefaults to 0.0.0.0

Host the HTTP server binds to.

opts.port

number

Port the HTTP server binds to. Defaults to the PORT environment variable, falling back to 3000.

opts.basicAuth

[string, string]

Basic auth credentials as [username, password]. Unlike AgentBase, SWMLService does not fall back to environment variables — credentials must be provided explicitly.

opts.schemaPath

string

Path to a JSON Schema file for verb validation.

opts.configFile

string

Path to a security configuration file for SSL, CORS, and host allowlist settings.

opts.schemaValidation

booleanDefaults to true

Enable schema validation. Can also be disabled via the SWML_SKIP_SCHEMA_VALIDATION=true environment variable.

Properties

name

string

Service display name.

route

string

HTTP route path where this service is accessible.

host

string

Host address the HTTP server binds to.

port

number

Port the HTTP server binds to.

log

Logger

Structured logger bound to this service name. Exposed for subclass access.

security

SecurityConfig

Unified security configuration loaded from environment variables and optional config file. Controls SSL, CORS, and host allowlist settings.

sslEnabled

boolean

Whether SSL/HTTPS is enabled. Mirrors security.sslEnabled.

sslCertPath

string | undefined

Path to the SSL certificate file.

sslKeyPath

string | undefined

Path to the SSL private key file.

domain

string | undefined

Domain name for SSL certificates.

schemaUtils

SchemaUtils

Schema validation utilities for SWML documents.

verbRegistry

VerbHandlerRegistry

Registry of custom verb handlers for specialized SWML verb processing.

Methods

addVerb

Add a SWML verb to the document.

addSection

Add a new named section to the document.

addVerbToSection

Add a verb to a specific named section.

resetDocument

Reset the document to an empty state.

renderSwml

Render the SWML document as an object.

getDocument

Get the SWML document as an object (Python-compat alias).

renderDocument

Render the SWML document as a JSON string.

setOnRequestCallback

Set a per-request callback for dynamic SWML generation.

onRequest

Subclass override hook for per-request SWML.

registerVerbHandler

registerRoutingCallback

extractSipUsername

Extract the username from a SIP URI (static).

getBasicAuthCredentials

Retrieve HTTP Basic Auth credentials.

manualSetProxyUrl

Manually set the proxy URL for webhook generation.

getApp

Get the Hono app for mounting or testing.

asRouter

Get the Hono app (Python-compat alias for getApp).

getBuilder

Get the underlying SwmlBuilder instance.

run

Start the HTTP server.

serve

Start the HTTP server (Python-compat alias for run).

stop

Stop the HTTP server.

Example

1 import { SWMLService } from '@signalwire/sdk';
2 
3 const service = new SWMLService({ name: 'my-ivr', route: '/' });
4 service.addVerb('answer', {});
5 service.addVerb('play', { url: 'https://example.com/greeting.mp3' });
6 service.addVerb('hangup', {});
7 
8 await service.run();