Tropo Scripting Development Guide

Method Summary

Methods	Parameters	Events	Return Values
answer	timeout	none	none
ask	allowSignals, attempts, bargein, choices, interdigitTimeout, minConfidence, mode, onBadChoice, onChoice, onError, onEvent, onHangup, onSignal, onTimeout, recognizer, terminator, text, timeout, voice	Events	Return Values
call	allowSignals, answerOnMedia, callerID, channel, destination, headers, network, onAnswer, onCallFailure, onError, onSignal, onTimeout, recordFormat, recordMethod, recordURI, timeout	Events	Return Values
conference	allowSignals, conferenceId, interdigitTimeout, mute, onChoice, onSignal, playTones, terminator	Events	none
getHeader	none	none	none
hangup	none	none	none
log	string	none	none
message	callerID, channel, network, text, timeout, to	none	none
record	allowSignals, attempts, bargein, beep, interdigitTimeout, maxTime, onError, onEvent, onHangup, onRecord, onSignal, onTimeout, recordFormat, recordMethod, recordPassword, recordURI, recordUser, silenceTimeout, terminator, text, timeout, transcriptionID, transcriptionOutFormat, transcriptionOutURI, voice	Events	Return Values
redirect	destination	none	none
reject	none	none	none
say	allowSignals, onSignal, text, voice	none	none
startCallRecording	format, method, recordPassword, recordUser, transcriptionEmailFormat, transcriptionID, transcriptionOutURI, uri	none	none
stopCallRecording	none	none	none
transfer	allowSignals, answerOnMedia, callerID, destination, headers, interdigitTimeout, onCallFailure, onError, onSignal, onSuccess, onTimeout, playrepeat, playvalue, terminator, timeout, voice	Events	Return Values
wait	allowSignals, milliseconds, onSignal	none	none

This is the amount of time in seconds (can be a fraction, e.g. 10.34) Tropo will wait for an acknowledgment from the telephone carrier before timing out.

Optional method that answers or 'picks up' an incoming call.

This parameter allows you to assign a signal to this function. Events from the Tropo REST API with a matching signal name will "interrupt" the function (i.e., stop it from running). If it already ran and completed, your interrupt request will be ignored. If the function has not run yet, the interrupt will be queued until it does run.

By default, allowSignals will accept any signal as valid; if you define allowSignals as "", it defines the function as "uninterruptible". You can also use an array - the function will stop if it receives an interrupt signal matching any of the names in the array.

This defines the total amount of times the user will hear the prompt before the ask ends in either a nomatch or noinput.

The bargein attribute specifies whether or not the caller will be able to interrupt the TTS/audio output with a touch tone phone keypress or voice utterance. A value of 'true' indicates that the user is allowed to interrupt, while a value of 'false' forces the caller to listen to the entire prompt before being allowed to give input to the application. If using Python, make sure to use True and False instead of true and false.

The choices field defines a simple grammar that will be active for the prompting of the user for input. For more information, review the Asking a Question and Working with Simple Grammar Quickstarts.

With ask, interdigitTimeout defines how long to wait - in seconds - between key presses to determine the user has stopped entering input. This is useful to allow to help users restart the process if they mistyped, or to slim down the wait time experienced by the user if you need to get a variable amount of digits (enter you 4 or 5 digit pin code, for example).

If the interdigitTimeout is hit, it will trigger the onBadChoice event.

This is the minimum amount of confidence that the "recognizer" must have before matching a response to a choice. As an example, if your grammar defines the choices as red, blue and green, and someone says "rud", a particular confidence will be set identifying how likely "rud" was meant to be "red". This is expressed in a Float as a rate between 0 and 1.

The type of caller input allowed for voice calls. This can be 'dtmf' (touch-tone input), 'speech' or 'any'.

This registers an event handler that fires when the number of attempts have been exhausted without a valid response from the user.

This registers an event handler that fires when a valid response is provided by a user.

This registers an event handler that fires when a system error (a non-user error) occurs during input. See onBadChoice and onTimeout for information on how to handle user errors.

