com.telapi.api.inboundxml.elements
Class Response

java.lang.Object
  com.telapi.api.inboundxml.elements.Response

public class Response
extends Object

Constructor Summary

protected

Response()

Method Summary

static Response	create() Creates a new basic response object.
String	createXml()
Response	dial(Dial dial) Adds a Dial element to a Response element.
Response	gather(Gather gather) Adds a Gather element to the current Response element.
Response	getSpeech(GetSpeech getSpeech) Adds a GetSpeech element to the current Response element.
Response	hangup() Conveniece method for creating a new Hangup element.
Response	hangup(Long schedule) Adds a Hangup element to the Response element.
Response	pause() Adds a Pause element to the Response element.
Response	pause(Long length) Adds a Pause element to the Response element.
Response	play(Long loop, String resource) Adds a Play element to a Response element.
Response	record(RecordParameters params) Convenience method for appending a new Record element.
Response	record(String action) Convenience method for appending a new Record element.
Response	record(String action, HttpMethod method, Long timeout, String finishOnKey, Long maxLength, Boolean transcribe, String transcribeCallback, Boolean playBeep, Boolean bothLegs, RecordingFileFormat fileFormat) Adds a Record element to a Response element.
Response	redirect(String url) Convenience method for creating a redirect element.
Response	redirect(String url, HttpMethod method) Adds a Redirect element to the Response element.
Response	reject() Convenience method for adding a Reject element to the current Response element.
Response	reject(RejectReason reason) Adds a Reject element to the Response element.
Response	say(String text) Convenience method for creating a Say element.
Response	say(String text, Voice voice, Long loop) Adds a Say element to a Response element.
Response	sms(String text, String to, String from) Convenience method for adding an Sms element.
Response	sms(String text, String to, String from, String action, HttpMethod method, String statusCallback) Appends an SMS Element to the current Response element.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Response

protected Response()

Method Detail

create

public static Response create()

Creates a new basic response object. This should be called at the beginning of each InboundXML generation.

Returns:

A newly generated Response element.

play

public Response play(Long loop,
                     String resource)

Adds a Play element to a Response element. The element plays an mp3 file for the caller.

Parameters:

loop - The amount of times the Play should be repeated. Zero indicates an infinite loop. The allowed values are greater than or equal to 0. Defaults to 1.

resource - The URL to the mp3 file which should be played (required).

Returns:

The Response element which is being created.

say

public Response say(String text,
                    Voice voice,
                    Long loop)

Adds a Say element to a Response element. The Say element reads text to the caller using a text-to-speech engine. Say is good to use with dynamic data, while Play may be a better choice for static information or prompts.

Parameters:

text - The text to be spoken (required).

voice - The type of voice that will read the text to the caller. Defaults to WOMAN.

loop - The amount of times the spoken text should be repeated. Zero indicates an infinite loop. The allowed values are greater than or equal to 0. Defaults to 1.

Returns:

The Response element which is being created.

say

public Response say(String text)

Convenience method for creating a Say element. Will be spoken in the WOMAN voice without looping.

Parameters:

text - The text to be spoken.

Returns:

The Response element which is being created.

record

public Response record(String action,
                       HttpMethod method,
                       Long timeout,
                       String finishOnKey,
                       Long maxLength,
                       Boolean transcribe,
                       String transcribeCallback,
                       Boolean playBeep,
                       Boolean bothLegs,
                       RecordingFileFormat fileFormat)

Adds a Record element to a Response element. The Record element is used to record audio during a call. It can occur anywhere within an InboundXML document but will only begin recording once it has been reached. This means Record would have to be the first element after Response for the entire call to be recorded. When the recording is complete, a URL of the recorded audio is created and submitted as a GET or POST to the action URL. Similar to the Gather element, a timeout value sets how much silence to allow before the recording ends, maxLength sets how long the recording may be, and the finishOnKey is used to set which keys will end the recording. By default, the action and method specify that Record should make a POST to the URL of the current InboundXML document.

Parameters:

action - URL where some parameters specific to Record will be sent for further processing (required).

method - Specifies the method to use when requesting the action or transcribeCallback URL.

timeout - The number of seconds Record should wait during silence before ending. Greater than or equal to 0. Defaults to 5.

finishOnKey - The key a caller can press to end the Record. Allowed values are 0-9, # or *. Defaults to #.

maxLength - The maximum length in seconds a recording should be. Defaults to 3600.

transcribe - Boolean value specifying if the recording should be transcribed. Defaults to false.

transcribeCallback - URL where the recording transcription will be sent. Defaults to the current InboundXML document.

playBeep - Boolean value specifying if a beep should be played when the recording begins. Defaults to false.

bothLegs - Boolean value specifying if both call legs should be recorded. Defaults to false.

fileFormat - The recording file format. Can be mp3 or wav. Default is mp3.

Returns:

The Response element which is being created.

record

public Response record(String action)

Convenience method for appending a new Record element.

Parameters:

action - URL where some parameters specific to Record will be sent for further processing (required).

Returns:

The Response element which is being created.

See Also:

record(String, HttpMethod, Long, String, Long, Boolean, String, Boolean, Boolean, RecordingFileFormat)

record

public Response record(RecordParameters params)

Convenience method for appending a new Record element.

Parameters:

params - The RecordParameters used to create the Record element.

Returns:

The Response element which is being created.

See Also:

record(String, HttpMethod, Long, String, Long, Boolean, String, Boolean, Boolean, RecordingFileFormat)

dial

public Response dial(Dial dial)

