com.hoiio.sdk.services
Class IvrService

java.lang.Object
  extended by com.hoiio.sdk.services.HttpService
      extended by com.hoiio.sdk.services.IvrService

public class IvrService
extends HttpService

Interactive voice responses (IVR) menus allows you to interact with your users through a voice call. You will be able to play a series of voice dialogs and your users will be able to respond via their telephone keypad. A common use case is a Customer Helpline where you might hear:
"For sales enquiry, please press 1. For technical support, please press 2. To speak to our customer service officers, please press 0."
Hoiio's IVR API allows developers to easily create IVR menus like the above using RESTful APIs. This can be achieved without the need for technical telecommunication knowledge. Coupled with our Hoiio Numbers and Text-to-Speech (TTS) technology, you can get started instantly without hassle.

For more info please refer to: http://developer.hoiio.com/docs/ivr.html


Constructor Summary
IvrService(String appId, String accessToken)
          Constructs the service to make all IVR requests
 
Method Summary
 Dial dial(String dest)
          Makes a dial-out to a destination number
 Dial dial(String dest, String msg, String callerID, String tag, String notifyUrl)
          Makes a dial-out to a destination number
 Gather gather(String session, String notifyUrl)
          Gets user input via the telephone's keypad in IVR calls
 Gather gather(String session, String notifyUrl, String msg, Integer maxDigits, Integer timeout, Integer attempts, String tag)
          Gets user input via the telephone's keypad in IVR calls
 String getSession(String request)
          Parses the JSON request to get the IVR session
 Hangup hangup(String session)
          Hangs up the current call
 Hangup hangup(String session, String msg, String tag, String notifyUrl)
          Hangs up the current call
 Monitor monitor(String session, String notifyUrl)
          Records the call conversation, including any voice messages
 Monitor monitor(String session, String notifyUrl, String msg, String tag)
          Records the call conversation, including any voice messages
 Play play(String session)
          Plays a voice message
 Play play(String session, String msg, String tag, String notifyUrl)
          Plays a voice message
 Record record(String session, String notifyUrl)
          Records voice messages from the user over the phone
 Record record(String session, String notifyUrl, String msg, Integer maxDuration, String tag)
          Records voice messages from the user over the phone
 Transfer transfer(String session, String dest)
          Transfers the current call to another destination number anywhere in the world or a voice conference room
 Transfer transfer(String session, String dest, String msg, String callerID, TransferOnFailture onFailure, String tag, String notifyUrl)
          Transfers the current call to another destination number anywhere in the world or a voice conference room
 
Methods inherited from class java.lang.Object
equals, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
 

Constructor Detail

IvrService

public IvrService(String appId,
                  String accessToken)
Constructs the service to make all IVR requests

Parameters:
appId - AppID of the developer
accessToken - AccessToken of the developer
Method Detail

dial

public Dial dial(String dest)
          throws HoiioException
Makes a dial-out to a destination number

Parameters:
dest - The destination number to call. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

dial

public Dial dial(String dest,
                 String msg,
                 String callerID,
                 String tag,
                 String notifyUrl)
          throws HoiioException
Makes a dial-out to a destination number

Parameters:
dest - The destination number to call. Phone numbers should start with a "+" and country code (E.164 format), e.g. +6511111111.
msg - (optional) The message that you want to play after the call is answered. Max 500 characters.
callerID - (optional) This is the Caller ID that the destination number will see on their incoming call.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notifyUrl - (optional) A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. If omitted, the call will hang up after msg is played, and the notification will not be sent to you.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

gather

public Gather gather(String session,
                     String notifyUrl)
              throws HoiioException
Gets user input via the telephone's keypad in IVR calls

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

gather

public Gather gather(String session,
                     String notifyUrl,
                     String msg,
                     Integer maxDigits,
                     Integer timeout,
                     Integer attempts,
                     String tag)
              throws HoiioException
Gets user input via the telephone's keypad in IVR calls

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution.
msg - (optional) This is the message that you want to play to instruct the user to enter their input. Max 500 characters.
maxDigits - (optional) The maximum number of digits to gather. Once the user has input the maximum number of digits, the input will end. Users can also press # to end the input at any time.
timeout - (optional) The time (in seconds) that the user has to input his response. When timeout is reached, whatever the user has inputted up to that point will be the user's response.
attempts - (optional) The number of attempts that the user has to input his response.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

