Swml Schema
SWML Schema
Reference for SWML (SignalWire Markup Language) document structure and validation.
Overview
SWML (SignalWire Markup Language) is a JSON format for defining call flows and AI agent behavior.
Key Components:
version: Schema version (always “1.0.0”)sections: Named groups of verbsVerbs: Actions like ai, play, connect, transfer
Basic Structure
1 { 2 "version": "1.0.0", 3 "sections": { 4 "main": [ 5 { "verb_name": { "param": "value" } } 6 ] 7 } 8 }
Required Fields
| Field | Type | Description |
|---|---|---|
version | string | Must be “1.0.0” |
sections | object | Contains named section arrays |
main | array | Default entry section (required) |
AI Verb
The ai verb creates an AI agent:
1 { 2 "version": "1.0.0", 3 "sections": { 4 "main": [ 5 { 6 "ai": { 7 "prompt": { 8 "text": "You are a helpful assistant." 9 }, 10 "post_prompt": { 11 "text": "Summarize the conversation." 12 }, 13 "post_prompt_url": "https://example.com/summary", 14 "params": { 15 "temperature": 0.7 16 }, 17 "languages": [ 18 { 19 "name": "English", 20 "code": "en-US", 21 "voice": "rime.spore" 22 } 23 ], 24 "hints": ["SignalWire", "SWAIG"], 25 "SWAIG": { 26 "functions": [], 27 "native_functions": [], 28 "includes": [] 29 } 30 } 31 } 32 ] 33 } 34 }
AI Verb Parameters
| Parameter | Type | Description |
|---|---|---|
prompt | object | Main prompt configuration |
post_prompt | object | Summary/completion prompt |
post_prompt_url | string | URL for summary delivery |
params | object | AI model parameters |
languages | array | Supported languages and voices |
hints | array | Speech recognition hints |
SWAIG | object | Function definitions |
pronounce | array | Pronunciation rules |
global_data | object | Initial session data |
SWAIG Object
1 { 2 "SWAIG": { 3 "functions": [ 4 { 5 "function": "search", 6 "description": "Search for information", 7 "parameters": { 8 "type": "object", 9 "properties": { 10 "query": { 11 "type": "string", 12 "description": "Search query" 13 } 14 }, 15 "required": ["query"] 16 }, 17 "web_hook_url": "https://example.com/swaig" 18 } 19 ], 20 "native_functions": [ 21 "check_time" 22 ], 23 "includes": [ 24 { 25 "url": "https://example.com/shared_functions", 26 "functions": ["shared_search", "shared_lookup"] 27 } 28 ] 29 } 30 }
Function Definition
| Field | Type | Required | Description |
|---|---|---|---|
function | string | Yes | Function name |
description | string | Yes | What the function does |
parameters | object | No | JSON Schema for parameters |
web_hook_url | string | * | Webhook URL (if not data_map) |
data_map | object | * | DataMap definition |
meta_data | object | No | Custom metadata |
meta_data_token | string | No | Token scope for metadata |
fillers | array | No | Processing phrases |
wait_file | string | No | Hold audio URL |
Common Verbs
answer
1 { "answer": {} }
play
1 { 2 "play": { 3 "url": "https://example.com/audio.mp3" 4 } 5 }
connect
1 { 2 "connect": { 3 "to": "+15551234567", 4 "from": "+15559876543" 5 } 6 }
transfer
1 { 2 "transfer": { 3 "dest": "https://example.com/other_agent" 4 } 5 }
hangup
1 { "hangup": {} }
record_call
1 { 2 "record_call": { 3 "stereo": true, 4 "format": "mp3" 5 } 6 }
record
1 { 2 "record": { 3 "format": "mp3" 4 } 5 }
Contexts Structure
1 { 2 "version": "1.0.0", 3 "sections": { 4 "main": [{ 5 "ai": { 6 "contexts": { 7 "default": "main", 8 "main": { 9 "steps": [ 10 { 11 "name": "greeting", 12 "text": "Welcome the caller.", 13 "valid_steps": ["collect"] 14 }, 15 { 16 "name": "collect", 17 "text": "Collect information.", 18 "functions": ["lookup_account"], 19 "valid_steps": ["confirm"] 20 } 21 ] 22 } 23 } 24 } 25 }] 26 } 27 }
Step Structure
| Field | Type | Description |
|---|---|---|
name | string | Step identifier |
text | string | Step prompt text |
step_criteria | string | Completion criteria |
functions | string | array | ”none” or list of function names |
valid_steps | array | Allowed next steps |
valid_contexts | array | Allowed context switches |
DataMap Structure
1 { 2 "function": "get_weather", 3 "description": "Get weather information", 4 "parameters": { 5 "type": "object", 6 "properties": { 7 "city": { 8 "type": "string", 9 "description": "City name" 10 } 11 }, 12 "required": ["city"] 13 }, 14 "data_map": { 15 "webhooks": [ 16 { 17 "url": "https://api.weather.com/current?q=${enc:args.city}", 18 "method": "GET", 19 "output": { 20 "response": "Weather: ${response.condition}" 21 } 22 } 23 ] 24 } 25 }
Prompt Object (POM)
1 { 2 "prompt": { 3 "pom": [ 4 { 5 "section": "Role", 6 "body": "You are a helpful assistant." 7 }, 8 { 9 "section": "Guidelines", 10 "bullets": [ 11 "Be concise", 12 "Be helpful", 13 "Be accurate" 14 ] 15 } 16 ] 17 } 18 }
Language Configuration
1 { 2 "languages": [ 3 { 4 "name": "English", 5 "code": "en-US", 6 "voice": "rime.spore", 7 "speech_fillers": ["um", "uh"], 8 "function_fillers": ["Let me check..."] 9 }, 10 { 11 "name": "Spanish", 12 "code": "es-ES", 13 "voice": "rime.spore" 14 } 15 ] 16 }
Model Parameters
1 { 2 "params": { 3 "temperature": 0.7, 4 "top_p": 0.9, 5 "max_tokens": 150, 6 "frequency_penalty": 0.0, 7 "presence_penalty": 0.0, 8 "confidence": 0.6, 9 "barge_confidence": 0.1 10 } 11 }
Schema Validation
The SDK includes a schema.json file for validation:
1 from signalwire_agents.utils.schema_utils import SchemaUtils 2 3 schema = SchemaUtils() 4 schema.validate(swml_document)
Full Example
1 { 2 "version": "1.0.0", 3 "sections": { 4 "main": [ 5 { "answer": {} }, 6 { 7 "ai": { 8 "prompt": { 9 "pom": [ 10 { 11 "section": "Role", 12 "body": "You are a customer service agent." 13 }, 14 { 15 "section": "Guidelines", 16 "bullets": [ 17 "Be helpful and professional", 18 "Verify customer identity", 19 "Resolve issues efficiently" 20 ] 21 } 22 ] 23 }, 24 "post_prompt": { 25 "text": "Summarize the customer interaction." 26 }, 27 "post_prompt_url": "https://example.com/swaig/summary", 28 "params": { 29 "temperature": 0.7 30 }, 31 "languages": [ 32 { 33 "name": "English", 34 "code": "en-US", 35 "voice": "rime.spore" 36 } 37 ], 38 "hints": ["account", "billing", "support"], 39 "SWAIG": { 40 "functions": [ 41 { 42 "function": "lookup_account", 43 "description": "Look up customer account", 44 "parameters": { 45 "type": "object", 46 "properties": { 47 "account_id": { 48 "type": "string", 49 "description": "Account number" 50 } 51 }, 52 "required": ["account_id"] 53 }, 54 "web_hook_url": "https://example.com/swaig" 55 } 56 ] 57 } 58 } 59 } 60 ] 61 } 62 }