SWML (SignalWire Markup Language)

What is SWML?

SWML (SignalWire Markup Language) is a document that instructs SignalWire how to handle a phone call. SWML can be written in JSON or YAML format — this guide uses JSON throughout. When a call comes in, SignalWire requests SWML from your agent, then executes the instructions.

SWML request and response flow. — SWML Flow

SWML Document Structure

Every SWML document has this structure:

1 {
2   "version": "1.0.0",
3   "sections": {
4     "main": [
5       { "verb1": { ...config } },
6       { "verb2": { ...config } },
7       { "verb3": { ...config } }
8     ]
9   }
10 }

Key parts:

version: Always "1.0.0"
sections: Contains named sections (usually just main)
Each section is an array of verbs (instructions)

Common Verbs

Verb	Purpose	Example
`answer`	Answer the incoming call	`{"answer": {}}`
`ai`	Start AI conversation	`{"ai": {...config}}`
`connect`	Transfer to another number	`{"connect": {"to": "+1..."}}`
`play`	Play audio file	`{"play": {"url": "..."}}`
`record_call`	Record the call	`{"record_call": {"format": "mp4"}}`
`hangup`	End the call	`{"hangup": {}}`

A Complete SWML Example

Here’s what your agent generates:

1 {
2   "version": "1.0.0",
3   "sections": {
4     "main": [
5       {
6         "answer": {}
7       },
8       {
9         "ai": {
10           "prompt": {
11             "text": "# Role\nYou are a helpful customer service agent.\n\n# Guidelines\n- Be professional\n- Be concise"
12           },
13           "post_prompt": "Summarize what was discussed",
14           "post_prompt_url": "https://your-agent.com/post_prompt",
15           "SWAIG": {
16             "defaults": {
17               "web_hook_url": "https://your-agent.com/swaig"
18             },
19             "functions": [
20               {
21                 "function": "get_balance",
22                 "description": "Get the customer's account balance",
23                 "parameters": {
24                   "type": "object",
25                   "properties": {
26                     "account_id": {
27                       "type": "string",
28                       "description": "The account ID"
29                     }
30                   },
31                   "required": ["account_id"]
32                 }
33               }
34             ]
35           },
36           "hints": ["account", "balance", "payment"],
37           "languages": [
38             {
39               "name": "English",
40               "code": "en-US",
41               "voice": "rime.spore"
42             }
43           ],
44           "params": {
45             "end_of_speech_timeout": 500,
46             "attention_timeout": 15000
47           }
48         }
49       }
50     ]
51   }
52 }

The `ai` Verb in Detail

The ai verb is the heart of voice AI agents. Here’s what each part does:

1 {
2   "ai": {
3     "prompt": {},            // What the AI should do (system prompt)
4     "post_prompt": "...",    // Instructions for summarizing the call
5     "post_prompt_url": "...",// Where to send the summary
6     "SWAIG": {},             // Functions the AI can call
7     "hints": [],             // Words to help speech recognition
8     "languages": [],         // Voice and language settings
9     "params": {},            // AI behavior parameters
10     "global_data": {}        // Data available throughout the call
11   }
12 }

prompt

The AI’s system prompt — its personality and instructions:

1 {
2   "prompt": {
3     "text": "You are a helpful assistant..."
4   }
5 }

Or using POM (Prompt Object Model):

1 {
2   "prompt": {
3     "pom": [
4       {
5         "section": "Role",
6         "body": "You are a customer service agent"
7       },
8       {
9         "section": "Rules",
10         "bullets": ["Be concise", "Be helpful"]
11       }
12     ]
13   }
14 }

SWAIG

Defines functions the AI can call:

1 {
2   "SWAIG": {
3     "defaults": {
4       "web_hook_url": "https://your-agent.com/swaig"
5     },
6     "functions": [
7       {
8         "function": "check_order",
9         "description": "Check order status",
10         "parameters": {
11           "type": "object",
12           "properties": {
13             "order_id": {"type": "string"}
14           }
15         }
16       }
17     ]
18   }
19 }

