Package com.relaypro.sdk

Class Relay

java.lang.Object

com.relaypro.sdk.Relay

public class Relay
extends java.lang.Object

Actions and utilities that can be performed on a Relay device.

Method Summary

Modifier and Type	Method	Description
static void	addWorkflow(java.lang.String name, Workflow wf)	Adds a workflow to the path.
void	alert(java.lang.String target, java.lang.String originator, java.lang.String name, java.lang.String text)	Sends out an alert to the specified group of devices and the Relay Dash.
void	answerCall(java.lang.String target, java.lang.String call_id)	Answers a call on your device.
void	breathe(java.lang.String target, java.lang.String color, int count)	Switches all the LEDs on a device to a certain color and creates a 'breathing' effect, where the LEDs will slowly light up a specified number of times.
void	broadcast(java.lang.String target, java.lang.String originator, java.lang.String name, java.lang.String text)	Broadcasts a message to a group of devices.
void	cancelAlert(java.lang.String target, java.lang.String name)	Cancels an alert that was sent to a group of devices.
void	cancelBroadcast(java.lang.String target, java.lang.String name)	Cancels the broadcast that was sent to a group of devices.
void	clearTimer(java.lang.String name)	Clears the specified timer.
java.lang.String	createIncident(java.lang.String originator, java.lang.String itype)	Creates an incident that will alert the Relay Dash.
void	disableHomeChannel(java.lang.String target)	Disables the home channel on the device.
void	disableLocation(java.lang.String target)	Disables location services on a device.
void	enableHomeChannel(java.lang.String target)	Enables the home channel on the device.
void	enableLocation(java.lang.String target)	Enables location services on a device.
java.lang.String	endInteraction(java.lang.String target)	Ends an interaction with the user.
java.util.Map<java.lang.String,java.lang.String>	fetchDevice(java.lang.String accessToken, java.lang.String refreshToken, java.lang.String clientId, java.lang.String subscriberId, java.lang.String userId)	A convenience method for getting all the details of a device.
void	flash(java.lang.String target, java.lang.String color, int count)	Switches all the LEDs on a device to a certain color and flashes them a specified number of times.
java.lang.String	getDeviceAddress(java.lang.String target, boolean refresh)	Returns the address of a targeted device.
int	getDeviceBattery(java.lang.String target, boolean refresh)	Returns the battery of a targeted device.
double[]	getDeviceCoordinates(java.lang.String target, boolean refresh)	Retrieves the coordinates of the device's location.
java.lang.String	getDeviceId(java.lang.String target, boolean refresh)	Returns the ID of a targeted device.
java.lang.String	getDeviceIndoorLocation(java.lang.String target, boolean refresh)	Returns the indoor location of a targeted device.
double[]	getDeviceLatLong(java.lang.String target, boolean refresh)	Returns the latitude and longitude coordinates of a targeted device.
java.lang.String	getDeviceLocation(java.lang.String target, boolean refresh)	Returns the location of a targeted device.
java.lang.Boolean	getDeviceLocationEnabled(java.lang.String target, boolean refresh)	Returns whether the location services on a device are enabled.
java.lang.String	getDeviceName(java.lang.String target, boolean refresh)	Returns the name of a targeted device.
java.lang.String	getDeviceType(java.lang.String target, boolean refresh)	Returns the device type of a targeted device, i.e.
int	getNumberVar(java.lang.String name, int defaultValue)	Retrieves a variable that was set either during workflow registration or through the set_var() function of type integer.
static java.lang.String	getSourceUriFromStartEvent(StartEvent startEvent)	Parses out and retrieves the source URN from a Start Event.
int	getUnreadInboxSize(java.lang.String target)	Retrieves the number of messages in a device's inbox.
java.lang.String	getUserProfile(java.lang.String target, boolean refresh)	Returns the user profile of a targeted device.
java.lang.String	getVar(java.lang.String name, java.lang.String defaultValue)	Retrieves a variable that was set either during workflow registration or through the set_var() function.
void	hangupCall(java.lang.String target, java.lang.String call_id)	Ends a call on your device.
boolean	isGroupMember(java.lang.String groupNameUri, java.lang.String potentialMemberNameUri)	Checks whether a device is a member of a particular group.
java.lang.String	listen(java.lang.String target, java.lang.String requestId)	Listens for the user to speak into the device.
java.lang.String	listen(java.lang.String target, java.lang.String requestId, java.lang.String[] phrases, boolean transcribe, LanguageType lang, int timeout)	Listens for the user to speak into the device.
void	logMessage(java.lang.String message, java.lang.String category)	Log an analytics event from a workflow with the specified content and under a specified category.
void	logUserMessage(java.lang.String message, java.lang.String deviceUri, java.lang.String category)	Log an analytic event from a workflow with the specified content and under a specified category.
java.lang.String	placeCall(java.lang.String target, java.lang.String calleeUri)	Places a call to another device.
java.lang.String	play(java.lang.String target, java.lang.String filename)	Plays a custom audio file that was uploaded by the user.
java.lang.String	playAndWait(java.lang.String target, java.lang.String filename)	Plays a custom audio file that was uploaded by the user.
void	playUnreadInboxMessages(java.lang.String target)	Play a targeted device's inbox messages.
void	rainbow(java.lang.String target, int rotations)	Switches all the LEDs on to a configured rainbow pattern and rotates the rainbow a specified number of times.
static void	receiveMessage(jakarta.websocket.Session session, java.lang.String message)
void	resolveIncident(java.lang.String incidentId, java.lang.String reason)	Resolves an incident that was created.
void	rotate(java.lang.String target, java.lang.String color, int rotations)	Switches all the LEDs on a device to a certain color and rotates them a specified number of times.
java.lang.String	say(java.lang.String target, java.lang.String text)	Utilizes text to speech capabilities to make the device 'speak' to the user.
java.lang.String	say(java.lang.String target, java.lang.String text, LanguageType lang)	Utilizes text to speech capabilities to make the device 'speak' to the user.
void	sayAndWait(java.lang.String target, java.lang.String text)	Utilizes text to speech capabilities to make the device 'speak' to the user.
void	sayAndWait(java.lang.String target, java.lang.String text, LanguageType lang)	Utilizes text to speech capabilities to make the device 'speak' to the user.
void	setChannel(java.lang.String target, java.lang.String channelName, boolean suppressTTS, boolean disableHomeChannel)	Sets the channel that a device is on.
void	setDeviceName(java.lang.String target, java.lang.String name)	Sets the name of a targeted device and updates it on the Relay Dash.
void	setTimer(TimerType timerType, java.lang.String name, long timeout, TimeoutType timeoutType)	Serves as a named timer that can be either interval or timeout.
void	setUserProfile(java.lang.String target, java.lang.String username, boolean force)	Sets the profile of a user by updating the username.
void	setVar(java.lang.String name, java.lang.String value)	Sets a variable with the corresponding name and value.
java.lang.String	startInteraction(java.lang.String target, java.lang.String name)	Starts an interaction with the user.
java.lang.String	startInteraction(java.lang.String target, java.lang.String name, java.lang.Object options)	Starts an interaction with the user.
void	startTimer(int timeout)	Starts an unnamed timer, meaning this will be the only timer on your device.
static void	startWorkflow(jakarta.websocket.Session session, java.lang.String workflowName)
void	stopPlayback(java.lang.String target, java.lang.String[] ids)	Stops a playback request on the device.
void	stopTimer()	Stops an unnamed timer.
static void	stopWorkflow(jakarta.websocket.Session session, java.lang.String reason)
void	switchAllLedOff(java.lang.String target)	Switches all of the LEDs on a device off.
void	switchAllLedOn(java.lang.String target, java.lang.String color)	Switches all the LEDs on a device on to a specified color.
void	switchLedOn(java.lang.String target, int index, java.lang.String color)	Switches on an LED at a particular index to a specified color.
void	terminate()	Terminates a workflow.
java.lang.String	translate(java.lang.String text, LanguageType from, LanguageType to)	Translates text from one language to another.
java.util.Map<java.lang.String,java.lang.String>	triggerWorkflow(java.lang.String accessToken, java.lang.String refreshToken, java.lang.String clientId, java.lang.String workflowId, java.lang.String subscriberId, java.lang.String userId, java.lang.String[] targets, java.util.Map<java.lang.String,java.lang.String> actionArgs)	A convenience method for sending an HTTP trigger to the Relay server.
void	unsetVar(java.lang.String name)	Unsets the value of a variable.
void	vibrate(java.lang.String target, int[] pattern)	Makes the device vibrate in a particular pattern.

