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.

AgentBase extends SWMLService. The SWAIG tool registry and SWAIG hosting (the /swaig endpoint) live on SWMLService, so any service — including standalone SWAIG hosts and sidecars that do not emit an AI block — can register and dispatch tools. The SWAIG methods below are inherited by AgentBase.

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.

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.

SWAIG tool registry

defineTool

Define a SWAIG tool with a handler.

registerSwaigFunction

onFunctionCall

Dispatch a SWAIG function call to its handler.

getRegisteredTools

Get summaries of all registered tools.

getTool

Look up a registered SwaigFunction by name.

hasTool

Check whether a tool is registered.

hasFunction

Check whether a function is registered.

getFunction

Get a registered function entry by name.

getAllFunctions

Get all registered functions keyed by name.

removeFunction

Remove a registered function.

listToolNames

List registered tool names.

validateBasicAuth

Validate basic-auth credentials (constant-time).

Example

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