> 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/python/agents/swml-service

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

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

[addsection]: /docs/server-sdks/reference/python/agents/swml-builder/add-section

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

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

[build]: /docs/server-sdks/reference/python/agents/swml-builder/build

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

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

[render]: /docs/server-sdks/reference/python/agents/swml-builder/render

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

[say]: /docs/server-sdks/reference/python/agents/swml-builder/say

SWMLBuilder provides a fluent interface for constructing SWML documents by chaining
method calls. It wraps a [`SWMLService`][swmlservice]
instance and delegates all document operations to it, while returning `self` from every
verb method to enable chaining. 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 schema (e.g., `connect()`, `record()`, `denoise()`,
`goto()`). These dynamic methods accept keyword arguments matching the verb's SWML
parameters and return `self` for chaining.

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

## **Properties**

**`service`** `SWMLService` — required

The [`SWMLService`][swmlservice] instance that
handles actual document storage, validation, and rendering. The builder delegates
all operations to this service.

---

## **Dynamic Verb Methods**

SWMLBuilder auto-generates chaining methods for every verb defined in the SWML schema
that does not already have an explicit method. These dynamic methods accept keyword
arguments matching the verb's SWML parameters and return `Self`.

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

```python {6-8}
from signalwire import SWMLService, SWMLBuilder

service = SWMLService(name="dynamic-demo")
builder = SWMLBuilder(service)

builder.connect(to="+15551234567", from_="+15559876543")
builder.record_call(format="mp4", stereo=True)
builder.denoise()

print(builder.build())
```

The `sleep` verb is a special case -- it accepts a positional `duration` argument
(milliseconds) instead of keyword arguments:

```python {6}
from signalwire import SWMLBuilder, SWMLService

service = SWMLService(name="demo")
builder = SWMLBuilder(service)
builder.add_section("main")
builder.sleep(duration=2000)

print(builder.render())
```

> **Info**
>
> If a verb name is not found in the SWML schema, calling it raises an `AttributeError`.

## **Methods**

#### [add\_section](/docs/server-sdks/reference/python/agents/swml-builder/add-section)

Add a new named section to the SWML document.

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

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

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

Add an answer verb to the SWML document.

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

Build and return the complete SWML document as a dictionary.

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

Add a hangup verb to end the current call.

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

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

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

Build and render the complete SWML document as a JSON string.

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

Reset the SWML document to an empty state.

#### [say](/docs/server-sdks/reference/python/agents/swml-builder/say)

Add text-to-speech playback to the SWML document.

---

## **Examples**

### Basic IVR Flow

```python {8-12}
from signalwire import SWMLService, SWMLBuilder

service = SWMLService(name="ivr")
builder = SWMLBuilder(service)

doc = (
    builder
    .answer()
    .play(url="https://example.com/welcome.mp3")
    .sleep(duration=1000)
    .hangup()
    .build()
)
print(doc)
```

### AI Agent with SWAIG

```python {8-9}
from signalwire import SWMLService, SWMLBuilder

service = SWMLService(name="ai-agent")
builder = SWMLBuilder(service)

swml_json = (
    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}
    )
    .render()
)
print(swml_json)
```

### Text-to-Speech Greeting

```python {9,11}
from signalwire import SWMLService, SWMLBuilder

service = SWMLService(name="greeting")
builder = SWMLBuilder(service)

doc = (
    builder
    .answer()
    .say("Welcome to our service. Please hold.", voice="rime.spore")
    .sleep(duration=500)
    .say("Connecting you now.", voice="rime.spore")
    .build()
)
print(doc)
```

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

## Docs

- [add_section](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/add-section.md): Add a new named section to the SWML document.
- [ai](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/ai.md): Add an AI verb to start an AI-powered conversation.
- [answer](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/answer.md): Add an answer verb to the SWML document.
- [build](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/build.md): Build and return the complete SWML document as a dictionary.
- [hangup](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/hangup.md): Add a hangup verb to end the current call.
- [play](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/play.md): Add a play verb to play audio or text-to-speech.
- [render](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/render.md): Build and render the complete SWML document as a JSON string.
- [reset](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/reset.md): Reset the SWML document to an empty state.
- [say](https://signalwire.com/docs/server-sdks/reference/python/agents/swml-builder/say.md): Add text-to-speech playback to the SWML document.