This registers an event handler that fires as a catch all for all events. This essentially means onEvent is executed after any other event handler, so if (for example) a timeout occurs, onTimeout is executed, then onEvent is executed and then the verb returns. If no other event handler is defined, onEvent will still fire.

This registers an event handler that fires when the user disconnects or hangs up.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

This event fires when the user doesn't respond to the prompt within a specified period of time.

Recognizer tells Tropo what language to listen for; the available options can be found here (there's quite a few).

This is the touch-tone key (also known as "DTMF digit") that indicates the end of input. A common use of the terminator is the # key, eg: "Please enter your five digit zip code, then press the pound key."

In the case of a voice session, this can either be the text to be rendered by the Text to Speech Engine (may also be SSML), or a URL to an audio file to be played. In the case of a text messaging session, this will be the text to be sent to the user.

The amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response. The maximum value for this parameter is 2 hours.

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

choice, error, event, hangup, timeout

event

Ask is essentially a say that requires input; it requests information from the caller and waits for a response.

If set to true, the call will be considered "answered" and audio will begin playing as soon as media is received from the far end (ringing / busy signal / etc). If using Python, make sure to use True and False instead of true and false. Note that since the call is considered "answered", the onTimeout event will never fire and the onAnswer event will fire on first ring.

The Caller ID for the session's origin. For example, if the number (407)555-1212 called (407)555-1000, the *1212 number would be the callerID. This also applies to IM account names; if IM account 'tropocloud' sends a message to 'foobar123', the callerID would be 'tropocloud'.

The callerID can be manually set to a specific number; for voice calls, this can be any valid phone number, though for SMS and IM it must be a number/ID assigned to your account.

Channel tells Tropo whether the call is "voice" or "text". This is not a required field and is actually often unnecessary - in most cases, Tropo is able to determine the channel based on the network. Channel is primarily used to split an inbound oriented application into different sets of instructions - one set for any input that comes in via text and a different set for input that comes in over voice.

The destination to make a call to or send a message to. This may currently take one of the following forms:

+14155551212 - The telephone number to dial with a '+' and country code.
tel:+14155551212 - The telephone number with a tel: prefix
sip:username@doamin.com - The SIP URI to dial
username - The IM or Twitter user name.

Some IM networks like Google Talk and Live Messenger include a domain as part of the user name. For those networks, include the domain: username@gmail.com

When making a voice call, you can specify dialing options as part of the number:

postd - The DTMF digits to dial after the call has connected
pause - The amount of time to wait before issuing the digits after the call is connected
Example: "+14155551212;postd=1234pp56;pause=1000ms". This will dial 1234 one second after connecting to the phone number, pause for an additional 2 seconds (pp) and then dial 56

As mentioned in the main description, you can also list multiple phone numbers or SIP addresses (or both!) as an array for a voice call; whichever destination picks up first, wins.

A hash containing SIP headers used when making the call. This parameter only applies when making SIP calls.

The name of the network being used for this session. For voice, this can be 'PSTN", "SIP", "SKYPE" or "INUM". For text, this can be "AIM", "GTALK", "JABBER", "MSN", "SMS", "TWITTER" or "YAHOO". While "SKYPE" is a valid network, it will not be used for an outbound call, as Skype does not allow calls to standard Skype IDs. it's only valid for inbound calls.

Network is used mainly by the text channels; for IM network, you must have an IM account linked in your app. For example, if you try to send to AIM when you don't have an AIM username included in your app, your app will fail. TWITTER is a valid network, but as Twitter is currently only supported for inbound applications, it would not be used here.

This registers an event handler that fires when the call is answered.

This event fires when an outbound call or a transfer fails, often due to an incorrect or disconnected destination phone number.

This registers an event handler that fires when a system error (a non-user error) occurs during input. See onBadChoice and onTimeout for information on how to handle user errors.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

This event fires when the call is not answered within a specified period of time.

The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'.

When submitting recordings via HTTP, this parameter determines the method used. This can be 'POST' (which is the default) or 'PUT' . When sending via POST, the name of the form field is "filename".

The FTP or HTTP URL to send the recorded audio file. When sending via POST, the name of the form field is "filename".

Timeout only applies to the voice channel and determines the amount of time Tropo will wait - in seconds - for the call to be answered before giving up. The maximum value for this parameter is 2 hours; it's recommended for outbound voice calls that this be set somewhere between 50-90 seconds. This ensures if one carrier cannot connect the call for whatever reason, there is time to try it on another carrier.

badChoice, callFailure, error, event, timeout

callObject, event

Initiates an outbound call or a text conversation.

This is the unique ID number that identifies the conference and is used by the calls to connect into the same conference session.

For conference, record and transfer, interdigitTimeout defines how long the user needs to wait - in seconds - before Tropo will recognize another key press. Essentially, this means if a user presses the wrong key to terminate the session (say * instead of #), how long do you want Tropo to wait before letting them try again.

If set to true, the user will be muted in the conference. If using Python, make sure to use True and False instead of true and false.

This registers an event handler that fires if the terminator is used to disconnect instead of hanging up.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

Identifies whether or not conference members can hear the tone generated when a a key on the phone is pressed. If using Python, make sure to use True and False instead of true and false.

This is the touch-tone key (also known as "DTMF digit") used to exit the conference.

event

This joins two or more calls together so they can communicate simultaneously

This fetches a particular SIP header for a call.

This instructs Tropo to disconnect the current call; it is optional.

This is the parameter that designates the string to send to the debugger.

This function outputs a single string of debugging text to Tropo's application debugger.

How long Tropo will wait - in seconds - for an answer, busy signal, or other event to occur. The maximum value for this parameter is 2 hours; it's recommended for outbound voice calls that this be set somewhere between 50-90 seconds. This ensures if one carrier cannot connect the call for whatever reason, there is time to try it on another carrier.

The destination to make a call to or send a message to. This may currently take one of the following forms:

+14155551212 - The telephone number to dial with a '+' and country code.
tel:+14155551212 - The telephone number with a tel: prefix
sip:username@doamin.com - The SIP URI to dial
username - The IM or Twitter user name.

postd - The DTMF digits to dial after the call has connected
pause - The amount of time to wait before issuing the digits after the call is connected
Example: "+14155551212;postd=1234pp56;pause=1000ms". This will dial 1234 one second after connecting to the phone number, pause for an additional 2 seconds (pp) and then dial 56

As mentioned in the main description, you can also list multiple phone numbers or SIP addresses (or both!) as an array for a voice call; whichever destination picks up first, wins.

This is a shortcut function to create a call or text message, say something, then disconnect - all in one step.

This defines the total amount of times the user will hear the prompt before the record ends in either a nomatch or noinput.

When set to true, callers will hear a tone indicating the recording has begun. If using Python, make sure to use True and False instead of true and false.

The maximum amount of time (in seconds) allowed for a recording. Defaults to 30 seconds, but may be set up to 2 hours in length (Tropo disconnects any session that exceeds 2 hours long, effectively reducing the possible recording to 2 hours as well).

This registers an event handler that fires when a system error (a non-user error) occurs during input. See onBadChoice and onTimeout for information on how to handle user errors.

This registers an event handler that fires when the user disconnects or hangs up.

This registers an event handler that fires when a recording of the input is complete.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

This event fires when the user doesn't begin speaking within a specific period of time, once the record prompt and/or beep is played.

The audio format used for the recording; values can be 'audio/wav', 'audio/mp3' or 'audio/au'.

When submitting recordings via HTTP, this parameter determines the method used. This can be 'POST' (which is the default) or 'PUT' . When sending via POST, the name of the form field is "filename".

When using FTP, this indicates the FTP password.

The FTP or HTTP URL to send the recorded audio file. When sending via POST, the name of the form field is "filename".

When using FTP, this is the FTP account username

Note: If the user and password field in the URL contains one of these characters : or @ or /, the character must be encoded.

The amount of time, after the caller is done speaking, before the user's response is considered done. Applies only to voice input.

This is the touch-tone key (also known as "DTMF digit") that stops the recording.

This can either be the text to be rendered by the Text to Speech Engine (may also be SSML), or a URL to an audio file to be played.

The amount of time Tropo will wait--in seconds and after sending or playing the prompt--for the user to begin a response. The maximum value for this parameter is 2 hours.

User definable ID that can be included when the transcription is posted to transcriptionOutURI.

The formatting for the transcription that will be sent to your transcription URI - either 'xml' or 'json'.

The e-mail address or HTTP URL to send the transcription results to; the transcription arrives as the content of the HTTP POST, as opposed to a header, named field or variable.

Note: Email addresses must be prefaced with mailto: if used (mailto:you@example.com)

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

error, event, hangup, record, timeout

event

Used to request input from the caller and records any audible response.

The new SIP destination for the incoming call as a URL:

sip:9991436228@sip.tropo.com

This is used to deflect the call to a different third party SIP address.

Rejects the incoming call.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

Says something to the user.

The format to record in. This can be either 'audio/wav', 'audio/mp3' or 'audio/au'.

The method for submitting recording audio. This may be 'POST' or 'PUT'.

When using FTP, this indicates the FTP password.

When using FTP, this is the FTP account username

Note: If the user and password field in the URL contains one of these characters : or @ or /, the character must be encoded.

Specifies the encoding used when delivering transcriptions via e-mail. Values can be "plain" or "encoded".

User definable ID that can be included when the transcription is posted to transcriptionOutURI.

Required URI parameter that specifies where to send the file after the recording is completed. Can be an HTTP or FTP URI.

startCallRecording allows Tropo applications to begin recording the current call. The resulting recording may then be sent via FTP or an HTTP POST/Multipart Form.

If startCallRecording is used, this will stop the call recording. If call recording is not enabled, this will do nothing. For more information, see the Recording the Entire Call example.

The new destination for the incoming call as a URL, in one of two forms:

Telephone number: +14155551212 (requires + and the country code)
SIP Address: sip:9991436228@sip.tropo.com

You can specify dialing options as part of the number:

postd - The DTMF digits to dial after the call has connected
pause - The amount of time to wait before issuing the digits after the call is connected
Example: "+14155551212;postd=1234pp56;pause=1000ms". This will dial 1234 one second after connecting to the phone number, pause for an additional 2 seconds (pp) and then dial 56

As mentioned in the main description, you can also list multiple phone numbers or SIP addresses (or both!) as an array; whichever destination picks up first, wins.

A hash containing SIP headers used when making the call. This parameter only applies when making SIP calls.

This event fires when an outbound call or a transfer fails, often due to an incorrect or disconnected destination phone number.

This registers an event handler that fires when a system error (a non-user error) occurs during the transfer.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

This registers an event handler that fires when the call is successfully transferred to the new destination.

This event fires when the person at the other end of the transfer doesn't answer within a specified period of time.

This defines the total amount of times the audio file specified by playvalue will repeat itself.

The audio file specified by this parameter will be played to the existing call. This could be "hold music", a ring-back sound, etc. Note that this file needs to be an absolute reference as opposed to a relative reference - i.e. if you host a file on our servers, it would need to be http://www.tropo.com/www/audio/hold_music.mp3, not just hold_music.mp3. For more information, check out Hosting Audio Files.

This is the touch-tone key (also know as "DTMF digit") that cancels the transfer. The terminator is only active when the call is ringing, it won't do anything once the call is connected.

Specifies the voice to be used when speaking text back to a user.

A full list of possible voices can be found here (there's many, many options).

callFailure, error, success, timeout

event

This will transfer an already answered call to another destination / phone number.

This defines the time to wait for a state change. Defaults to 0ms if the parameter is skipped.

This specifies a callback function to run if the function is interrupted by a signal. Review documentation on sending interrupts here.

The wait function (use "await" in Groovy) suspends the script's current thread of execution for the specified length of time, or until the active session changes state (such as a user hanging up), whichever occurs first.