Adds a Dial element to a Response element. The Dial element starts an outgoing dial from the current call. Once the dial is complete, the next element in the InboundXML document will be processed unless the action attribute is set. In that case the result of the dial is submitted as a GET or POST (depending on the method attribute) to the action URL, and the call continues using the InboundXML of that URL. By default the outgoing call will timeout if it is not answered after 30 seconds; however, the timeout attribute can be used to set a custom time. The length of the call is limited by the timeLimit attribute, which is 4 hours (14400 seconds) by default. Setting the hangupOnStar attribute to 'true' will allow the original call to terminate the outgoing call without having to hang up by dialing '*'. The original call then continues with the current InboundXML document, or if a URL was passed, the response from the action attribute. The callerId attribute can be set to any number, and will default to the caller id of the original caller. The number to be dialed should be nested within the Dial element. For more options, use the Number or Conference elements instead of a simple phone number.

Parameters:

dial - A new Dial element which must be created by calling Dial.create(...).

Returns:

The Response element which is being created.

hangup

public Response hangup(Long schedule)

Adds a Hangup element to the Response element. The Hangup element will hangup the current call.

Parameters:

schedule - Specifies in seconds when a hangup should occur during a call. Defaults to 0

Returns:

The Response element which is being created.

hangup

public Response hangup()

Conveniece method for creating a new Hangup element.

Returns:

The Response element which is being created.

See Also:

hangup(Long)

redirect

public Response redirect(String url)

Convenience method for creating a redirect element.

Parameters:

url - The URL to which to redirect.

Returns:

The Response element which is being created.

See Also:

redirect(String, HttpMethod)

redirect

public Response redirect(String url,
                         HttpMethod method)

Adds a Redirect element to the Response element. The Redirect element directs the call to another InboundXML document. The URL of the InboundXML document is nested within the Redirect element, and the method attribute sets if the request will be a GET or a POST. In addition to the default voice request parameters, the parameter UrlBase will also be forwarded when the redirect request is made. UrlBase points to the base InboundXML document where the Redirect occurred.

Parameters:

url - The URL to which to redirect.

method - Method used to request the InboundXML doucment the call is being redirected to. Defaults to POST.

Returns:

The Response element which is being created.

reject

public Response reject(RejectReason reason)

Adds a Reject element to the Response element. The Reject element will reject an incoming call. The reason attribute determines if the caller hears a busy signal or a not-in-service message.

Parameters:

reason - The reason to list as why the call was rejected. Defaults to rejected.

Returns:

The response element which is being created.

reject

public Response reject()

Convenience method for adding a Reject element to the current Response element.

Returns:

The Response element which is being created.

See Also:

reject(RejectReason)

pause

public Response pause(Long length)

Adds a Pause element to the Response element. The Pause element will pause the call, holding for the number of seconds set by the length attribute.

Parameters:

length - The length in seconds the pause should be. Allowed values are 1 or greater. Defaults to 1.

Returns:

The Response element which is being created.

pause

public Response pause()

Adds a Pause element to the Response element. Pauses for one second.

Returns:

The response element which is being created.

See Also:

pause(Long)

sms

public Response sms(String text,
                    String to,
                    String from,
                    String action,
                    HttpMethod method,
                    String statusCallback)

Appends an SMS Element to the current Response element. TelAPI allows SMS messages to be sent during a call using the Sms element. The SMS receiver (to attribute) must be a valid phone number and the sender (from attribute) must be one of your registered TelAPI numbers. Text of the message should be placed inside the element and can not be longer than 160 characters. The action attribute can be used to direct the SMS to a new InboundXML document for processing. If directed to a new InboundXML using the action attribute, all InboundXML beneath the Sms element in the originating InboundXML document is disregarded. Similarly, the statusCallback attribute is provided to report the outcome of the SMS transmission.

Parameters:

text - The content of the SMS.

to - The phone number that will receive the SMS message (required).

from - The number that will display as sending the SMS message (required).

action - URL where parameters specific to Sms are sent.

method - Method used to request the action URL. Defaults to POST.

statusCallback - URL where the status of the SMS can be sent.

Returns:

The Response element which is being created.

sms

public Response sms(String text,
                    String to,
                    String from)

Convenience method for adding an Sms element.

Parameters:

text - The content of the SMS.

to - The phone number that will receive the SMS message (required).

from - The number that will display as sending the SMS message (required).

Returns:

The Response element which is being created.

See Also:

sms(String, String, String, String, HttpMethod, String)

gather

public Response gather(Gather gather)

Adds a Gather element to the current Response element. The Gather element allows callers to input digits to the call using their keypads which are then sent via POST or GET to a URL for further processing. There are many ways to get creative with Gather but its most common use case is in creating IVR menus. This is accomplished by nesting prompts for input from the caller using the Say or Play elements. By default an unlimited number of digits can be gathered, the Gather will timeout after 5 seconds pass without any new digits or once the '#' key is pressed, and the gathered digits will be submitted to the current InboundXML document. This default behavior of Gather can be altered using its provided element attributes.

Parameters:

gather - The Gather element to add. It must be created by calling the Gather.create(...) method.

Returns:

The Response element which is being created.

getSpeech

public Response getSpeech(GetSpeech getSpeech)

Adds a GetSpeech element to the current Response element. The GetSpeech element is used to translate a callers voice into text. That translated text is then submitted to an action URL for further processing and use in your application.

Parameters:

getSpeech - The GetSpeech element to add. It must be created by calling the GetSpeech.create(...) method.

Returns:

The Response element which is being created.

createXml

public String createXml()