SignalWire cXML

SignalWire cXML is a set of actions defined in an XML document you can use to tell SignalWire what to do when you receive an incoming call or instructions for outbound calls.

When a call is made 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 call, and much more.

Request for XML

SignalWire makes an HTTP request to your configured endpoint just like a regular web form submission (POST) or page load (GET). The request includes contextual information about the call, allowing you to respond dynamically and fluidly to the call 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 call:

AccountSid

• Type: string
  The unique ID of the Account this call is associated with.

ApiVersion

• Type: string
  The version of the SignalWire API. Incoming calls use the API version placed on the number called. Outgoing calls use the version of the REST API request.

CallSid

• Type: string
  A unique identifier for the call.

CallStatus

• Type: string
  The status of the call. Can be one of the following values: ringing, in-progress, queued, failed, busy, no-answer, or completed.

Direction

• Type: string
  An identifier to describe the direction of the call: outbound-dial: calls launched through the <Dial> verb, outbound-api: calls launched through the REST API, inbound: for inbound calls.

From

• Type: string
  The phone number that sent this call, in E.164 format.

ParentCallSid

• Type: string
  A unique identifier for the call that created this call.

To

• Type: string
  The phone number of the call recipient, in E.164 format.

CallStatus values

The following are the possible CallStatus parameter values. These are also used in <Dial>’s DialCallStatus:

Responding to SignalWire

An example of a SignalWire cXML document that reads a message to the caller before playing an audio file:

<?xml version="1.0" encoding="UTF-8"?>
<Response>
    <Say>Hello, World!</Say>
    <Play>https://your-application.com/audio.mp3</Play>
</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 your Compatibility XML document and executes your XML commands in order, from top to bottom.

Status callbacks

Status callbacks are asynchronous, best-effort HTTP notifications: delivery can be delayed or fail silently — if your server is unreachable, the callback simply never arrives. Don’t gate time-critical or business-critical actions solely on receiving one. Confirm state via the REST API before acting, or use a transport with visible failure modes — see Status callback reliability.

SignalWire can send your application callbacks at various lifecycle stages of your call. 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 call 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.

The StatusCallback request contains the Standard Request Parameters plus the following optional parameters:

AudioInMos

• Type: string
  The mean opinion score that helps to determine audio quality. The scale is from 1-5 with 1 being worst and 5 being best.

CallbackSource

• Type: string
  The source of the status callback.

CallDuration

• Type: integer
  The duration, in seconds, of the finished call. Only present on the completed event.

CallerName

• Type: string
  The name of the caller. Only available if Caller ID lookup is enabled.

ForwardedFrom

• Type: string
  The number this call was forwarded from.

HangupBy

• Type: string
  An indicator of which number ended the call.

HangupDirection

• Type: string
  An indicator of which direction ended the call.

RecordingDuration

• Type: integer
  The duration, in seconds, of the recording.

RecordingSid

• Type: string
  The unique identifier for the audio recording.

RecordingUrl

• Type: string
  The URL of the recorded audio call.

SequenceNumber

• Type: integer
  The order in which events occur. Starts at 0. Although events are fired in order, they each take time and may not appear in the order you expect.

Timestamp

• Type: string
  The timestamp, in RFC 2822 format, of when the event occurred.

Instructions

Instructions (verbs and nouns) tell SignalWire what actions to take during a call. They are executed sequentially, so one instruction must complete fully before the next one is executed. Some instructions have optional attributes that can override the flow of execution, allowing you to dynamically change what happens based on events within the call.

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

Call actions

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

• Connect – Connect a call to another resource like a video room or stream.
• Denoise – Enable or disable noise reduction.
• Dial – Initiate a call to another phone number.
• Echo – Echo audio back to the call.
• Gather – Collect input from the caller as pressed digits or speech.
• Pay – Securely collect payment information during a call.
• Play – Play an audio file in the call.
• Record – Record and save the audio in the call.
• Say – Read the supplied text into the call.
• Sms – Send an SMS message during a call.
• Stream – Stream a call to a websocket.

Call control

The following instructions control what happens to the call itself:

• 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 current document and start executing another.
• Refer – Send SIP REFER to transfer the call from SignalWire control.
• Reject – Decline an incoming call.