Phone Markup Language (PhoneML) - Examples
Teleku allows web developers to write phone applications with ANY programming language using the following snippets of PhoneML XML or JSON.
All you need to do is simply accept HTTP POST web requests to your Web site and respond with snippets of PhoneML XML or JSON to instruct Teleku on how
to handle the call. All requests come from Teleku as Form POST requests and include the following form fields:
- caller = the caller's phone number (Callerid/ANI)
- called = the phone number of the call (DNIS)
- callguid = unique 37 character identifier of the call
- channeltype = type of call (voice or sms)
- callerinput = the digit(s) or spoken word(s) from the caller's input
- callerinputhistory = the digit(s) and spoken word(s) from the caller's input throughout the duration of the call separated by commas
- callername = reverse phone number lookup returning the name of the caller
- callerlocation = reverse phone number lookup returning the location (city and state) of the caller
You can use these fields to find out more information about the caller and react to their touch tone or voice commands. You many also use the method attribute in the <input> and <goto> tags to designate a Form GET request if desired.
For testing purposes, you can send these results to http://teleku.com/echo to read your response variables back to the caller. You may also reference these system variables in your <speak> tags as follows:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <speak> The caller ID is @caller The number dialed by the caller is @called The call GUID is @callguid The type of call channel is @channeltype The callers last input was @callerinput The callers input string from all prompts during the call is @callerinputhistory The callers name is @callername The callers location is @callerlocation </speak> </phoneml>
Here is an example of a powerful auto attendant script in 5 lines of code. You could answer a call, play your company's jingle, announce your company's name, prompt the caller to press 1 or say Sales and ultimately transfer the call to the operator by returning the following XML to Teleku.
Note: Commands and tag attributes can be in upper, lower, or mixed case. Commands are always wrapped inside of <phoneml> XML tag. There is no looping or nesting of XML or JSON tags as in other more complex markup languages.
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <play>http://acme.com/jingle.mp3</play> <speak>Thanks for calling Acme Labs. Press 1 or say sales to be transferred to Sales or press 2 or say support to be transferred to Technical Supportotherwise stay on the call to speak with our Operator</speak> <input options="1,2,sales,support">http://acme.com/transfer</input> <speak>Transferring to Operator</speak> <transfer>602-555-1234</transfer> </phoneml>
The JSON equivalent response to the script above would look like the following:
{"phoneml":[{"play":{"$":"http://acme.com/jingle.mp3"}}, {"speak":{"$":"Thanks for calling Acme Labs. Press 1 or say sales..."}}, {"input":{"$":"http://acme.com/transfer","@options":"1,2,sales,support"}}, {"speak":{"$":"Transferring to Operator"}}, {"transfer":{"$":"602-555-1234"}}]}
Note: There is a super handy JSON validator available at http://jsonformatter.curiousconcept.com.
We currently have 7 PhoneML keywords in use today. As you can see form the example above, there are no looping logic rules or XML or JSON child node nesting requirements. Everything is based on order of operation thus simplifying web development learning curves. In the illustration above, the <play> and <speak> commands play MP3 and text-to-speech (TTS) announcements in order. The <input> command identifies the allowed caller input options and identifies the Form Action on where to submit the data on successful input. You could also specify <input>digits<digits> if you wanted to collect a string of digits like a credit card number or zip code using both touch tone and speech recognition (ASR). The <speak> and <transfer> commands after the <input> command handle the remainder of the call if no input is received from the caller.
Let's walk through the PhoneML commands below and show you examples of how you could use them in your custom phone application.
<Speak>
<Speak> allows you to speak or read text-to-speech (TTS) sentences and data to the caller.
Optional attributes include:
- bargein = boolean (true/false) - True allows callers to provide input while TTS is speaking. False forces caller to listen to the announcement. Default: true
- voice = (man/woman) - Reads text in the voice of the gender specified. Default: woman
- translate = Translates text from one language to another (Optional)
Note: The voice attribute can also be used to specify international dialect voices such as:
- Allison = English Female
- Soledad = American Spanish Female
Note: The translate attribute can translate words and paragraphs from and to languages using the following format:
- en|es = English to Spanish
- es|en = Spanish to English
- en|fr = English to French
- fr|en = French to English
- en|it = English to Italian
- it|en = Italian to English
- en|de = English to German
- de|en = German to English
- en|sv = English to Swedish
- sv|en = Swedish to English
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <speak>This is an interruptible female voice</speak> <speak voice="man" bargein="false">This is a non-interruptible male voice</speak> <speak voice="woman">This is an interruptible female voice</speak> <speak voice="soledad">Hola! Que pasa?</speak> <speak voice="soledad" translate="en|es">Hello! How are you?</speak> </phoneml>
<Play>
<Play> allows you to play MP3, WAV, or VOX audio files to the caller.
Optional attributes include:
- bargein = boolean (true/false) - True allows callers to provide input while audio file is playing. False forces caller to listen to the audio file. Default: true
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <play>http://acme.com/welcome.mp3</play> <play bargein="false">http://acme.com/welcome.wav</play> <play bargein="true">http://acme.com/welcome.vox</play> </phoneml>
<Input>
<Input> allows you to specify input options (grammars) to collect from the caller. These options can include both numeric touch tone options or words for speech recognition (ASR). Values are separated by commas. If you are interested in allowing the caller to enter or say a string of digits, you may specify free form entry as <input>digits<input>.
<Input> includes an optional action attribute to direct the collected input back to your desired URL for further processing by your application.
Optional attributes include:
- options = specifies touch tone and speech recognition keyword options to return from caller.
Options are separated by commas. Built-in touchtone and voice grammar options include:
digits - best for collecting a series of digits like a menu prompt or a credit card number
boolean - accepts yes/no and dtmf-1/dtmf-2 and returns true/false
date - grammar allows for date input in the following format: yyyymmdd (19700518), by either voice or dtmf input
currency - voice or dtmf grammar that recognizes currencies given in US dollar and cents amounts, for example, $420.03. The maximum currency setting is $100,000
number - voice or dtmf input grammar that recognizes numeric input. Note that the maximum length of detectable digits is '16'
phone - grammar will recognize any 10 digit phone number entry, including extensions, via dtmf or voice
time - grammar will recognize any standard time value entry via voice or dtmf, including AM and PM values
Default: digits (returns any touch tone or spoken digit or string of digits) - method = (post/get) - specifies the form method of the response to your application. Default: post
- Note: you can chain extensions together by referencing the desired extension in the following format - http://teleku.com/tel/extension/number such as http://teleku.com/tel/extension/6
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <input>http://acme.com/ruby/rails</input> <input options="digits">http://acme.com/ruby/rails</input> <input options="1,2,high,low">http://acme.com/processdigits.php</input> <input options="sales,support" method="get">http://acme.com/menu.aspx</input> </phoneml>
Note: you can also collect multiple inputs during the script by specifying the URL on the last <Input> tag.
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <Speak>Let's order a pizza!</Speak> <Speak>What size would you like small medium or large?</Speak> <Input options="small,medium,large,1,2,3"></Input> <Speak>How would you like the crust? thin thick or pan?</Speak> <Input options="thin,thick,pan,1,2,3">http://teleku.com/echo</Input> </phoneml>
<Record>
<Record> allows you to record an audio file and post it to your desired URL.
Optional attributes include:
- beep = boolean (true/false) - Allows you to determine whether to play beep at the beginning of the recording or not. Default: false
- playback = boolean (true/false) - Allows you to playback the recording to the caller prior to submitting the voice file for processing. Default: false
- maxlength = specifies the max length of the recording allowed in seconds. Default: 120 seconds
- maxsilence = specifies the max length of silence allowed in seconds before ending the recording. Default: 5 seconds
- Note: You can email your audio file to by including "mailto:" in front of your email address as the target address. Ninja audio files are delivered as 8kHz mono ulaw (a.k.a. G7.11) format while Samurai delivers the audio in a standard WAV format.
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <record>http://acme.com/ruby/rails</record> <record maxlength="60" maxsilence="2">http://acme.com/ruby/rails</record> <record beep="true">http://acme.com/uploadvmail.php</record> <record beep="true" playback="true">http://acme.com/uploadvmail.php</record> <record beep="true" playback="true">mailto:chris@getvocal.com</record> </phoneml>
<Transfer>
<Transfer> allows you to transfer the call to another number. Note: ";postd=ppp1234" or simply "x" can be added to the dial string to represent pauses in dialing.
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <transfer>16025551212</transfer> <transfer>16025551212;postd=ppp4444</transfer> <transfer>16025551212x4444</transfer> </phoneml>
<Goto>
<Goto> allows you redirect the flow of the voice application to another URL for processing.
Optional attributes include:
- method = (post/get) - specifies the form method of the response to your application. Default: post
- Note: you can chain extensions together by referencing the desired extension in the following format - http://teleku.com/tel/extension/number such as http://teleku.com/tel/extension/6
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <goto>http://acme.com/no_input_received.aspx</goto> <goto method="get">http://acme.com/no_input_received.php</goto> </phoneml>
<Hangup>
<Hangup> disconnects the call. You may specify a URL of your application to call for processing within the <Hangup> tags.
Optional attributes include:
- method = (post/get) - specifies the form method of the response to your application. Default: post
- Note: you can chain extensions together by referencing the desired extension in the following format - http://teleku.com/tel/extension/number such as http://teleku.com/tel/extension/6
Example:
<?xml version="1.0" encoding="UTF-8"?> <phoneml> <hangup/> <hangup method="get">http://acme.com/no_input_received.php</hangup> <hangup method="post">http://acme.com/logendofcall.aspx</hangup> </phoneml>
Outbound Dialing
SMS Applications
Need Help?