com.telapi.api.inboundxml.elements
Class Dial

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

All Implemented Interfaces:

ResponseElement

@XStreamConverter(value=com.thoughtworks.xstream.converters.extended.ToAttributedValueConverter.class,
                  strings="number")
public class Dial
extends Object
implements ResponseElement

Constructor Summary

protected

Dial()

Method Summary

Dial	conference(ConferenceParameters params) Convenience method for creating a Conference element.
Dial	conference(String conferenceName) Convenience method for creating a Conference element.
Dial	conference(String conferenceName, Boolean muted, Boolean beep, Boolean startConferenceOnEnter, Boolean endConferenceOnExit, Long maxParticipants, String waitUrl, HttpMethod waitMethod, Boolean hangupOnStar, String callbackUrl, HttpMethod callbackMethod, String waitSound, HttpMethod waitSoundMethod, String digitsMatch, Boolean stayAlone) Appends a conference element to the dial element.
static Dial	createDial() Convenience method for creating a Dial element.
static Dial	createDial(DialParameters params) Convenience method for creating a Dial element.
static Dial	createDial(String number) Convenience method for creating a Dial element.
static Dial	createDial(String number, String action, HttpMethod method, Long timeout, Boolean hangupOnStar, Long timeLimit, String callerId, Boolean hideCallerId, String dialMusic, String callbackUrl, HttpMethod callbackMethod, Boolean confirmSound, String digitsMatch, Boolean straightToVm, String heartbeatUrl, HttpMethod heartbeatMethod, String forwardedFrom) Creates a new Dial element.
Dial	number(String number, String sendDigits, String url, HttpMethod callbackMethod) Creates a Number element.
Dial	sip(String sipAddress) Convenience method for creating a new Sip element.
Dial	sip(String sipAddress, String sendDigits, String url, HttpMethod method) The Sip element is nested within the Dial element, and is used to call to sip addresses.

Methods inherited from class java.lang.Object

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

Constructor Detail

Dial

protected Dial()

Method Detail

createDial

public static Dial createDial(String number,
                              String action,
                              HttpMethod method,
                              Long timeout,
                              Boolean hangupOnStar,
                              Long timeLimit,
                              String callerId,
                              Boolean hideCallerId,
                              String dialMusic,
                              String callbackUrl,
                              HttpMethod callbackMethod,
                              Boolean confirmSound,
                              String digitsMatch,
                              Boolean straightToVm,
                              String heartbeatUrl,
                              HttpMethod heartbeatMethod,
                              String forwardedFrom)

Creates a new Dial 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:

number - The number which is to be dialed. If used, no other element can be appended to the Dial element.

action - URL where some parameters specific to Dial will be sent for further processing. The calling party can be redirected here upon the hang up of the B leg caller.

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

timeout - The number of seconds calls made with are allowed silence before ending. Defaults to 30.

hangupOnStar - Boolean value specifying if pressing * should end the dial. Defaults to false.

timeLimit - The duration in seconds a call made through should occur for before ending. Defaults to 14400.

callerId - Number to display as calling. Defaults to the ID of phone being used. Defaults to the caller's caller ID.

hideCallerId - Boolean value specifying if the caller ID should be hidden or not. Defaults to false.

dialMusic - URL containing an audio file that can be played during the dial.

callbackUrl - URL requested once the dialed call connects.

callbackMethod - Method used to request the callback URL. Defaults to POST.

confirmSound - Boolean value specifying if a sound should play when dial is successful. Defaults to false.

digitsMatch - Specifies digits that TelAPI should listen for and send to the callbackUrl if a caller inputs them. Separate additional digits or digit patterns with a comma. Allowed values are digits, # and *.

straightToVm - Boolean value specifying if call should be redirected to voice mail immediately. Defaults to false.

heartbeatUrl - A URL TelAPI can request every 60 seconds during the call to notify of elapsed time and pass other general information.

heartbeatMethod - Method used to request the heartbeat URL. Defaults to POST.

forwardedFrom - Specifies the number to list the call as forwarded from.

Returns:

A new Dial element.

createDial

public static Dial createDial(DialParameters params)

Convenience method for creating a Dial element.

Parameters:

params - The parameters from which the Dial element is created.

Returns:

A new Dial element.

See Also:

#createDial(String, String, HttpMethod, Long, Boolean, Long, String, Boolean, String, String, String, HttpMethod, Boolean, String, Boolean, String, HttpMethod, String)

createDial

public static Dial createDial(String number)

Convenience method for creating a Dial element.

Parameters:

number - The number to dial.

Returns:

A new Dial element.

See Also:

#createDial(String, String, HttpMethod, Long, Boolean, Long, String, Boolean, String, String, String, HttpMethod, Boolean, String, Boolean, String, HttpMethod, String)

createDial

public static Dial createDial()

Convenience method for creating a Dial element.

Returns:

A new Dial element.

See Also:

#createDial(String, String, HttpMethod, Long, Boolean, Long, String, Boolean, String, String, String, HttpMethod, Boolean, String, Boolean, String, HttpMethod, String)

number

public Dial number(String number,
                   String sendDigits,
                   String url,
                   HttpMethod callbackMethod)