getSession

public String getSession(String request)
Parses the JSON request to get the IVR session

Parameters:
request - the POST request sent from Hoiio to developer's notify URL in JSON format
Returns:
The IVR session for this particular call

hangup

public Hangup hangup(String session)
              throws HoiioException
Hangs up the current call

Parameters:
session - The unique session ID for this particular call.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

hangup

public Hangup hangup(String session,
                     String msg,
                     String tag,
                     String notifyUrl)
              throws HoiioException
Hangs up the current call

Parameters:
session - The unique session ID for this particular call.
msg - (optional) This message will be played to the user before the call is hangup. Max 500 characters.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notifyUrl - (optional) A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. If omitted, the notification will not be sent to you.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

monitor

public Monitor monitor(String session,
                       String notifyUrl)
                throws HoiioException
Records the call conversation, including any voice messages

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution
Returns:
Object containing all the responses from the server
Throws:
HoiioException

monitor

public Monitor monitor(String session,
                       String notifyUrl,
                       String msg,
                       String tag)
                throws HoiioException
Records the call conversation, including any voice messages

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution
msg - (optional) This is the message that you want to play to inform the user before the start of the recording. Max 500 characters.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

play

public Play play(String session)
          throws HoiioException
Plays a voice message

Parameters:
session - The unique session ID for this particular call.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

play

public Play play(String session,
                 String msg,
                 String tag,
                 String notifyUrl)
          throws HoiioException
Plays a voice message

Parameters:
session - The unique session ID for this particular call.
msg - (optional) This is the message that you want to play to the user. Max 500 characters.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notifyUrl - (optional) A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. If omitted, the call will hang up after msg is played, and the notification will not be sent to you.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

record

public Record record(String session,
                     String notifyUrl)
              throws HoiioException
Records voice messages from the user over the phone

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution
Returns:
Object containing all the responses from the server
Throws:
HoiioException

record

public Record record(String session,
                     String notifyUrl,
                     String msg,
                     Integer maxDuration,
                     String tag)
              throws HoiioException
Records voice messages from the user over the phone

Parameters:
session - The unique session ID for this particular call.
notifyUrl - A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution
msg - (optional) This is the message that you want to play to inform the user before the start of the recording. Max 500 characters.
maxDuration - (optional) The maximum duration in seconds of the recording. Once the recording limit is reached, the call will automatically move on to the next IVR block.
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

transfer

public Transfer transfer(String session,
                         String dest)
                  throws HoiioException
Transfers the current call to another destination number anywhere in the world or a voice conference room

Parameters:
session - The unique session ID for this particular call.
dest - The destination to transfer the call to. This can be either a E.164 format destination number (start with a "+" and country code, e.g. +6511111111) or a conference room ID.
Returns:
Object containing all the responses from the server
Throws:
HoiioException

transfer

public Transfer transfer(String session,
                         String dest,
                         String msg,
                         String callerID,
                         TransferOnFailture onFailure,
                         String tag,
                         String notifyUrl)
                  throws HoiioException
Transfers the current call to another destination number anywhere in the world or a voice conference room

Parameters:
session - The unique session ID for this particular call.
dest - The destination to transfer the call to. This can be either a E.164 format destination number (start with a "+" and country code, e.g. +6511111111) or a conference room ID.
msg - (optional) This is the message that you want to play to the user before the call is transferred. Max 500 characters.
callerID - (optional) This is the Caller ID that the destination number will see on their incoming call.
onFailure - (optional) Action to perform if the transfer fails: hangup, continue
tag - (optional) This is a text string containing your own reference ID for this transaction. This value will be included in the response for Notification for your reference. Max 256 characters.
notifyUrl - (optional) A fully-qualified HTTP/S URL on your web server to be notified when this action has completed execution. If omitted, the notification will not be sent to you.
Returns:
Object containing all the responses from the server
Throws:
HoiioException