cXML Specification

SignalWire cXML (Compatibility XML) is an XML-based language for controlling voice calls, SMS/MMS messages, and faxes. It is fully compatible with Twilio’s TwiML, allowing you to use existing TwiML documents with SignalWire without modification.

How cXML works

When a call, message, or fax arrives at one of your SignalWire phone numbers, SignalWire makes an HTTP request to the webhook URL configured for that number. Your server responds with a cXML document containing instructions for how to handle the communication.

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

SignalWire executes instructions in order from top to bottom. Outbound calls and messages work the same way: you provide a URL to a cXML document when initiating the call or message via the REST API.

Multiple cXML documents can be chained together using redirect verbs, enabling complex application flows.

Channel types

cXML supports three channel types, each with its own set of verbs:

Syntax

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Say>Connecting you...</Say>
4
  <Dial>
5
    <Number>+15551234567</Number>
6
  </Dial>
7
</Response>

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

• the <Response> element — the root tag defining the body of the XML document.
• verbs — XML tags denoting actions that you want SignalWire to take. In the example above, <Say> and <Dial> are verbs.
• nouns — the items for the actions specified in the associated verbs. 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 verbs in a document must be nested within a single <Response> element, and each document can only have one.

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 an empty response:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<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>.

Each channel type has its own set of available verbs. See the Voice, Messaging, and Fax overview pages for the complete list of verbs for each channel.

Nouns

A noun is what the verb uses to complete its action. Placed inside a verb tag, it can be the text that is read in a call, or other XML 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:

1
<?xml version="1.0" encoding="UTF-8"?>
2
<Response>
3
  <Dial>
4
    <Conference>my-example-conference</Conference>
5
  </Dial>
6
</Response>

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.