Methods inherited from class java.lang.Object

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

Method Detail

addWorkflow

public static void addWorkflow(java.lang.String name,
                               Workflow wf)

Adds a workflow to the path. Maps the specified name of the workflow to the new instance of the workflow class created.

Parameters:

name - a name for your workflow.

wf - a new instance of a class that contains your workflow.

startWorkflow

public static void startWorkflow(jakarta.websocket.Session session,
                                 java.lang.String workflowName)

stopWorkflow

public static void stopWorkflow(jakarta.websocket.Session session,
                                java.lang.String reason)

receiveMessage

public static void receiveMessage(jakarta.websocket.Session session,
                                  java.lang.String message)

startInteraction

public java.lang.String startInteraction(java.lang.String target,
                                         java.lang.String name)

Starts an interaction with the user. Triggers an INTERACTION_STARTED event and allows the user to interact with the device via functions that require an interaction URN. Uses a default set of options.

Parameters:

target - the device that you would like to start an interaction with.

name - a name for your interaction

Returns:

any errors received from the server.

See Also:

startInteraction(String, String, Object)

startInteraction

public java.lang.String startInteraction(java.lang.String target,
                                         java.lang.String name,
                                         java.lang.Object options)

Starts an interaction with the user. Triggers an INTERACTION_STARTED event and allows the user to interact with the device via functions that require an interaction URN.

