SWMLBuilder | SignalWire

SWMLBuilder provides a fluent interface for constructing SWML documents by chaining method calls. It wraps a 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.

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

Properties

service

SWMLServiceRequired

The 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.

1 from signalwire import SWMLService, SWMLBuilder
2 
3 service = SWMLService(name="dynamic-demo")
4 builder = SWMLBuilder(service)
5 
6 builder.connect(to="+15551234567", from_="+15559876543")
7 builder.record_call(format="mp4", stereo=True)
8 builder.denoise()
9 
10 print(builder.build())

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

1 from signalwire import SWMLBuilder, SWMLService
2 
3 service = SWMLService(name="demo")
4 builder = SWMLBuilder(service)
5 builder.add_section("main")
6 builder.sleep(duration=2000)
7 
8 print(builder.render())

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

Methods

add_section

Add a new named section to the SWML document.

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

answer

Add an answer verb to the SWML document.

build

Build and return the complete SWML document as a dictionary.

hangup

Add a hangup verb to end the current call.

play

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

render

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

reset

Reset the SWML document to an empty state.

say

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

Examples

Basic IVR Flow

1 from signalwire import SWMLService, SWMLBuilder
2 
3 service = SWMLService(name="ivr")
4 builder = SWMLBuilder(service)
5 
6 doc = (
7     builder
8     .answer()
9     .play(url="https://example.com/welcome.mp3")
10     .sleep(duration=1000)
11     .hangup()
12     .build()
13 )
14 print(doc)

AI Agent with SWAIG

1 from signalwire import SWMLService, SWMLBuilder
2 
3 service = SWMLService(name="ai-agent")
4 builder = SWMLBuilder(service)
5 
6 swml_json = (
7     builder
8     .answer()
9     .ai(
10         prompt_text="You are a helpful customer service assistant.",
11         post_prompt="Summarize what was discussed.",
12         post_prompt_url="https://example.com/post_prompt",
13         swaig={
14             "defaults": {"web_hook_url": "https://example.com/swaig"},
15             "functions": [
16                 {
17                     "function": "check_order",
18                     "description": "Check order status",
19                     "parameters": {
20                         "type": "object",
21                         "properties": {
22                             "order_id": {"type": "string", "description": "The order ID"}
23                         },
24                         "required": ["order_id"]
25                     }
26                 }
27             ]
28         },
29         hints=["order", "tracking", "refund"],
30         params={"end_of_speech_timeout": 500}
31     )
32     .render()
33 )
34 print(swml_json)

Text-to-Speech Greeting

1 from signalwire import SWMLService, SWMLBuilder
2 
3 service = SWMLService(name="greeting")
4 builder = SWMLBuilder(service)
5 
6 doc = (
7     builder
8     .answer()
9     .say("Welcome to our service. Please hold.", voice="rime.spore")
10     .sleep(duration=500)
11     .say("Connecting you now.", voice="rime.spore")
12     .build()
13 )
14 print(doc)