> Fetch clean Markdown by appending `.md` to any page URL under https://signalwire.com/docs or requesting it with the HTTP header `Accept: text/markdown`. The root index at https://signalwire.com/docs/llms.txt lists the available documentation indexes.

# SwmlBuilder

> Fluent builder API for constructing SWML documents with method chaining.

[swmlservice]: /docs/server-sdks/reference/typescript/agents/swml-service

[swml]: /docs/swml/reference/calling/ai

[swml-reference]: /docs/swml/reference/calling/ai

[addverb]: /docs/server-sdks/reference/typescript/agents/swml-builder/add-verb

[addverbtosection]: /docs/server-sdks/reference/typescript/agents/swml-builder/add-verb-to-section

[ai]: /docs/server-sdks/reference/typescript/agents/swml-builder/ai

[answer]: /docs/server-sdks/reference/typescript/agents/swml-builder/answer

[getschemautils]: /docs/server-sdks/reference/typescript/agents/swml-builder/get-schema-utils

[hangup]: /docs/server-sdks/reference/typescript/agents/swml-builder/hangup

[play]: /docs/server-sdks/reference/typescript/agents/swml-builder/play

[reset]: /docs/server-sdks/reference/typescript/agents/swml-builder/reset

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.

> **Info**
>
> SwmlBuilder constructs [SWML][swml] documents programmatically. See the
> [SWML reference][swml-reference] for the full specification of all supported verbs.

## **Constructor**

```typescript {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.

```typescript {3}
import { SwmlBuilder } from '@signalwire/sdk';

const builder = new SwmlBuilder();
builder.answer();
builder.play({ url: 'https://example.com/greeting.mp3' });
builder.hangup();

console.log(builder.render());
```

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

```typescript {5}
import { SwmlBuilder } from '@signalwire/sdk';

const builder = new SwmlBuilder();
builder.answer();
builder.sleep(2000);
builder.hangup();

console.log(builder.render());
```

## **Methods**

#### [addVerb](/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb)

Append a verb to the main section.

#### [addVerbToSection](/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb-to-section)

Append a verb to a named section.

#### [ai](/docs/server-sdks/reference/typescript/agents/swml-builder/ai)

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

#### [answer](/docs/server-sdks/reference/typescript/agents/swml-builder/answer)

Add an answer verb to the SWML document.

#### [getSchemaUtils](/docs/server-sdks/reference/typescript/agents/swml-builder/get-schema-utils)

Get the shared SchemaUtils singleton (static).

#### [hangup](/docs/server-sdks/reference/typescript/agents/swml-builder/hangup)

Add a hangup verb to end the current call.

#### [play](/docs/server-sdks/reference/typescript/agents/swml-builder/play)

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

#### [reset](/docs/server-sdks/reference/typescript/agents/swml-builder/reset)

Reset the SWML document to an empty state.

#### [addSection](/docs/server-sdks/reference/typescript/agents/swml-builder/add-section)

Add a new named section to the document.

#### [build](/docs/server-sdks/reference/typescript/agents/swml-builder/build)

Build and return the SWML document as an object.

#### [render](/docs/server-sdks/reference/typescript/agents/swml-builder/render)

Render the SWML document as a JSON string.

#### [document](/docs/server-sdks/reference/typescript/agents/swml-builder/document)

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

#### [setValidation](/docs/server-sdks/reference/typescript/agents/swml-builder/set-validation)

Enable or disable verb schema validation.

---

## **Examples**

### Basic IVR Flow

```typescript {5}
import { SwmlBuilder } from '@signalwire/sdk';

const builder = new SwmlBuilder();

const doc = builder
  .answer()
  .play({ url: 'https://example.com/welcome.mp3' })
  .sleep(1000)
  .hangup()
  .build();

console.log(doc);
```

### AI Agent with SWAIG

```typescript {7}
import { SwmlBuilder } from '@signalwire/sdk';

const builder = new SwmlBuilder();

builder
  .answer()
  .ai({
    prompt: { text: 'You are a helpful customer service assistant.' },
    post_prompt: 'Summarize what was discussed.',
    post_prompt_url: 'https://example.com/post_prompt',
    swaig: {
      defaults: { web_hook_url: 'https://example.com/swaig' },
      functions: [
        {
          function: 'check_order',
          description: 'Check order status',
          parameters: {
            type: 'object',
            properties: {
              order_id: { type: 'string', description: 'The order ID' },
            },
            required: ['order_id'],
          },
        },
      ],
    },
    hints: ['order', 'tracking', 'refund'],
    params: { end_of_speech_timeout: 500 },
  });

console.log(builder.render());
```

### Multi-Section Document

```typescript {10}
import { SwmlBuilder } from '@signalwire/sdk';

const builder = new SwmlBuilder();

// Add verbs to the default main section
builder.answer();
builder.play({ url: 'https://example.com/greeting.mp3' });

// Add verbs to a named section
builder.addVerbToSection('goodbye', 'play', {
  url: 'https://example.com/goodbye.mp3',
});
builder.addVerbToSection('goodbye', 'hangup', {});

console.log(builder.render());
```

> Fluent builder API for constructing SWML documents with method chaining.

## Docs

- [addSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/add-section.md): Add a new empty named section to the SWML document.
- [addVerb](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb.md): Append a verb to the main section of the SWML document.
- [addVerbToSection](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb-to-section.md): Append a verb to a named section, creating the section if it does not exist.
- [ai](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/ai.md): Add an AI verb to start an AI-powered conversation.
- [answer](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/answer.md): Add an answer verb to the SWML document.
- [build](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/build.md): Build and return the SWML document as an object.
- [document](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/document.md): Read-only accessor for the underlying SWML document.
- [getSchemaUtils](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/get-schema-utils.md): Get or create the shared SchemaUtils singleton.
- [hangup](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/hangup.md): Add a hangup verb to end the current call.
- [play](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/play.md): Add a play verb to play audio or text-to-speech.
- [render](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/render.md): Render the SWML document as a JSON string.
- [reset](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/reset.md): Reset the SWML document to an empty state.
- [say](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/say.md): Add a play verb with a say: prefix for text-to-speech.
- [setValidation](https://signalwire.com/docs/server-sdks/reference/typescript/agents/swml-builder/set-validation.md): Enable or disable verb schema validation at runtime.