Parameters:

target - the device that you would like to start an interaction with.

name - a name for your interaction

options - can be color, home channel, or input types.

Returns:

any errors received from the server.

See Also:

startInteraction(String, String)

endInteraction

public java.lang.String endInteraction(java.lang.String target)

Ends an interaction with the user. Triggers an INTERACTION_ENDED event to signify that the user is done interacting with the device.

Parameters:

target - the interaction that you would like to end.

Returns:

any errors received from the server.

say

public java.lang.String say(java.lang.String target,
                            java.lang.String text)

Utilizes text to speech capabilities to make the device 'speak' to the user.

Parameters:

target - the interaction URN.

text - what you would like the device to say.

Returns:

the response ID after the device speaks to the user.

say

public java.lang.String say(java.lang.String target,
                            java.lang.String text,
                            LanguageType lang)

Utilizes text to speech capabilities to make the device 'speak' to the user.

Parameters:

target - the interaction URN.

text - what you would like te device to say.

lang - the language of the text that is being spoken.

Returns:

the response ID after the device speaks to the user.

sayAndWait

public void sayAndWait(java.lang.String target,
                       java.lang.String text)

Utilizes text to speech capabilities to make the device 'speak' to the user. Waits until the text is fully played out on the device before continuing.

Parameters:

target - the interaction URN.

text - what you would like the device to say.

sayAndWait

public void sayAndWait(java.lang.String target,
                       java.lang.String text,
                       LanguageType lang)

Utilizes text to speech capabilities to make the device 'speak' to the user. Waits until the text is fully played out on the device before continuing.

Parameters:

target - the interaction URN.

text - what you would like the device to say.

lang - the language of the text that is being spoken.

listen

public java.lang.String listen(java.lang.String target,
                               java.lang.String requestId)

Listens for the user to speak into the device. Utilizes speech to text functionality to interact with the user.

Parameters:

target - the interaction URN.

requestId - the request ID.

Returns:

the text that the device parsed from what was spoken.

listen

public java.lang.String listen(java.lang.String target,
                               java.lang.String requestId,
                               java.lang.String[] phrases,
                               boolean transcribe,
                               LanguageType lang,
                               int timeout)

Listens for the user to speak into the device. Utilizes speech to text functionality to interact with the user.

Parameters:

target - the interaction URN.

requestId - the request ID.

phrases - phrases that you would like to limit the user's response to.

transcribe - whether you would like to transcribe the user's response.

lang - if you would like the device to listen for a response in a specific language.

timeout - timeout for how long the device will wait for user's response.

