| Namespace | http://www.mulesoft.org/schema/mule/twiml |
| Schema Location | http://www.mulesoft.org/schema/mule/twiml/1.0/mule-twiml.xsd |
| Version | 1.0 |
| Minimum Mule Version | 3.2 |
Module Overview
A Mule module for generating Twilios Markup Language. Twilio can handle instructions for calls and SMS messages in
real time from iON applications. When an SMS or incoming call is received, Twilio looks up the iON app associated
with the phone number called and makes a request to it. iON will respond to the request and that response will
decides how the call should proceed by returning a Twilio Markup XML (TwiML) document telling Twilio to say text
to the caller, send an SMS message, play audio files, get input from the keypad, record audio, connect the call
to another phone and more.
TwiML is similar to HTML. Just as HTML is rendered in a browser to display a webpage, TwiML is 'rendered' by Twilio
to the caller. Only one TwiML document is rendered to the caller at once but many documents can be linked together
to build complex interactive voice applications.
Outgoing calls are controlled in the same manner as incoming calls using TwiML. The initial flow for the call is
provided as a parameter to the Twilio Cloud Connector.
Summary
| Message Processors |
|---|
|
<twiml:dial>
The verb connects the current caller to an another phone.
|
|
<twiml:gather>
The verb collects digits that a caller enters into his or her telephone keypad.
|
|
<twiml:play>
The Play verb plays an audio file back to the caller.
|
|
<twiml:record>
The verb records the caller's voice and returns to you the URL of a file containing the audio
recording.
|
|
<twiml:response>
The root element of Twilio's XML Markup is the element.
|
|
<twiml:say>
The Say verb converts text to speech that is read back to the caller.
|
|
<twiml:sms>
The verb sends an SMS message to a phone number during a phone call.
|
Message Processors
<twiml:dial>
The verb connects the current caller to an another phone. If the called party picks up, the two parties
are connected and can communicate until one hangs up. If the called party does not pick up, if a busy signal
is received, or if the number doesn't exist, the dial verb will finish.
When the dialed call ends, Twilio makes a request to the 'action' flow if provided. Call flow will continue
using the TwiML received in response to that request.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| action-flow-ref |
|
Optional. The 'action' attribute takes a flow as an argument. When the dialed call ends, Twilio will make
a request to this flow. If you provide an 'action' flow, Twilio will continue the current call after the dialed
party has hung up, using the TwiML received in your response to the 'action' URL request. Any TwiML verbs
occuring after a which specifies an 'action' attribute are unreachable.
If no 'action' is provided, Dial will finish and Twilio will move on to the next TwiML verb in the document. If
there is no next verb, Twilio will end the phone call. Note that this is different from the behavior of
and .
|
| timeout |
|
Optional. The 'timeout' attribute sets the limit in seconds that waits for the called party to
answer the call. Basically, how long should Twilio let the call ring before giving up and reporting 'no-answer'
as the 'DialCallStatus'.
|
| hangupOnStar |
|
Optional. The 'hangupOnStar' attribute lets the calling party hang up on the called party by pressing
the '*' key on his phone. When two parties are connected using , Twilio blocks execution of further verbs
until the caller or called party hangs up. This feature allows the calling party to hang up on the called party
without having to hang up her phone and ending her TwiML processing session. When the caller presses '*' Twilio
will hang up on the called party. If an 'action' URL was provided, Twilio submits 'completed' as the
'DialCallStatus' to the URL and processes the response. If no 'action' was provided Twilio will continue on to
the next verb in the current TwiML document.
|
| timeLimit |
|
Optional. The 'timeLimit' attribute sets the maximum duration of the in seconds. For example, by
setting a time limit of 120 seconds will hang up on the called party automatically two minutes into
the phone call. By default, there is a four hour time limit set on calls.
|
| callerId |
|
Optional. The 'callerId' attribute lets you specify the caller ID that will appear to the called party
when Twilio calls. By default, when you put a in your TwiML response to Twilio's inbound call request,
the caller ID that the dialed party sees is the inbound caller's caller ID.
For example, an inbound caller to your Twilio number has the caller ID 1-415-123-4567. You tell Twilio to
execute a verb to 1-858-987-6543 to handle the inbound call. The called party (1-858-987-6543) will
see 1-415-123-4567 as the caller ID on the incoming call.
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Child Elements
| nestedProcessors |
|
The response of this processor will be used as the inner content of the dial element.
|
Return Payload
- TwiML-based markup representing the Dial operation
<twiml:gather>
The verb collects digits that a caller enters into his or her telephone keypad. When the caller is
done entering data, Twilio submits that data to the provided 'action' URL in an HTTP GET or POST request, just
like a web browser submits data from an HTML form.
If no input is received before timeout, falls through to the next verb in the TwiML document.
You may optionally nest and verbs within a verb while waiting for input. This allows
you to read menu options to the caller while letting her enter a menu selection at any time. After the first
digit is received the audio will stop playing.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| action-flow-ref |
|
When the caller has finished entering digits Twilio will make a GET request to this flow including
a Digits variable which represent the digits the caller pressed, excluding the finishOnKey digit if used.
|
| timeout |
|
Optional. Sets the limit in seconds that Twilio will wait for the caller to press another digit before
moving on and making a request to the 'action' flow. For example, if 'timeout' is
'10', Twilio will wait ten seconds for the caller to press another key before submitting the previously entered
digits to the 'action' flow. Twilio waits until completing the execution of all nested verbs before beginning
the timeout period.
|
| finishOnKey |
|
Optional. The 'finishOnKey' attribute lets you choose one value that submits the received data when
entered. For example, if you set 'finishOnKey' to '#' and the user enters '1234#', Twilio will immediately
stop waiting for more input when the '#' is received and will submit "Digits=1234" to the 'action' flow.
|
| numDigits |
|
Optional. The 'numDigits' attribute lets you set the number of digits you are expecting, and submits
the data to the 'action' flow once the caller enters that number of digits. For example, one might set
'numDigits' to '5' and ask the caller to enter a 5 digit zip code. When the caller enters the fifth digit
of '94117', Twilio will immediately submit the data to the 'action' flow.
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Child Elements
| nestedProcessors |
|
Optional. The response of this processor will be used as the inner content of the gather element.
|
Return Payload
- TwiML-based markup representing the Gather operation
<twiml:play>
The Play verb plays an audio file back to the caller. Twilio retrieves the file from a URL that you provide.
- Twilio will attempt to cache the audio file the first time it is played. This means the first attempt may
be slow to play due to the time spent downloading the file from your remote server. Twilio may play a
processing sound while the file is being downloaded.
- Twilio obeys standard HTTP caching headers. If you change a file already cached by Twilio, make sure your
web server is sending the proper headers to inform us that the contents of the file have changed.
- Audio played over the telephone network is transcoded to a format the telephone network understands.
Regardless of the quality of the file you provide us, we will transcode so it plays correctly. This may result
in lower quality because the telephone number does not support high bitrate audio.
- High bitrate, lossy encoded files, such as 128kbps mp3 files, will take longer to transcode and potentially
sound worse than files that are in lossless 8kbps formats. This is due to the inevitable degradation that
occurs when converting from lossy compressed formats and the processing involved in converting from higher bit
rates to low bit rates.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| loop |
|
Optional. The 'loop' attribute specifies how many times the audio file is played. The default behavior is to play the audio once. Specifying '0' will cause the the verb to loop until the call is hung up.
|
| file |
|
Audio file to play
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Return Payload
- TwiML-based markup representing the Play operation
<twiml:record>
The verb records the caller's voice and returns to you the URL of a file containing the audio
recording. You can optionally generate text transcriptions of recorded calls by setting the 'transcribe'
attribute of the verb to 'true'.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| action-flow-ref |
|
The 'action' attribute takes an absolute or relative URL as a value. When recording is finished
Twilio will make a request to this flow. After making this request, Twilio will continue the current call using
the TwiML received in your response. There is one exception: if Twilio receives an empty recording, it will
not make a request to the 'action' URL. The current call flow will continue with the next verb in the
current TwiML document.
|
| timeout |
|
Optional. The 'timeout' attribute tells Twilio to end the recording after a number of seconds of silence
has passed. The default is 5 seconds.
|
| finishOnKey |
|
Optional. The 'finishOnKey' attribute lets you choose a set of digits that end the recording when
entered. For example, if you set 'finishOnKey' to '#' and the caller presses '#', Twilio will immediately
stop recording and submit 'RecordingUrl', 'RecordingDuration', and the '#' as parameters in a request to the
'action' flow. The allowed values are the digits 0-9, '#' and '*'. The default is '1234567890*#' (i.e. any key
will end the recording). Unlike , you may specify more than one character as a 'finishOnKey' value.
|
| maxLength |
|
Optional. The 'maxLength' attribute lets you set the maximum length for the recording in seconds. If
you set 'maxLength' to '30', the recording will automatically end after 30 seconds of recorded time has
elapsed. This defaults to 3600 seconds (one hour) for a normal recording and 120 seconds (two minutes) for
a transcribed recording.
|
| shouldTranscribe |
|
Optional. The 'transcribe' attribute tells Twilio that you would like a text representation of
the audio of the recording. Twilio will pass this recording to our speech-to-text engine and attempt to
convert the audio to human readable text. The 'transcribe' option is off by default. If you do not wish to
perform transcription, simply do not include the transcribe attribute.
|
| transcribe-flow-ref |
|
Optional. The 'transcribeCallback' attribute is used in conjunction with the 'transcribe' attribute. It
allows you to specify a flow to which Twilio will make an asynchronous request when the transcription is
complete.
|
| playBeep |
|
Optional. The 'playBeep' attribute allows you to toggle between playing a sound before the start of a
recording. If you set the value to 'false', no beep sound will be played.
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Return Payload
- TwiML-based markup representing the Record operation
<twiml:response>
The root element of Twilio's XML Markup is the element. In any TwiML response to a Twilio request,
all verb elements must be nested within this element. Any other structure is considered invalid.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| map |
|
Outbound headers
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Child Elements
| nestedProcessors |
|
Optional. The response of this processor will be used as content for the response element
|
Return Payload
- A TwiML-based markup document containing the response element.
<twiml:say>
The Say verb converts text to speech that is read back to the caller. is useful for development or saying dynamic text that is difficult to pre-record.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| lang |
|
Optional. The 'language' attribute allows you pick a voice with a specific language's accent and pronunciations. Twilio currently supports languages English, Spanish, French and German. The default is 'English'.
|
| voice |
|
Optional. The 'voice' attribute allows you to choose a male or female voice to read text back. The default value is 'man'.
|
| loop |
|
Optional. The 'loop' attribute specifies how many times you'd like the text repeated. The default is once. Specifying '0' will cause the the Say verb to loop until the call is hung up.
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Child Elements
| nestedProcessors |
|
Optional. The response of this processor will be used as the text to say.
|
Return Payload
- TwiML-based markup representing the Say operation
<twiml:sms>
The verb sends an SMS message to a phone number during a phone call.
Attributes
| config-ref |
|
Optional. Specify which configuration to use. |
| action-flow-ref |
|
Optional. The 'action' attribute takes a flow as an argument. After processing the verb, Twilio
will call this flow with the inbound headers 'SmsStatus' and 'SmsSid'. Using an 'action' flow, your application
can receive synchronous notification that the message was successfully enqueued.
|
| from |
|
Optional. The 'from' attribute takes a valid phone number as an argument. This number must be a phone
number that you've purchased from or ported to Twilio. When sending an SMS during an incoming call, 'from'
defaults to the called party. When sending an SMS during an outgoing call, 'from' defaults to the calling
party. This number must be an SMS-capable local phone number assigned to your account. If the phone number
isn't SMS-capable, then the verb will not send an SMS message.
|
| to |
|
Optional. The 'to' attribute takes a valid phone number as a value. Twilio will send an SMS message to this
number. When sending an SMS during an incoming call, 'to' defaults to the caller. When sending an SMS during
an outgoing call, 'to' defaults to the called party. The value of 'to' must be a valid phone number.
NOTE: sending to short codes is not currently supported.
|
| status-flow-ref |
|
Optional. Flow to call when SMS delivery status notification is required.
|
| retryMax |
1 |
Optional. Specify how many times this operation can be retried automatically |
Child Elements
| nestedProcessors |
|
Optional. The response of this processor will be used as the content to send via SMS.
|
Return Payload
- TwiML-based markup representing the Sms operation
