Cxml Reference

Fresh

cXML Specification

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

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.

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Welcome to SignalWire!</Say>
</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:

Voice\ \ Control calls with <Say>, <Play>, <Dial>, <Gather>, <Record>, and more. Messaging\ \ Handle SMS/MMS with <Message> and <Redirect>. Fax\ \ Manage faxes with <Receive> and <Reject>.

Syntax

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Say>Connecting you...</Say>
  <Dial>
    <Number>+15551234567</Number>
  </Dial>
</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:

XMLNode.jsC#PythonRuby

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

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Dial>
    <Conference>my-example-conference</Conference>
  </Dial>
</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.

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.

Messaging Overview

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

SignalWire cXML is a set of actions defined in an XML document that you can use to tell SignalWire what to do when you receive an incoming SMS or MMS message.

Overview

When an SMS or MMS message is sent to one of your SignalWire phone numbers, SignalWire looks up the SignalWire cXML document from the URL you configured, and reads the instructions you provided to determine what to do.

SignalWire cXML allows you to dynamically control what happens, responding with specific instructions based on the caller, time of day, incoming message, and much more.

Not sending SMS or MMS? SignalWire cXML allows you to control calls as well. Check out Voice XML for more details.

Request for XML

SignalWire makes an HTTP request to your configured endpoint just like a regular web form submission (POST) or page load (GET). Including contextual information about the message in the request to your endpoint, allows you to respond dynamically and fluidly to the message to meet the needs of your application.

You can configure the endpoint URL and HTTP Method in your phone number settings panel on your SignalWire Dashboard, or via the REST API.

Request parameters

SignalWire sends the following parameters, as either URL query parameters or POST parameters, to your endpoint when it receives a message:

AccountSid

string

The unique ID of the Account this message is associated with.

Body

string

The text body of the message.

From

string

The phone number that sent this message, in E.164 format.

MediaContentType{X}

string

The content-type of the media stored at MediaUrl{X}, where X is a zero-based index of the media. Example: MediaContentType0. Only present if media is included.

MediaUrl{X}

string

The URL to the media received in the message. URLs are publicly available but unguessable. Each media entry has its own entry, where X is a zero-based index of the media. Example: MediaUrl0. Only present if media is included.

MessageSid

string

A unique identifier for the message. May be used to later retrieve this message from the REST API.

NumMedia

integer

The number of media items associated with the message.

To

string

The phone number of the message recipient, in E.164 format.

Responding to SignalWire

An example SignalWire cXML document that sends two messages back to the sender when a message is received:

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Hello from SignalWire!</Message>
    <Message>Thanks for your message.</Message>
</Response>

When a 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 SignalWire cXML. SignalWire starts at the top of SignalWire cXML document and executes your XML commands in order, from top to bottom.

SignalWire cXML verbs and their attributes are case-sensitive, so using `<message>` instead of `<Message>` will result in an error.

Status callbacks

SignalWire can send your application callbacks at various lifecycle stages of your message. Status callbacks do not allow you to change the application execution directly, so callbacks do not have to respond with SignalWire cXML, but they allow your application to get updates as a message is happening.

You should respond to any callbacks with a 200 OK or 204 No Content, otherwise, you will see failures in your application log on SignalWire.

Instructions

The following instructions are used to manage messages and responses:

Message\ \ Send a message to another phone number. Redirect\ \ Stop executing the current document and start executing another.

MIME types

The following are the MIME types supported by SignalWire:

Type	Description
`audio/mp4`	mpeg layer 4 audio
`audio/mpeg`	mpeg layer 3 audio
`audio/mpeg3`	mpeg layer 3 audio
`audio/ogg`	ogg audio
`audio/vorbis`	audio compression format
`audio/vnd.wav`	wav format audio
`audio/ac3`	codec format audio
`audio/amr`	codec format audio
`audio/midi`	musical instrument digital interface format
`image/jpeg`	jpeg format image
`image/gif`	graphics interchange format
`image/png`	portable network graphics format
`image/bmp`	bitmap image format
`text/plain`	text file format
`text/calendar`	text file format
`text/vcard`	text file format
`text/x-vcard`	text file format
`video/mpeg`	mpeg video format
`video/mp4`	mpeg layer 4 video format
`video/quicktime`	quicktime video
`video/h264`	video compression format
`video/3gp`	media container format

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.

Message

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

The <Message> verb sends an SMS or MMS message to a phone number. To send a message in combination with Voice XML verbs, use the <Sms> Voice verb.

An example message that responds to the sender:

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Hello from SignalWire!</Message>
</Response>

An example message with further instructions returned from the action request.

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message action="https://your-application.com/followup"
             method="GET">
        Hello from SignalWire!
    </Message>
</Response>

Verb attributes

action

string

The action attribute takes a URL endpoint that is expected to return a cXML document to override control flow. The endpoint receives a callback with the Standard Messaging Request Parameters as well as MessageStatus and ErrorCode and expect a valid cXML document in return. The next instructions to be executed are the verbs returned in response to the action endpoint request. For example, any verbs following a <Message> verb with its action attribute set are unreachable, as flow control will be passed onto the response from the action request.

from

string

The from attribute takes a valid phone number in E.164 format or short code. If no from is specified, it defaults to the number that received the message. You can only specify from phone numbers or short codes that you have purchased from SignalWire and which are capable of messaging.

method

stringDefaults to POST

The method attribute specifies whether the request to action is a GET or a POST. Valid values are GET or POST.

to

string

The to attribute takes a valid phone number in E.164 format as an argument. The message is sent to this phone number. If no to is specified, the message is sent as a reply to the incoming message sender.

Message status

