SWML | SignalWire

SWML is the JSON format that tells SignalWire how to handle calls. Your agent generates SWML automatically - you configure the agent, and it produces the right SWML.

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 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:

1 from signalwire_agents import AgentBase
2 
3 
4 class MyAgent(AgentBase):
5     def __init__(self):
6         super().__init__(name="my-agent")
7 
8         # This becomes languages in SWML
9         self.add_language("English", "en-US", "rime.spore")
10 
11         # This becomes prompt in SWML
12         self.prompt_add_section("Role", "You are helpful.")
13 
14         # This becomes hints in SWML
15         self.add_hints(["help", "support"])
16 
17         # This becomes params in SWML
18         self.set_params({"end_of_speech_timeout": 500})
19 
20         # This becomes SWAIG.functions in SWML
21         self.define_tool(
22             name="get_help",
23             description="Get help information",
24             parameters={},
25             handler=self.get_help
26         )

When SignalWire requests SWML, the agent’s _render_swml() method:

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
$ curl http://localhost:3000/
$ 
$ ## Using swaig-test CLI
$ 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_agents/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.