***

title: SwmlBuilder
slug: /reference/typescript/agents/swml-builder
description: Fluent builder API for constructing SWML documents with method chaining.
max-toc-depth: 3
---------------------

For a complete index of all SignalWire documentation pages, fetch https://signalwire.com/docs/llms.txt

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

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

[swml-reference]: /docs/swml/reference/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

[getdocument]: /docs/server-sdks/reference/typescript/agents/swml-builder/get-document

[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

[renderdocument]: /docs/server-sdks/reference/typescript/agents/swml-builder/render-document

[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.
</Info>

## **Constructor**

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

```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.renderDocument());
```

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.renderDocument());
```

## **Methods**

<CardGroup cols={3}>
  <Card title="addVerb" href="/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb">
    Append a verb to the main section.
  </Card>

  <Card title="addVerbToSection" href="/docs/server-sdks/reference/typescript/agents/swml-builder/add-verb-to-section">
    Append a verb to a named section.
  </Card>

  <Card title="ai" href="/docs/server-sdks/reference/typescript/agents/swml-builder/ai">
    Add an AI verb to start an AI-powered conversation.
  </Card>

  <Card title="answer" href="/docs/server-sdks/reference/typescript/agents/swml-builder/answer">
    Add an answer verb to the SWML document.
  </Card>

  <Card title="getDocument" href="/docs/server-sdks/reference/typescript/agents/swml-builder/get-document">
    Return the raw SWML document object.
  </Card>

  <Card title="getSchemaUtils" href="/docs/server-sdks/reference/typescript/agents/swml-builder/get-schema-utils">
    Get the shared SchemaUtils singleton (static).
  </Card>

  <Card title="hangup" href="/docs/server-sdks/reference/typescript/agents/swml-builder/hangup">
    Add a hangup verb to end the current call.
  </Card>

  <Card title="play" href="/docs/server-sdks/reference/typescript/agents/swml-builder/play">
    Add a play verb to play audio or text-to-speech.
  </Card>

  <Card title="renderDocument" href="/docs/server-sdks/reference/typescript/agents/swml-builder/render-document">
    Serialize the SWML document to a JSON string.
  </Card>

  <Card title="reset" href="/docs/server-sdks/reference/typescript/agents/swml-builder/reset">
    Reset the SWML document to an empty state.
  </Card>
</CardGroup>

***

## **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()
  .getDocument();

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.renderDocument());
```

### 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.renderDocument());
```