Returns:

the text that the device parsed from what was spoken.

play

public java.lang.String play(java.lang.String target,
                             java.lang.String filename)

Plays a custom audio file that was uploaded by the user.

Parameters:

target - the interaction URN.

filename - the name of the audio file.

Returns:

the response ID after the audio file has been played on the device.

playAndWait

public java.lang.String playAndWait(java.lang.String target,
                                    java.lang.String filename)

Plays a custom audio file that was uploaded by the user. Waits until the audio file has finished playing before continuing through the workflow.

Parameters:

target - the interaction URN.

filename - the name of the audio file.

Returns:

the response ID after the audio file has been played on the device.

stopPlayback

public void stopPlayback(java.lang.String target,
                         java.lang.String[] ids)

Stops a playback request on the device.

Parameters:

target - the device URN.

ids - the IDs of the devices who you would like to stop the playback message for.

playUnreadInboxMessages

public void playUnreadInboxMessages(java.lang.String target)

Play a targeted device's inbox messages.

Parameters:

target - the device or interaction URN whose inbox you would like to check.

getUnreadInboxSize

public int getUnreadInboxSize(java.lang.String target)

Retrieves the number of messages in a device's inbox.

Parameters:

target - the device or interaction URN whose inbox you would like to check.

Returns:

the number of messages in the specified device's inbox.

setTimer

public void setTimer(TimerType timerType,
                     java.lang.String name,
                     long timeout,
                     TimeoutType timeoutType)

Serves as a named timer that can be either interval or timeout. Allows you to specify the unit of time.

Parameters:

timerType - can be 'timeout' or 'interval'. Defaults to 'timeout'.

name - a name for your timer.

timeout - an integer representing when you would like your timer to fire.

timeoutType - can be 'ms', 'secs', 'mins' or 'hrs'. Defaults to 'secs'.

clearTimer

public void clearTimer(java.lang.String name)

Clears the specified timer.

Parameters:

name - the name of the timer that you would like to clear.

startTimer

public void startTimer(int timeout)

Starts an unnamed timer, meaning this will be the only timer on your device. The timer will fire when it reaches the value of the 'timeout' parameter.

Parameters:

timeout - the number of seconds you would like to wait until the timer fires.

stopTimer

public void stopTimer()

Stops an unnamed timer.

translate

public java.lang.String translate(java.lang.String text,
                                  LanguageType from,
                                  LanguageType to)

Translates text from one language to another.

Parameters:

text - the text that you would like to translate.

from - the language that you would like to translate from.

to - the language that you would like to translate to.

Returns:

the translated text.

placeCall

public java.lang.String placeCall(java.lang.String target,
                                  java.lang.String calleeUri)

Places a call to another device.

Parameters:

target - the device or interaction URN that will place the call.

calleeUri - the URN of the device you would like to call.

Returns:

the call ID.

answerCall

public void answerCall(java.lang.String target,
                       java.lang.String call_id)

Answers a call on your device.

Parameters:

target - the device or interaction URN that will answer the call.

call_id - the ID of the call to answer.

hangupCall

public void hangupCall(java.lang.String target,
                       java.lang.String call_id)

Ends a call on your device.

Parameters:

target - the device or interaction URN that will hang up the call.

call_id - the ID of the call to hang up.

createIncident

public java.lang.String createIncident(java.lang.String originator,
                                       java.lang.String itype)

Creates an incident that will alert the Relay Dash.

Parameters:

originator - the device URN that triggered the incident.

itype - the type of incident that occurred.

resolveIncident

public void resolveIncident(java.lang.String incidentId,
                            java.lang.String reason)

Resolves an incident that was created.

Parameters:

incidentId - the ID of the incident that you would like to resolve.

reason - the reason for resolving the incident.

logUserMessage

public void logUserMessage(java.lang.String message,
                           java.lang.String deviceUri,
                           java.lang.String category)

Log an analytic event from a workflow with the specified content and under a specified category. This includes the device who triggered the workflow that called this function.

Parameters:

message - a description for your analytical event.

deviceUri - the URN of the device that triggered this function.

category - a category for your analytical event.

logMessage

public void logMessage(java.lang.String message,
                       java.lang.String category)

