SignalWire Markup Language (SWML) is a powerful manifestation of call flow instructions, expressed in YAML or JSON. SWML surpasses traditional CPaaS solutions, with greater flexibility and potency through its underlying technology stack, FreeSWITCH. In this post, we’ll go over SWML essentials, with examples for developing sophisticated call flows in an astonishingly low-code fashion.

Getting Started

Begin by configuring your SignalWire phone number to interpret a SWML script. When this number receives an incoming call, it will automatically send a POST request to its associated webhook. This webhook will contain the script’s currently defined call object and variables. In return, a server - be it SignalWire’s or your own - replies with the SWML script, ready to execute.

We will focus on crafting a SWML script entirely within your SignalWire Space, using YAML. You can, however, also implement the native functionality of your preferred programming language to write SWML in a JSON format.

Creating Your First SWML Script

After configuring your phone number, visit the RELAY / SWML tab of your SignalWire Space. Consider SWML the RELAY equivalent of Compatibility XML. Under the SWML Scripts heading, select + New to generate a new SWML script.

Basic Example SWML Script

The most basic SWML script will look something like the above.

Each script begins with an optional version field: a string representing a semantic version of the document schema.

Up next are the sections. Every SWML script is built using a non-optional “sections” field that features a mandated main section. Each section is an array of strings or objects that comprise SWML’s statements and methods. Statements control the script’s flow or manage the call’s state, while Methods provide the catalyst for a call’s output. The main section of a SWML script is always executed first.

Utilizing the play method and its say parameter, supplied text will be read aloud to the caller. Freely customize the gender and language of your text-to-speech using Amazon Polly or Google Cloud voices.

Advancing Your Script

Rapid iteration is a key component of SWML. Unlike older XML-based systems, SWML enables the expression of an entire call flow within a singular document, saving developers of all skill levels from drowning in a sea of webhooks.

Branching Logic

Label enables you to denote subdivisions within the sections of your SWML document. These are useful when creating transfer, goto, or execute statements that transport callers to disparate parts of a call flow.

By introducing the prompt method, callers can navigate your call flow via the input of a digit or a verbal response. To enable speech detection, you must set one of its parameters, like speech_hints.

The proceeding switch statement will execute instructions that correspond to the caller’s input using the prompt_value variable. For a more robust SWML script, you can create or delete your own variables using the set and unset statements. All variables are global, and can be referenced inside %{} JavaScript expressions in the vars. JavaScript object.

Employing the connect method, you can forward callers to a combination of PSTN numbers and SIP endpoints, ringing each serially or simultaneously in parallel. Additionally, the %{call.from} call object parameter can be used to pass the original inbound caller ID through to your endpoints.

The record method simplifies voicemail recording through the attainment of audio in the foreground. Conversely, the record_call method works in the background, and is ideal for recording the entirety of an active call.

Intuitively, each string or object within your main section's array will be executed in order until the section is completed. When there are no more statements or methods left to execute, the call will end.

Conclusion

You can imagine how SWML equips developers with the necessary tools to create intricate call flows using only a small amount of code. It’s extremely powerful when used to build with the new AI agent. If you’d like to learn more about building an AI agent with SWML, you can find an example here.

To learn more about SignalWire's capabilities, visit developer.signalwire.com, and join the vibrant SignalWire community on Slack or our Forum to interact with the team and share your projects. We can't wait to see what you build!