The cXML Specification

SignalWire cXML (Compatibility XML) is the language used by SignalWire to determine how the phone numbers in your account react during calls or text messages. When a call or message comes into one of your SignalWire phone numbers, SignalWire makes an HTTP request to the URL endpoint you configured for that number. Your response to that request instructs SignalWire on what to do next.

Responses to the HTTP request are in an XML format. SignalWire cXML allows you to specify instructions using simple commands called verbs. SignalWire starts at the top of your XML document and executes your SignalWire cXML commands in order, from top to bottom.

THE API FORMERLY KNOWN AS LĀML

The Compatibility API and cXML were previously known as "LāML". laml still appears in endpoint URLs, and the cXML namespace of the REST Client is still titled LaML. Don't worry, it's all cXML!

This is an example of a simple SignalWire cXML document:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Welcome to SignalWire!</Say>
</Response>

How it Works

When a message or call is received by one of your SignalWire phone numbers, SignalWire looks up the URL endpoint you configured for that phone number and makes an HTTP request to it. The URL endpoint then responds to the request with a SignalWire cXML document that determines what to do next.

SignalWire will read the instructions in the SignalWire cXML document, from top to bottom, and will execute them in order.

You can generate and respond with raw XML yourself, or utilize one of the SignalWire helper libraries to help you generate it easily. For each XML example, we also include an example on how to generate the same XML using the helper libraries.

Outbound calls and messages started via the SignalWire cXML REST API are controlled the same way. When you start an outbound call or message, you also pass a link to a SignalWire XML document. SignalWire will make a request to this document to determine how it should proceed with the call or message.

While a single cXML document is executed at a time, many documents can be linked together and generated dynamically to create complex applications to fit any need.

Helper Libraries

All cXML examples are shown as raw XML by default. Use the language tabs to view the syntax for generating equivalent XML using a helper libraries available with our Compatibility SDKs for JavaScript, C#, Python, and Ruby.

Comparing the Compatibility SDKs and Libraries

While made available as part of our Compatibility SDKs, these cXML helper libraries are not REST clients and do not directly make API calls. They are better understood as helper libraries for easily generating XML within your language of choice.

SignalWire cXML Syntax

<?xml version="1.0" encoding="UTF-8"?>
<!-- All responses must contain the Response element -->
<Response>
  <!-- Say and Dial are examples of Verbs -->
  <Say>Connecting you...</Say>
  <Dial>
    <!-- Number is an example of a Dial Noun -->
    <Number>+15551234567</Number>
  </Dial>
</Response>

As the name suggests, SignalWire cXML is XML-based and consists of the following elements:

• the <Response> element — the tag defining the body of the XML document.
• verb — an XML tag denoting the action that you want SignalWire to take. In the example above, <Say> and <Dial> are verbs.
• noun — the item for the action specified in the associated verb. In the example above, <Number> is a noun of the <Dial> verb.

Response Element

The root element of all SignalWire cXML documents is a <Response> tag. All messaging verbs in a document must be nested within a single <Response> element, and each document can only have a single one.

Empty Response

Empty response example

XML

<?xml version="1.0" encoding="UTF-8"?>
<Response></Response>

JavaScript

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

C#

using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;

class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
    }
}

Python

from signalwire.voice_response import VoiceResponse

response = VoiceResponse()

Ruby

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new

puts response.to_s

When an incoming SMS, MMS, or call to a SignalWire phone number is received, SignalWire will automatically respond with the proper SignalWire XML directions to handle those incoming messages. Even if no actions are required to handle these messages, a <Response> must be used. To receive incoming messaging without requiring further actions, respond with <Response></Response>.

Verbs

A verb identifies the action to take.

Verbs are executed sequentially, so one instruction must complete fully before the next one is executed. Some verbs have optional attributes that can override the flow of execution, allowing you to dynamically change what happens based on events within the call.

All verbs are case-sensitive, so calling <ThisAction> is different from calling <thisaction>.

Voice Verbs

The following verbs cause the specified action to take place during the call:

Verb	Action
<Denoise>	Enables or disables noise reduction.
<Dial>	Initiates a call to another phone number.
<Echo>	Echoes audio back to the call.
<Gather>	Collects input from the remote number, either as pressed digits or as speech.
<Play>	Plays an audio file in the call.
<Record>	Records and saves the audio in the call.
<Say>	Reads the supplied text into the call.
<Sms>	Sends an SMS message during a call.
<Stream>	Streams a call to a websocket.

The following verbs control what happens to the call itself:

Verb	Action
<Enqueue>	Place the call into a queue.
<Hangup>	Disconnect the call.
<Leave>	Remove the call from the queue it is currently in.
<Pause>	Wait before continuing to execute further instructions.
<Redirect>	Stop executing the instructions in this XML document, and start executing those in another specified document.
<Refer>	Send SIP REFER to transfer the call from SignalWire control.
<Reject>	Decline an incoming call.

Messaging Verbs

The following verbs are used to manage messages and responses:

Verb	Action
<Message>	Sends a message to another phone number.
<Redirect>	Stop executing the instructions in this XML document, and start executing those in another specified document.

Fax Verbs

The following verbs are used to manage faxes:

Verb	Action
<Receive>	Receives an incoming fax.
<Reject>	Rejects an incoming fax.

Nouns

A noun is what the verb uses to complete its action. Placed inside a verb tab, it can be the text that is read in a call, or other XML or SignalWire cXML elements that represent the target of the action, such as Conference or Number.

Each verb has its own set of supported nouns. See the documentation for a specific verb for more details.

An example of using a <Conference> noun within a <Dial> verb:

XML

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>my-example-conference</Conference>
  </Dial>
</Response>

JavaScript

const { RestClient } = require("@signalwire/compatibility-api");
const response = new RestClient.LaML.VoiceResponse();

dial = response.dial();
dial.conference("my-example-conference");
console.log(response.toString());

C#

using Twilio.TwiML;
using Twilio.TwiML.Voice;
using System;


class Example
{
    static void Main()
    {
        var response = new VoiceResponse();
        var dial = new Dial();
        dial.Conference("my-example-conference");
        response.Append(dial);

        Console.WriteLine(response.ToString());
    }
}

Python

from signalwire.voice_response import VoiceResponse, Dial, Conference

response = VoiceResponse()
dial = Dial()
dial.conference('my-example-conference')
response.append(dial)

print(response)

Ruby

require 'signalwire/sdk'

response = Signalwire::Sdk::VoiceResponse.new do |response|
  response.dial do |dial|
    dial.conference('my-example-conference')
  end
end

puts response.to_s

Data Formats

Dates and Times

All dates and times in requests to and from SignalWire cXML API are UTC, and presented in RFC 2822 format.

For example, the date and time of 8:01 AM CDT on July 23rd, 2018 is presented as: Mon, 23 Jul 2018 13:01:00 +0000

Phone Numbers

All phone numbers in requests to or from the SignalWire cXML API are in E.164 format, an unambiguous general format for specifying international phone numbers. Numbers in this format start with a plus sign ("+") and the country code.

For example, a US-based phone number like (555) 123-4567 would be formatted like: +15551234567.

If a number cannot be represented in E.164 format, then SignalWire uses the raw Caller ID string that was received.