Log an analytics event from a workflow with the specified content and under a specified category. This does not log the device who triggered the workflow that called this function.

Parameters:

message - a description for your analytical event.

category - a category for your analytical event

switchLedOn

public void switchLedOn(java.lang.String target,
                        int index,
                        java.lang.String color)

Switches on an LED at a particular index to a specified color.

Parameters:

target - the interaction URN.

index - the index of the LED, numbered 1-12.

color - the hex color code you would like to turn the LED to.

switchAllLedOn

public void switchAllLedOn(java.lang.String target,
                           java.lang.String color)

Switches all the LEDs on a device on to a specified color.

Parameters:

target - the interaction URN.

color - the hex color code you would like the LEDs to be.

switchAllLedOff

public void switchAllLedOff(java.lang.String target)

Switches all of the LEDs on a device off.

Parameters:

target - the interaction URN.

rainbow

public void rainbow(java.lang.String target,
                    int rotations)

Switches all the LEDs on to a configured rainbow pattern and rotates the rainbow a specified number of times.

Parameters:

target - the interaction URN.

rotations - the number of times you would like the rainbow to rotate.

rotate

public void rotate(java.lang.String target,
                   java.lang.String color,
                   int rotations)

Switches all the LEDs on a device to a certain color and rotates them a specified number of times.

Parameters:

target - the interaction URN.

color - the hex color code you would like to turn the LEDs to.

rotations - the number of times you would like the LEDs to rotate.

flash

public void flash(java.lang.String target,
                  java.lang.String color,
                  int count)

Switches all the LEDs on a device to a certain color and flashes them a specified number of times.

Parameters:

target - the interaction URN.

color - the hex color code you would like to turn the LEDs to.

count - the number of times you would like the LEDs to flash.

breathe

public void breathe(java.lang.String target,
                    java.lang.String color,
                    int count)

Switches all the LEDs on a device to a certain color and creates a 'breathing' effect, where the LEDs will slowly light up a specified number of times.

Parameters:

target - the interaction URN.

color - the hex color code you would like to turn the LEDs to.

count - the number of times you would like the LEDs to flash.

vibrate

public void vibrate(java.lang.String target,
                    int[] pattern)

Makes the device vibrate in a particular pattern. You can specify how many vibrations you would like, the duration of each vibration in milliseconds, and how long you would like the pauses between each vibration to last in milliseconds.

Parameters:

target - the interaction URN.

pattern - an array representing the pattern of your vibration.

setVar

public void setVar(java.lang.String name,
                   java.lang.String value)

Sets a variable with the corresponding name and value. Scope of the variable is from start to end of a workflow. Note that you can only set values of type string.

Parameters:

name - name of the variable to be created.

value - value that the variable will hold.

getVar

public java.lang.String getVar(java.lang.String name,
                               java.lang.String defaultValue)

Retrieves a variable that was set either during workflow registration or through the set_var() function. The variable can be retrieved anywhere within the workflow, but is erased after the workflow terminates.

Parameters:

name - name of the variable to be retrieved.

defaultValue - default value of the variable if it does not exist.

Returns:

the variable requested as a String.

getNumberVar

public int getNumberVar(java.lang.String name,
                        int defaultValue)

Retrieves a variable that was set either during workflow registration or through the set_var() function of type integer. The variable can be retrieved anywhere within the workflow, but is erased after the workflow terminates.

Parameters:

name - name of the variable to be retrieved.

defaultValue - default value of the variable if it does not exist.

Returns:

the variable requested as an Integer.

unsetVar

public void unsetVar(java.lang.String name)

Unsets the value of a variable.

Parameters:

name - the name of the variable whose value you would like to unset.

isGroupMember

public boolean isGroupMember(java.lang.String groupNameUri,
                             java.lang.String potentialMemberNameUri)

Checks whether a device is a member of a particular group.

Parameters:

groupNameUri - the URN of a group.

potentialMemberNameUri - the URN of the device name.

Returns:

true if the device is a member of the specified group, false otherwise.

alert

public void alert(java.lang.String target,
                  java.lang.String originator,
                  java.lang.String name,
                  java.lang.String text)

Sends out an alert to the specified group of devices and the Relay Dash.

