com.askfast.askfastapi

Class AskFastRestClient

java.lang.Object

com.askfast.askfastapi.AskFastRestClient

public class AskFastRestClient
extends Object

A client that gives access to the Ask Fast REST API. An accountId and accessToken are required to access the REST API. If you do not pass an accessToken, make sure to pass a valid refreshToken, as the class tries to retrieve a fresh accessToken at the key server.
This REST client uses Retrofit. Make sure to wrap every call with a try/catch, as an exception could be thrown when the request fails.

Field Summary

Fields

Modifier and Type	Field and Description
static String	DEFAULT_ENDPOINT
static String	KEYSERVER_PATH

Constructor Summary

Constructors

Constructor and Description
AskFastRestClient(String accountId, String refreshToken) Creates an AskFastRestClient instance.
AskFastRestClient(String accountId, String refreshToken, String accessToken) Creates an AskFastRestClient instance.
AskFastRestClient(String accountId, String refreshToken, String accessToken, String endpoint) Creates an AskFastRestClient instance.

Method Summary

Methods

Modifier and Type	Method and Description
protected static <T> Set<T>	asOrderedSet(List<T> src)
void	buyAdapter(String adapterId) Buy an adapter.
Dialog	createDialog(Dialog dialog) Create a dialog.
String	getAccessToken() Returns the access token.
Adapter	getAdapter(String adapterId) Returns the corresponding adapter by id
Set<Adapter>	getAdapters(String type) Returns a set of Adapters, optionally narrowed down by a type.
Set<Adapter>	getAllAdapters(String type) Returns adapters owned by your account and shared with your account.
List<Adapter>	getCapableAdapters(String type)
Integer	getDDRRecordCount(Collection<String> adapterIds, Collection<String> adapterTypes, String fromAddress, String typeId, String status, Long startTime, Long endTime, String delimitedSessionKeys, Integer offset) A faster fetch of the aggregation of all quantities in the DDRRecord.getQuantity() based on the filtering criteria given
List<DDRRecord>	getDDRRecords(Collection<String> adapterIds, Collection<String> adapterTypes, String fromAddress, String typeId, String status, Long startTime, Long endTime, String delimitedSessionKeys, Integer offset, Integer limit, Boolean shouldGenerateCosts, Boolean shouldIncludeServiceCosts) Returns a list of DDRRecords based on the give parameters.
Dialog	getDialog(String dialogId) Retrieve a dialog by its id.
Set<Dialog>	getDialogs() Returns the list of dialogs.
Set<Dialog>	getDialogsByName(String name)
Set<Adapter>	getFreeAdapters(String adapterType, String address) Gets all the free adapters
List<Recording>	getRecordings() Get all the recordings of the current accountId
List<Recording>	getRecordings(String accountId) Get all the recordings linked to the specified account.
String	getRefreshToken() Returns the refresh token
RestResponse	modifyCall(String sessionId, String url) Modify the existing call
RestResponse	redirectCallToAnotherNumber(String sessionId, String number) Redirect the call to another number
void	removeAdapter(String adapterId) Remove an adapter from the logged in account.
void	removeDialog(String dialogId) Delete a dialog.
Result	startDialog(Map<String,String> addressMap, Map<String,String> addressCcMap, Map<String,String> addressBccMap, AdapterType adapterType, String adapterID, String senderName, String subject, String url) Initiates a broadcast dialog request from a given adapterId.
Result	startDialog(String toAddress, AdapterType adapterType, String senderName, String subject, String url) Initiates a dialog request from a given adapterId.
Result	startDialog(String toAddress, String adapterId, String senderName, String subject, String url) Initiates a dialog request from a given adapterId.
Result	startEmailDialog(String toAddress, String senderName, String subject, String url) Initiate an Email request from a random Email adapter.
Result	startPhoneDialog(String toAddress, String url) Initiate a phone call from a random call adapter.
Result	startSMSDialog(String toAddress, String senderName, String url) Initiate an SMS request from a random SMS adapter.
Adapter	updateAdapter(String adapterId, Adapter adapter) Updates the adapter with the given adapterId.
Dialog	updateDialog(String dialogId, Dialog dialog) Update a dialog.

