Skip to main content

What is SignalWire Compatibility XML?

SignalWire 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 Compatibility XML allows you to specify instructions using simple commands called verbs. SignalWire starts at the top of your XML document and executes your SignalWire Compatibility commands in order, from top to bottom.

This is an example of a simple SignalWire Compatibility XML 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 Compatibility document that determines what to do next.

SignalWire will read the instructions in the SignalWire Compatibility XML 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 Compatibility 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 SignalWire XML document is executed at a time, many documents can be linked together and generated dynamically to create complex applications to fit any need.

SignalWire Compatibility XML 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>

SignalWire Compatibility 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 Compatibility XML 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 version="1.0" encoding="UTF-8"?>
<Response></Response>

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:

VerbAction
<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:

VerbAction
<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:

VerbAction
<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:

VerbAction
<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 Compatibility 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 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 Compatibility 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 Compatibility 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.