Parameters:

target - the group URN that you would like to send an alert to.

originator - the URN of the device that triggered the alert.

name - a name for your alert.

text - the text that you would like to be spoken to the group as your alert.

cancelAlert

public void cancelAlert(java.lang.String target,
                        java.lang.String name)

Cancels an alert that was sent to a group of devices. Particularly useful if you would like to cancel the alert on all devices after one device has acknowledged the alert.

Parameters:

target - the device URN that has acknowledged the alert.

name - the name of the alert.

broadcast

public void broadcast(java.lang.String target,
                      java.lang.String originator,
                      java.lang.String name,
                      java.lang.String text)

Broadcasts a message to a group of devices. The message is played out on all devices, as well as sent to the Relay Dash.

Parameters:

target - the group URN that you would like to broadcast you message to.

originator - the device URN that triggered the broadcast.

name - a name for your broadcast.

text - the text that you would like to broadcast to your group.

cancelBroadcast

public void cancelBroadcast(java.lang.String target,
                            java.lang.String name)

Cancels the broadcast that was sent to a group of devices.

Parameters:

target - the device URN that is cancelling the broadcast.

name - the name of the broadcast that you would like to cancel.

getDeviceName

public java.lang.String getDeviceName(java.lang.String target,
                                      boolean refresh)

Returns the name of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the name of the device.

Returns:

the name of the device.

getDeviceId

public java.lang.String getDeviceId(java.lang.String target,
                                    boolean refresh)

Returns the ID of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the name of the device.

Returns:

the device ID.

getDeviceLocation

public java.lang.String getDeviceLocation(java.lang.String target,
                                          boolean refresh)

Returns the location of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the location.

Returns:

the location of the device.

getDeviceAddress

public java.lang.String getDeviceAddress(java.lang.String target,
                                         boolean refresh)

Returns the address of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the address.

Returns:

the address of the device.

getDeviceCoordinates

public double[] getDeviceCoordinates(java.lang.String target,
                                     boolean refresh)

Retrieves the coordinates of the device's location.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the coordinates.

Returns:

a double array containing the latitude and longitude of the device.

getDeviceLatLong

public double[] getDeviceLatLong(java.lang.String target,
                                 boolean refresh)

Returns the latitude and longitude coordinates of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the coordinates.

Returns:

a double array containing the latitude and longitude of the device.

getDeviceIndoorLocation

public java.lang.String getDeviceIndoorLocation(java.lang.String target,
                                                boolean refresh)

Returns the indoor location of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the location.

Returns:

the indoor location of the device.

getDeviceBattery

public int getDeviceBattery(java.lang.String target,
                            boolean refresh)

Returns the battery of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the battery.

Returns:

the batter of the device as an integer.

getDeviceType

public java.lang.String getDeviceType(java.lang.String target,
                                      boolean refresh)

Returns the device type of a targeted device, i.e. gen2, gen 3, etc.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the device type.

Returns:

the device type.

getUserProfile

public java.lang.String getUserProfile(java.lang.String target,
                                       boolean refresh)

Returns the user profile of a targeted device.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving the device user profile.

Returns:

the user profile registered to the device.

getDeviceLocationEnabled

public java.lang.Boolean getDeviceLocationEnabled(java.lang.String target,
                                                  boolean refresh)

Returns whether the location services on a device are enabled.

Parameters:

target - the device or interaction URN.

refresh - whether you would like to refresh before retrieving whether the device's location services are enabled.

Returns:

true if the device's location services are enabled, false otherwise.

setDeviceName

public void setDeviceName(java.lang.String target,
                          java.lang.String name)

Sets the name of a targeted device and updates it on the Relay Dash. The name remains updated until it is set again via a workflow or updated manually on the Relay Dash.

Parameters:

target - the device or interaction URN.

name - a new name for your device.

enableLocation

public void enableLocation(java.lang.String target)

Enables location services on a device. Location services will remain enabled until they are disabled on the Relay Dash or through a workflow.

Parameters:

target - the device or interaction URN.

disableLocation

public void disableLocation(java.lang.String target)

Disables location services on a device. Location services will remain disabled until they are enabled on the Relay Dash or through a workflow.