hints

Words that help speech recognition accuracy:

1 {
2   "hints": ["SignalWire", "SWML", "account number", "order ID"]
3 }

languages

Voice and language configuration:

1 {
2   "languages": [
3     {
4       "name": "English",
5       "code": "en-US",
6       "voice": "rime.spore"
7     }
8   ]
9 }

params

AI behavior settings:

1 {
2   "params": {
3     "end_of_speech_timeout": 500,
4     "attention_timeout": 15000,
5     "barge_match_string": "stop|cancel|quit"
6   }
7 }

How Your Agent Generates SWML

You don’t write SWML by hand. Your agent configuration becomes SWML automatically. Each SDK method maps to a section of the SWML document:

Agent Method	SWML Output
`add_language(...)`	`ai.languages` array
`prompt_add_section(...)`	`ai.prompt.text` or `ai.prompt.pom`
`add_hints(...)`	`ai.hints` array
`set_params(...)`	`ai.params` object
`define_tool(...)`	`ai.SWAIG.functions` array

Python

TypeScript

1 from signalwire import AgentBase
2 
3 class MyAgent(AgentBase):
4     def __init__(self):
5         super().__init__(name="my-agent")
6         self.add_language("English", "en-US", "rime.spore")  # -> languages
7         self.prompt_add_section("Role", "You are helpful.")   # -> prompt
8         self.add_hints(["help", "support"])                   # -> hints
9         self.set_params({"end_of_speech_timeout": 500})       # -> params
10         self.define_tool(name="get_help", description="Get help", parameters={}, handler=self.get_help)  # -> SWAIG

The above examples all produce identical SWML output. See the Architecture section for the full API comparison table.

When SignalWire requests SWML, the agent’s render method (_render_swml() in Python, renderSwml() in TypeScript):

Collects all configuration (prompts, languages, hints, params)
Builds the SWAIG functions array with webhook URLs
Assembles the complete SWML document
Returns JSON to SignalWire

SWML Rendering Pipeline

Viewing Your SWML

You can see the SWML your agent generates:

$ ## Using curl (use credentials from agent startup output or env vars)
$ curl -u "$SWML_BASIC_AUTH_USER:$SWML_BASIC_AUTH_PASSWORD" http://localhost:3000/
$ 
$ ## Using swaig-test CLI (no auth needed - loads agent directly)
$ swaig-test my_agent.py --dump-swml
$ 
$ ## Pretty-printed
$ swaig-test my_agent.py --dump-swml --raw | jq '.'

SWML Schema Validation

The SDK validates SWML against the official schema:

Located at signalwire/core/schema.json
Catches invalid configurations before sending to SignalWire
Provides helpful error messages

Common SWML Patterns

Auto-Answer with AI

1 {
2   "version": "1.0.0",
3   "sections": {
4     "main": [
5       {"answer": {}},
6       {"ai": {...}}
7     ]
8   }
9 }

Record the Call

1 {
2   "version": "1.0.0",
3   "sections": {
4     "main": [
5       {"answer": {}},
6       {"record_call": {"format": "mp4", "stereo": true}},
7       {"ai": {...}}
8     ]
9   }
10 }

Transfer After AI

When a SWAIG function returns a transfer action, the SWML for transfer is embedded in the response:

1 {
2   "response": "Transferring you now",
3   "action": [
4     {"transfer": true},
5     {
6       "swml": {
7         "version": "1.0.0",
8         "sections": {
9           "main": [
10             {"connect": {"to": "+15551234567", "from": "+15559876543"}}
11           ]
12         }
13       }
14     }
15   ]
16 }

Next Steps

Now that you understand SWML structure, let’s look at SWAIG — how AI calls your functions.