Methods inherited from class java.lang.Object

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

Field Detail

DEFAULT_ENDPOINT

public static final String DEFAULT_ENDPOINT

See Also:

Constant Field Values

KEYSERVER_PATH

public static final String KEYSERVER_PATH

See Also:

Constant Field Values

Constructor Detail

AskFastRestClient

public AskFastRestClient(String accountId,
                 String refreshToken)

Creates an AskFastRestClient instance. The accessToken will be retrieved from the key server using your accountId and refreshToken.

Parameters:

accountId - Your accountId

refreshToken - Your refreshToken

AskFastRestClient

public AskFastRestClient(String accountId,
                 String refreshToken,
                 String accessToken)

Creates an AskFastRestClient instance. Be sure the accessToken is valid, otherwise any request will fail and most likely throw an exception. The accessToken is not automatically refreshed.

Parameters:

accountId - Your accountId

refreshToken - Your refreshToken

accessToken - The access token

AskFastRestClient

public AskFastRestClient(String accountId,
                 String refreshToken,
                 String accessToken,
                 String endpoint)

Creates an AskFastRestClient instance. Be sure the accessToken is valid, otherwise any request will fail and most likely throw an exception. The accessToken is not automatically refreshed.

Parameters:

accountId - Your accountId

refreshToken - Your refreshToken

accessToken - The access token

