import LamlAdmonition from ../_laml-admonition.md; # 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. This is an example of a simple SignalWire cXML document: xml Welcome to SignalWire! ## 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](#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. :::tip 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 Connecting you... +15551234567 As the name suggests, SignalWire cXML is XML-based and consists of the following elements: - the **** 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, and are verbs. - **noun** — the item for the action specified in the associated verb. In the example above, is a noun of the verb. ### Response Element The root element of all SignalWire cXML documents is a tag. All messaging verbs in a document must be nested within a single element, and each document can only have a single one. ### Empty Response Empty response example xml javascript const { RestClient } = require(@signalwire/compatibility-api); const response = new RestClient.LaML.VoiceResponse(); csharp 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 must be used. To receive incoming messaging without requiring further actions, respond with . ## 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 is different from calling . ### Voice Verbs The following verbs cause the specified action to take place during the call: | Verb | Action | |:--|:| | [](./voice/denoise.mdx) | Enables or disables noise reduction. | | [](./voice/dial.mdx) | Initiates a call to another phone number. | | [](./voice/echo.mdx) | Echoes audio back to the call. | | [](./voice/gather.mdx) | Collects input from the remote number, either as pressed digits or as speech. | | [](./voice/play.mdx) | Plays an audio file in the call. | | [](./voice/record.mdx) | Records and saves the audio in the call. | | [](./voice/say.mdx) | Reads the supplied text into the call. | | [](./voice/sms.mdx) | Sends an SMS message during a call. | | [](./voice/stream.mdx) | Streams a call to a websocket. | The following verbs control what happens to the call itself: | Verb | Action | |:-|:| | [](./voice/enqueue.mdx) | Place the call into a queue. | | [](./voice/hangup.mdx) | Disconnect the call. | | [](./voice/leave.mdx) | Remove the call from the queue it is currently in. | | [](./voice/pause.mdx) | Wait before continuing to execute further instructions. | | [](./voice/redirect.mdx) | Stop executing the instructions in this XML document, and start executing those in another specified document. | | [](./voice/refer.mdx) | Send SIP REFER to transfer the call from SignalWire control. | | [](./voice/reject.mdx) | Decline an incoming call. | ### Messaging Verbs The following verbs are used to manage messages and responses: | Verb | Action | |:--|:| | [](./messaging/message.mdx) | Sends a message to another phone number. | | [](./messaging/redirect.mdx) | 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 | |:|:--| | [](./fax/receive.mdx) | Receives an incoming fax. | | [](./fax/reject.mdx) | 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 noun within a verb: xml my-example-conference 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()); csharp 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.