SwmlBuilder | SignalWire

SwmlBuilder provides a fluent interface for constructing SWML documents by chaining verb method calls. It produces documents of the form { version: "1.0.0", sections: { main: [...verbs] } }. Use SwmlBuilder when you want concise, readable document construction in a single expression.

In addition to the explicitly defined methods below, SwmlBuilder automatically generates methods for every SWML verb in the bundled schema (e.g., connect(), record(), denoise(), goto()). These dynamic methods accept an optional config?: Record<string, unknown> parameter and return this for chaining.

SwmlBuilder constructs SWML documents programmatically. See the SWML reference for the full specification of all supported verbs.

Constructor

1 const builder = new SwmlBuilder(opts?);

Initializes an empty SWML document and installs dynamic verb methods from the bundled schema. All constructor options are optional.

SwmlBuilderOptions

initialDocument

{ version?: string; sections?: Record<string, unknown[]> }

Seed the builder with an existing document instead of creating an empty one. Enables document injection — mirrors the Python SDK’s SWMLService injection pattern.

enableValidation

boolean

Explicit override for verb schema validation. Defaults to true unless SWML_SKIP_SCHEMA_VALIDATION=true is set in the environment.

schemaPath

string

Path to a custom SWML schema JSON file. When set, the builder uses a per-instance SchemaUtils loaded from this path instead of the bundled schema.

Dynamic Verb Methods

SwmlBuilder auto-generates chaining methods for every verb defined in the SWML schema. These dynamic methods accept an optional config object matching the verb’s SWML parameters and return this for chaining.

Examples of dynamic verbs: connect(), record(), recordCall(), denoise(), transfer(), goto(), cond(), execute(), tap(), and many more.

1 import { SwmlBuilder } from '@signalwire/sdk';
2 
3 const builder = new SwmlBuilder();
4 builder.answer();
5 builder.play({ url: 'https://example.com/greeting.mp3' });
6 builder.hangup();
7 
8 console.log(builder.renderDocument());

The sleep verb is a special case — it accepts either a number (duration) directly or a config object:

1 import { SwmlBuilder } from '@signalwire/sdk';
2 
3 const builder = new SwmlBuilder();
4 builder.answer();
5 builder.sleep(2000);
6 builder.hangup();
7 
8 console.log(builder.renderDocument());

Methods

addVerb

Append a verb to the main section.

addVerbToSection

Append a verb to a named section.

Add an AI verb to start an AI-powered conversation.

answer

Add an answer verb to the SWML document.

getDocument

Return the raw SWML document object.

getSchemaUtils

Get the shared SchemaUtils singleton (static).

hangup

Add a hangup verb to end the current call.

play

Add a play verb to play audio or text-to-speech.

renderDocument

Serialize the SWML document to a JSON string.

reset

Reset the SWML document to an empty state.

addSection

Add a new named section to the document.

build

Build and return the document (Python-compat alias for getDocument).

render

Render the document as JSON (Python-compat alias for renderDocument).

document

Property-style read-only accessor for the underlying document.

setValidation

Enable or disable verb schema validation.

Examples

Basic IVR Flow

1 import { SwmlBuilder } from '@signalwire/sdk';
2 
3 const builder = new SwmlBuilder();
4 
5 const doc = builder
6   .answer()
7   .play({ url: 'https://example.com/welcome.mp3' })
8   .sleep(1000)
9   .hangup()
10   .getDocument();
11 
12 console.log(doc);

AI Agent with SWAIG

1 import { SwmlBuilder } from '@signalwire/sdk';
2 
3 const builder = new SwmlBuilder();
4 
5 builder
6   .answer()
7   .ai({
8     prompt: { text: 'You are a helpful customer service assistant.' },
9     post_prompt: 'Summarize what was discussed.',
10     post_prompt_url: 'https://example.com/post_prompt',
11     swaig: {
12       defaults: { web_hook_url: 'https://example.com/swaig' },
13       functions: [
14         {
15           function: 'check_order',
16           description: 'Check order status',
17           parameters: {
18             type: 'object',
19             properties: {
20               order_id: { type: 'string', description: 'The order ID' },
21             },
22             required: ['order_id'],
23           },
24         },
25       ],
26     },
27     hints: ['order', 'tracking', 'refund'],
28     params: { end_of_speech_timeout: 500 },
29   });
30 
31 console.log(builder.renderDocument());

Multi-Section Document

1 import { SwmlBuilder } from '@signalwire/sdk';
2 
3 const builder = new SwmlBuilder();
4 
5 // Add verbs to the default main section
6 builder.answer();
7 builder.play({ url: 'https://example.com/greeting.mp3' });
8 
9 // Add verbs to a named section
10 builder.addVerbToSection('goodbye', 'play', {
11   url: 'https://example.com/goodbye.mp3',
12 });
13 builder.addVerbToSection('goodbye', 'hangup', {});
14 
15 console.log(builder.renderDocument());