Creates a Number element. The Number element must be nested within the Dial element. It can be used to send DTFM tones or redirect to InboundXML when called parties when they are answered. Number can also be used to dial multiple phones simultaneously by using additional Number elements. If multiple Number elements are used to specify additional calls, the first call to answer is connected, and the rest of the outgoing calls are canceled.

Parameters:

number - The number to be called (required).

sendDigits - Specifies which DTFM tones to play to the called party. w indicates a half second pause.

url - URL that the called party can be directed to before the call beings.

callbackMethod - Method used to request the url. Defaults to POST.

Returns:

The Dial element to which the current Number element will be added.

conference

public Dial conference(String conferenceName,
                       Boolean muted,
                       Boolean beep,
                       Boolean startConferenceOnEnter,
                       Boolean endConferenceOnExit,
                       Long maxParticipants,
                       String waitUrl,
                       HttpMethod waitMethod,
                       Boolean hangupOnStar,
                       String callbackUrl,
                       HttpMethod callbackMethod,
                       String waitSound,
                       HttpMethod waitSoundMethod,
                       String digitsMatch,
                       Boolean stayAlone)

Appends a conference element to the dial element. Like the Number element, the Conference element is only nested within the Dial element. Instead of dialing a number, the Conference element allows the ongoing call to connect to a conference room. The conference room name is nested within the Conference element, and all calls connected to the same conference room name will be in the room together. By default all callers will hear hold music until two callers are in the room. To change this behavior, startConferenceOnEnter may be set to 'true' or 'false'. The waitUrl attribute may be used to set a custom MP3, or for greater customization, the URL of a InboundXML document to use while callers are waiting. If a InboundXML document is used, the Gather , Record and Dial elements are not allowed. When callers enter or exit the room, a beep is heard if the beep attribute is set to the default value of 'true'. A participant can be initially muted by setting the muted attribute to 'true'. The conference room can be limited to a certain number of participants by setting the maxParticipants attribute. The endConferenceOnExit attribute is used to end a conference when an specific user (or any one of many users) exits.

Parameters:

conferenceName - The conference name (required).

muted - Boolean value specifying if the conference should be muted. Defaults to false.

beep - Boolean value specifying if a beep should play upon entrance to conference. Defaults to false.

startConferenceOnEnter - Boolean value specifying if conference should begin upon entrance. Defaults to true.

endConferenceOnExit - Boolean value specifying if conference should begin upon exit. Defaults to true.

maxParticipants - The maximum number of participants allowed in the conference call. Defaults to 40.

waitUrl - URL conference participants can be sent to while they wait for entrance into the conference.

waitMethod - Method used to request waitUrl. Defaults to POST.

hangupOnStar - Boolean value specifying if pressing * should end the conference. Defaults to false.

callbackUrl - URL where some parameters specific to Conference will be sent once it is completed.

callbackMethod - Method used to request the callback URL. Defaults to POST.

waitSound - URL to sound that can be played while waiting to enter the conference.

waitSoundMethod - Method used to request the waitsound URL. Defaults to POST.

digitsMatch - Specifies digits that TelAPI should listen for and send to the callbackUrl if a caller inputs them. Seperate additional digits or digit patterns with a comma. Can be a digit, # or *.

stayAlone - Boolean value specifying if the caller should stay alone in the conference call. Defaults to true.

Returns:

The Dial element to which the current Conference element will be added.

conference

public Dial conference(String conferenceName)

Convenience method for creating a Conference element.

Parameters:

conferenceName - The name of the created Conference.

Returns:

The Dial element to which the current Conference element will be added.

See Also:

conference(String, Boolean, Boolean, Boolean, Boolean, Long, String, HttpMethod, Boolean, String, HttpMethod, String, HttpMethod, String, Boolean)

conference

public Dial conference(ConferenceParameters params)

Convenience method for creating a Conference element.

Parameters:

params - The parameters from which the Conference element is created.

Returns:

The Dial element to which the current Conference element will be added.

See Also:

conference(String, Boolean, Boolean, Boolean, Boolean, Long, String, HttpMethod, Boolean, String, HttpMethod, String, HttpMethod, String, Boolean)

sip

public Dial sip(String sipAddress,
                String sendDigits,
                String url,
                HttpMethod method)

The Sip element is nested within the Dial element, and is used to call to sip addresses. The desired sip address to call is nested within the opening and closing Sip elements, just as with a number when using the Number element. The opening and closing sip tags may be omitted completely by simply prefixing the desired sip address with "sip:" when using it within the Dial element like so: Dialsip:username@domain.comDial. If multiple Sip elements are used, the first call to answer is connected, and the rest of the outgoing calls are canceled.

Parameters:

sipAddress - The sip address (required).

sendDigits - Specifies which DTFM tones to play to the called party. w indicates a half second pause. Allowed values are numbers, and w.

url - URL that the called party can be directed to before the call beings.

method - Method used to request the url. Defaults to POST.

Returns:

The Dial element to which the current Sip element will be added.

sip

public Dial sip(String sipAddress)

Convenience method for creating a new Sip element.

Parameters:

sipAddress - The sip address (required).

Returns:

The Dial element to which the current Sip element will be added.

See Also:

sip(String, String, String, HttpMethod)