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();

The constructor takes no parameters. It initializes an empty SWML document and installs dynamic verb methods from 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.

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());