Parameters:

target - the device or interaction URN.

setChannel

public void setChannel(java.lang.String target,
                       java.lang.String channelName,
                       boolean suppressTTS,
                       boolean disableHomeChannel)

Sets the channel that a device is on. This can be used to chang the channel of a device during a workflow, where the channel will also be updated on the Relay Dash.

Parameters:

target - the device or interaction URN.

channelName - the name of the channel you would like to set your device to.

suppressTTS - whether you would like to surpress text to speech.

disableHomeChannel - whether you would like to disable the home channel.

setUserProfile

public void setUserProfile(java.lang.String target,
                           java.lang.String username,
                           boolean force)

Sets the profile of a user by updating the username.

Parameters:

target - the device URN whose profile you would like to update.

username - the updated username for the device.

force - whether you would like to force this update.

enableHomeChannel

public void enableHomeChannel(java.lang.String target)

Enables the home channel on the device.

Parameters:

target - the device URN.

disableHomeChannel

public void disableHomeChannel(java.lang.String target)

Disables the home channel on the device.

Parameters:

target - the device URN.

terminate

public void terminate()

Terminates a workflow. This method is usually called after your workflow has completed and you would like to end the workflow by calling end_interaction(), where you can then terminate the workflow.

getSourceUriFromStartEvent

public static java.lang.String getSourceUriFromStartEvent(StartEvent startEvent)

Parses out and retrieves the source URN from a Start Event.

Parameters:

startEvent - the start event.

Returns:

the source URN.

triggerWorkflow

public java.util.Map<java.lang.String,java.lang.String> triggerWorkflow(java.lang.String accessToken,
                                                                              java.lang.String refreshToken,
                                                                              java.lang.String clientId,
                                                                              java.lang.String workflowId,
                                                                              java.lang.String subscriberId,
                                                                              java.lang.String userId,
                                                                              java.lang.String[] targets,
                                                                              java.util.Map<java.lang.String,java.lang.String> actionArgs)

A convenience method for sending an HTTP trigger to the Relay server. This generally would be used in a third-party system to start a Relay workflow via an HTTP trigger and optionally pass data to it with action_args. If the accessToken has expired and the request gets a 401 response, a new access_token will be automatically generated via the refreshToken, and the request will be resubmitted with the new accessToken. Otherwise the refresh token won't be used. This method will return a tuple of (requests.Response, access_token) where you can inspect the http response, and get the updated access_token if it was updated (otherwise the original access_token will be returned).

Parameters:

accessToken - the current access token. Can be a placeholder value and this method will generate a new one and return it. If the original value of the access token passed in here has expired, this method will also generate a new one and return it.

refreshToken - the permanent refresh_token that can be used to obtain a new access_token. The caller should treat the refresh token as very sensitive data, and secure it appropriately.

clientId - the auth_sdk_id as returned from "relay env".

workflowId - the workflow_id as returned from "relay workflow list". Usually starts with "wf_".

subscriberId - the subscriber UUID as returned from "relay whoami".

userId - the IMEI of the target device, such as 990007560023456.

targets - the device URN on which you would like to trigger the workflow.

actionArgs - a Map of any key/value arguments you want to pass in to the workflow that gets started by this trigger.

Returns:

fetchDevice

public java.util.Map<java.lang.String,java.lang.String> fetchDevice(java.lang.String accessToken,
                                                                          java.lang.String refreshToken,
                                                                          java.lang.String clientId,
                                                                          java.lang.String subscriberId,
                                                                          java.lang.String userId)

A convenience method for getting all the details of a device. This will return quite a bit of data regarding device configuration and state. The result, if the query was successful, should have a large JSON dictionary.

Parameters:

accessToken - the current access token. Can be a placeholder value and this method will generate a new one and return it. If the original value of the access token passed in here has expired, this method will also generate a new one and return it.

refreshToken - the permanent refresh_token that can be used to obtain a new access_token. The caller should treat the refresh token as very sensitive data, and secure it appropriately.

clientId - the auth_sdk_id as returned from "relay env".

subscriberId - the subscriber UUID as returned from "relay whoami".

userId - the IMEI of the target device, such as 990007560023456.

Returns:

a Map containing the response and the access token.