endpoint - The endpoint, the url of API endpoint you wish to use. (The default is set to: https://api.ask-fast.com)

Method Detail

startPhoneDialog

public Result startPhoneDialog(String toAddress,
                      String url)

Initiate a phone call from a random call adapter.

Parameters:

toAddress - The address which will be called

url - This can be one of:
1. http(s) endpoint fetching a Question json as response.
2. A standard text prefixed by keyword: text://your message. This will be transformed to a Question.QUESTION_TYPE_COMMENT
3. A unique dialogId as defined in the ASK-Fast Portal or by method createDialog(Dialog) method

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

startSMSDialog

public Result startSMSDialog(String toAddress,
                    String senderName,
                    String url)

Initiate an SMS request from a random SMS adapter.

Parameters:

toAddress - The mobile number to which an SMS is to be sent

senderName - A senderName can be attached for medium types: SMS, EMAIL. For SMS, the length should not exceed 11 charecters.

url - This can be one of:
1. http(s) endpoint fetching a Question json as response.
2. A standard text prefixed by keyword: text://your message. This will be transformed to a Question.QUESTION_TYPE_COMMENT
3. A unique dialogId as defined in the ASK-Fast Portal or by method createDialog(Dialog) method

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

startEmailDialog

public Result startEmailDialog(String toAddress,
                      String senderName,
                      String subject,
                      String url)

Initiate an Email request from a random Email adapter.

Parameters:

toAddress - An email address to which an email is to be sent

senderName - A senderName can be attached for medium types: SMS, EMAIL. For SMS, the length should not exceed 11 charecters. * @param subject Only valid for an email adapter. The subject of the message to be sent

subject - Only valid for an email adapter. The subject of the message to be sent

url - This can be one of:
1. http(s) endpoint fetching a Question json as response.
2. A standard text prefixed by keyword: text://your message. This will be transformed to a Question.QUESTION_TYPE_COMMENT
3. A unique dialogId as defined in the ASK-Fast Portal or by method createDialog(Dialog) method

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

startDialog

public Result startDialog(String toAddress,
                 String adapterId,
                 String senderName,
                 String subject,
                 String url)

Initiates a dialog request from a given adapterId.

Parameters:

toAddress - The address for which an outbound dialog request is requested to be initiated.

adapterId - Specific adapterId (channel or communication mode) that is either owned by you, or that you are a shared user of.

senderName - A senderName can be attached for medium types: SMS, EMAIL. For SMS, the length should not exceed 11 charecters.

subject - Only valid for an email adapter. The subject of the message to be sent

url - This can be one of:
1. http(s) endpoint fetching a Question json as response.
2. A standard text prefixed by keyword: text://your message. This will be transformed to a Question.QUESTION_TYPE_COMMENT
3. A unique dialogId as defined in the ASK-Fast Portal or by method createDialog(Dialog) method

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

startDialog

public Result startDialog(String toAddress,
                 AdapterType adapterType,
                 String senderName,
                 String subject,
                 String url)

Initiates a dialog request from a given adapterId. This will pick up the first random adapter of the given type, in case of multiple adapters of the same type.

Parameters:

toAddress - The address for which an outbound dialog request is requested to be initiated.

adapterType - The type of the communication for which a dialog is initiated. E.g. Call, SMS, Email etc

senderName - A senderName can be attached for medium types: SMS, EMAIL. For SMS, the length should not exceed 11 charecters.

subject - Only valid for an email adapter. The subject of the message to be sent

url - The url used to load the dialog. This can also be a dialogId

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

startDialog

public Result startDialog(Map<String,String> addressMap,
                 Map<String,String> addressCcMap,
                 Map<String,String> addressBccMap,
                 AdapterType adapterType,
                 String adapterID,
                 String senderName,
                 String subject,
                 String url)

Initiates a broadcast dialog request from a given adapterId.

Parameters:

addressMap - The key value pairs of {toAddress, recipientName}

addressCcMap - The key value pairs of {ccAddress, recipientName}. Used in case of an email adapter only

addressBccMap - The key value pairs of {bccAddress, recipientName}. Used in case of an email adapter only

adapterType - The type of communication opted for this outbound dialog. The first adapter of the given type is chosen if there are multiple ones exist. Usually either one of adapterType or adapterID.

adapterID - The id identifying a particular mode of communication. These values can be retried from ASK-Fast Portal in the adapters section.

senderName - A senderName can be attached for medium types: SMS, EMAIL. For SMS, the length should not exceed 11 charecters.

subject - Only valid for an email adapter. The subject of the message to be sent

url - This can be one of:
1. http(s) endpoint fetching a Question json as response.
2. A standard text prefixed by keyword: text://your message. This will be transformed to a Question.QUESTION_TYPE_COMMENT
3. A unique dialogId as defined in the ASK-Fast Portal or by method createDialog(Dialog) method

Returns:

Result based on a the request. If its a error, this might throw a RetrofitError, if it has a RetrofitError.getBody() try to deserialize it to Result and parse the reason for the failure. A login error would however not be caught by this Exception type.

getAdapters

public Set<Adapter> getAdapters(String type)

Returns a set of Adapters, optionally narrowed down by a type.

Parameters:

type - Optional. Possible values: sms, call, email or ussd

Returns:

A set of Adapters, optionally narrowed down by a type.

getAllAdapters

public Set<Adapter> getAllAdapters(String type)

Returns adapters owned by your account and shared with your account.

Parameters:

type -

Returns:

asOrderedSet

protected static <T> Set<T> asOrderedSet(List<T> src)

getAdapter

public Adapter getAdapter(String adapterId)

Returns the corresponding adapter by id

Parameters:

adapterId - The adapterId to be fetched

Returns:

Return the adapter

updateAdapter

public Adapter updateAdapter(String adapterId,
                    Adapter adapter)

Updates the adapter with the given adapterId.

Parameters:

adapterId - The id of the adapter

adapter - The adapter

Returns:

The updated adapter

buyAdapter

public void buyAdapter(String adapterId)

Buy an adapter. TODO: specify error behaviour: what happens if you can't buy the adapter? what if you're out of credits?

Parameters:

adapterId - The id of the adapter

removeAdapter

public void removeAdapter(String adapterId)

Remove an adapter from the logged in account. // TODO: describe more specifically per adapter type

Parameters:

adapterId - The The id of the adapter

getFreeAdapters

public Set<Adapter> getFreeAdapters(String adapterType,
                           String address)

Gets all the free adapters

Parameters:

adapterType - The type of the adapter

address - The address of adapter looking for

Returns:

A collection of Adapters

getCapableAdapters

public List<Adapter> getCapableAdapters(String type)

createDialog

public Dialog createDialog(Dialog dialog)

Create a dialog. The system assigns an id to the dialog.

Parameters:

dialog - The dialog

Returns:

The dialog

getDialogs

public Set<Dialog> getDialogs()

Returns the list of dialogs.

Returns:

The list of dialogs

getDialogsByName

public Set<Dialog> getDialogsByName(String name)

getDialog

public Dialog getDialog(String dialogId)

Retrieve a dialog by its id.

Parameters:

dialogId - The id of the dialog

Returns:

The dialog

updateDialog

public Dialog updateDialog(String dialogId,
                  Dialog dialog)

Update a dialog.

Parameters:

dialogId - The id of the dialog

dialog - The dialog

Returns:

The updated dialog

removeDialog

public void removeDialog(String dialogId)

Delete a dialog.

Parameters:

dialogId - The The id of the dialog

getRecordings

public List<Recording> getRecordings()

Get all the recordings of the current accountId

Returns:

List of recordings

getRecordings

public List<Recording> getRecordings(String accountId)

Get all the recordings linked to the specified account.

Parameters:

accountId - The accountId to for which all the recordings are recorded.

Returns:

List of recordings

getDDRRecords

public List<DDRRecord> getDDRRecords(Collection<String> adapterIds,
                            Collection<String> adapterTypes,
                            String fromAddress,
                            String typeId,
                            String status,
                            Long startTime,
                            Long endTime,
                            String delimitedSessionKeys,
                            Integer offset,
                            Integer limit,
                            Boolean shouldGenerateCosts,
                            Boolean shouldIncludeServiceCosts)
                              throws Exception

Returns a list of DDRRecords based on the give parameters.

Parameters:

adapterIds - The list of adapterIds for which ddrRecords must be fetched

adapterTypes - Fetch ddrRecords based on the channel used

fromAddress - Fetch ddrRecords based on the fromAddress

typeId - Fetch ddrRecords based on the type of cost attached. E.g. incoming, outgoing, tts processing etc

status - Fetch ddrRecords based on the status of the communication

startTime - Fetch ddrRecords based on a date range

endTime - Fetch ddrRecords based on a date range

delimitedSessionKeys - Fetch ddrRecords based on the sessionKeys generated per communication address.

offset - Skip the given number of ddrRecords

limit - Limit the fetch

shouldGenerateCosts - Force recalculating the costs for the communication or event

shouldIncludeServiceCosts - Force recalculating the service costs for the communication or event

Returns:

A collection of ddrRecords

Throws:

Exception - Error in ddr fetching

getDDRRecordCount

public Integer getDDRRecordCount(Collection<String> adapterIds,
                        Collection<String> adapterTypes,
                        String fromAddress,
                        String typeId,
                        String status,
                        Long startTime,
                        Long endTime,
                        String delimitedSessionKeys,
                        Integer offset)
                          throws Exception

A faster fetch of the aggregation of all quantities in the DDRRecord.getQuantity() based on the filtering criteria given

Parameters:

adapterIds - The list of adapterIds for which ddrRecords must be fetched

adapterTypes - Fetch ddrRecords based on the channel used

fromAddress - Fetch ddrRecords based on the fromAddress

typeId - Fetch ddrRecords based on the type of cost attached. E.g. incoming, outgoing, tts processing etc

status - Fetch ddrRecords based on the status of the communication

startTime - Fetch ddrRecords based on a date range

endTime - Fetch ddrRecords based on a date range

delimitedSessionKeys - Fetch ddrRecords based on the sessionKeys generated per communication address.

offset - Skip the given number of ddrRecords

Returns:

Total number of ddrs fetched for the filter passed

Throws:

Exception - Error in ddr fetching

modifyCall

public RestResponse modifyCall(String sessionId,
                      String url)

Modify the existing call

Parameters:

sessionId -

url -

Returns:

redirectCallToAnotherNumber

public RestResponse redirectCallToAnotherNumber(String sessionId,
                                       String number)

Redirect the call to another number

Parameters:

sessionId -

number -

Returns:

getAccessToken

public String getAccessToken()
                      throws Exception

Returns the access token. If the access token is null, it requests the key server to give a fresh token.

Returns:

The access token

Throws:

Exception - Thrown when refreshing the access token if the accountId or refreshToken is null

getRefreshToken

public String getRefreshToken()

Returns the refresh token

Returns:

The refresh token