1	{
2	"version": "1.0.0",
3	"sections": {
4	"main": [
5	{ "verb1": { ...config } },
6	{ "verb2": { ...config } },
7	{ "verb3": { ...config } }
8	]
9	}
10	}

1	{
2	"ai": {
3	"prompt": {}, // What the AI should do (system prompt)
4	"post_prompt": "...", // Instructions for summarizing the call
5	"post_prompt_url": "...",// Where to send the summary
6	"SWAIG": {}, // Functions the AI can call
7	"hints": [], // Words to help speech recognition
8	"languages": [], // Voice and language settings
9	"params": {}, // AI behavior parameters
10	"global_data": {} // Data available throughout the call
11	}
12	}

1	{
2	"prompt": {
3	"pom": [
4	{
5	"section": "Role",
6	"body": "You are a customer service agent"
7	},
8	{
9	"section": "Rules",
10	"bullets": ["Be concise", "Be helpful"]
11	}
12	]
13	}
14	}

1	{
2	"SWAIG": {
3	"defaults": {
4	"web_hook_url": "https://your-agent.com/swaig"
5	},
6	"functions": [
7	{
8	"function": "check_order",
9	"description": "Check order status",
10	"parameters": {
11	"type": "object",
12	"properties": {
13	"order_id": {"type": "string"}
14	}
15	}
16	}
17	]
18	}
19	}

1	{
2	"hints": ["SignalWire", "SWML", "account number", "order ID"]
3	}

1	{
2	"languages": [
3	{
4	"name": "English",
5	"code": "en-US",
6	"voice": "rime.spore"
7	}
8	]
9	}

1	{
2	"params": {
3	"end_of_speech_timeout": 500,
4	"attention_timeout": 15000,
5	"barge_match_string": "stop\|cancel\|quit"
6	}
7	}

1	from signalwire import AgentBase
2
3	class MyAgent(AgentBase):
4	def __init__(self):
5	super().__init__(name="my-agent")
6	self.add_language("English", "en-US", "rime.spore") # -> languages
7	self.prompt_add_section("Role", "You are helpful.") # -> prompt
8	self.add_hints(["help", "support"]) # -> hints
9	self.set_params({"end_of_speech_timeout": 500}) # -> params
10	self.define_tool(name="get_help", description="Get help", parameters={}, handler=self.get_help) # -> SWAIG

$	## Using curl (use credentials from agent startup output or env vars)
$	curl -u "$SWML_BASIC_AUTH_USER:$SWML_BASIC_AUTH_PASSWORD" http://localhost:3000/
$
$	## Using swaig-test CLI (no auth needed - loads agent directly)
$	swaig-test my_agent.py --dump-swml
$
$	## Pretty-printed
$	swaig-test my_agent.py --dump-swml --raw \| jq '.'

1	{
2	"response": "Transferring you now",
3	"action": [
4	{"transfer": true},
5	{
6	"swml": {
7	"version": "1.0.0",
8	"sections": {
9	"main": [
10	{"connect": {"to": "+15551234567", "from": "+15559876543"}}
11	]
12	}
13	}
14	}
15	]
16	}

What is SWML?

SWML Document Structure

Common Verbs

A Complete SWML Example

The ai Verb in Detail

prompt

SWAIG

hints

languages

params

How Your Agent Generates SWML

Python

TypeScript

SWML Rendering Pipeline

Viewing Your SWML

SWML Schema Validation

Common SWML Patterns

Auto-Answer with AI

Record the Call

Transfer After AI

Next Steps

What is SWML?

SWML Document Structure

Common Verbs

A Complete SWML Example

The ai Verb in Detail

prompt

SWAIG

hints

languages

params

How Your Agent Generates SWML

Python

TypeScript

SWML Rendering Pipeline

Viewing Your SWML

SWML Schema Validation

Common SWML Patterns

Auto-Answer with AI

Record the Call

Transfer After AI

Next Steps

The `ai` Verb in Detail

The `ai` Verb in Detail