The MessageStatus parameter is sent with requests to the action endpoint or to statusCallback URLs. It determines whether the message was successfully sent or if there were problem with delivery.

Valid message statuses are: queued, sending, sent, failed, delivered

Nouns

An example Message verb using nested nouns

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>
        <Body>Hello from SignalWire!</Body>
        <Media>https://link.to/your-media-file</Media>
    </Message>
</Response>

The noun of a cXML verb is nested within the verb upon which the verb acts. <Message> has the following nouns:

Noun	Description
`plain text`	The text of the message you want to send.
`<Body>`	The text of the message you want to send. If more than one `<Body>` noun is present, the text will be concatenated together into a single string. The maximum body size allowed is 1600 characters.
`<Media>`	The URL of media to include in the message. If you wish to send multiple media in a single message, use multiple `<Media>` nouns. You can have a maximum of 10 media URLs per message.

Nesting

No other verbs can be nested within <Message> and you cannot nest <Message> within any other verbs.

Examples

Send a simple SMS

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Message>Hello from SignalWire!</Message>
</Response>

The simplest case for <Message>: SignalWire responds to an inbound message with a “hello” message, from the number that received the message.

Send an image with your message (MMS)

XMLNode.jsC#PythonRuby

```xml
&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;Response>
    &lt;Message>
        &lt;Body>Hello from SignalWire!&lt;/Body>
        &lt;Media>https://link.to/your-media-file&lt;/Media>
    &lt;/Message>
&lt;/Response>

Add a picture to the message by specifying a URL with a nested <Media> noun. The <Body> noun is optional if you are sending media and you do not want to send text with your media in the message.

Send a message and respond based on status

XMLNode.jsC#PythonRuby

&lt;?xml version="1.0" encoding="UTF-8"?>
&lt;Response>
    &lt;Message action="https://your-application.com/followup"
             method="GET">
        Hello from SignalWire!
    &lt;/Message>
    &lt;Message>I am unreachable!&lt;/Message>
&lt;/Response>

This example allows us to follow up with further actions based on whether the message is sent or not. The URL https://your-application.com/followup receives a GET request with the message’s parameters and includes the MessageStatus, either invalid, sending or failed.

The cXML document returned from your application determines what to do next. You could do nothing, or if the MessageStatus was failed, you could alert the user with a different <Message>.

With the action attribute is present, the remaining verbs in the document are unreachable because control is passed off to the response rather than continuing on in the document.

Redirect

For AI agents: a documentation index is available at the root level at /llms.txt. Append /llms.txt to any URL for a page-level index, or .md for the markdown version of any page.

The <Redirect> verb transfers control from the current document to another. It is effectively an exit statement from the current document, as there is no way to return to any instructions listed after the <Redirect> verb.

An example message that redirects next XML instruction to another document:

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Redirect>https://your-application.com/next-instructions</Redirect>
</Response>

Verb attributes

The following attribute is available for the verb <Redirect>:

method

stringDefaults to POST

Specifies whether the redirect is a GET or a POST.

Nouns

The following item is accepted as a noun for the <Redirect> verb:

Noun	Description
`plain text`	The URL, in plain text, of the document to execute.

Nesting

No other verbs can be nested within <Redirect> and you cannot nest <Redirect> within any other verbs.

Examples

Redirect to absolute URL

XMLNode.jsC#PythonRuby

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Redirect>http://www.somesite.com/NextDoc.xml</Redirect>
</Response>

To continue processing this message using the instructions in another document, specify the absolute URL of that document as the noun to the <Redirect> verb.

*Twilio and TwiML are trademarks of Twilio, Inc. SignalWire, Inc. and its products are not affiliated with or endorsed by Twilio, Inc.

Cxml Reference ​

cXML Specification ​

How cXML works ​

Channel types ​

Syntax ​

Response element ​

Verbs ​

Nouns ​

Data formats ​

Dates and times ​

Phone numbers ​

Messaging Overview ​

Overview ​

Not sending SMS or MMS? SignalWire cXML allows you to control calls as well. Check out Voice XML for more details. ​

Request for XML ​

Request parameters ​

AccountSid ​

Body ​

From ​

MediaContentType{X} ​

MediaUrl{X} ​

MessageSid ​

NumMedia ​

To ​

Responding to SignalWire ​

SignalWire cXML verbs and their attributes are case-sensitive, so using <message> instead of <Message> will result in an error. ​

Status callbacks ​

Instructions ​

MIME types ​

Message ​

Verb attributes ​

action ​

from ​

method ​

to ​

Message status ​

Nouns ​

Nesting ​

Examples ​

Send a simple SMS ​

Send an image with your message (MMS) ​

Send a message and respond based on status ​

See also ​

Redirect ​

Verb attributes ​

method ​

Nouns ​

Nesting ​

Examples ​

Redirect to absolute URL ​

Cxml Reference

cXML Specification

How cXML works

Channel types

Syntax

Response element

Verbs

Nouns

Data formats

Dates and times

Phone numbers

Messaging Overview

Overview

Not sending SMS or MMS? SignalWire cXML allows you to control calls as well. Check out Voice XML for more details.

Request for XML

Request parameters

AccountSid

Body

From

MediaContentType{X}

MediaUrl{X}

MessageSid

NumMedia

To

Responding to SignalWire

SignalWire cXML verbs and their attributes are case-sensitive, so using `<message>` instead of `<Message>` will result in an error.

Status callbacks

Instructions

MIME types

Message

Verb attributes

action

from

method

to

Message status

Nouns

Nesting

Examples

Send a simple SMS

Send an image with your message (MMS)

Send a message and respond based on status

See also

Redirect

Verb attributes

method

Nouns

Nesting

Examples

Redirect to absolute URL