Registering your workflows


Workflows are the underlying engine that drives user interaction on Relay devices. Using the Relay SDK, you can interact from your app with a registered workflow over a web socket connection. When a Relay user triggers a workflow, they enter the workflow channel. Workflows can short-lived (ending when a user leaves the workflow channel, the default behavior) or long-lived (persisting in the background until explicitly ended with the terminate command, called a 'transient' workflow).

You can add and update workflows on your Relay account with the Relay CLI. Recommended path (with brew):
$ brew install relaypro/tap/relay

Optionally, use npm package manager:
$ npm install -g @relaypro/cli

Workflow Structure

A Relay workflow contains its name, how to trigger it, where to establish the web socket connection and other configuration details.

$ relay workflow:create --help
create or update a workflow

  $ relay workflow:create [ID]

  ID  device / user ID to install workflow on

  --name=name                                         (required)
  --uri=uri                                           (required)
  -b, --boolean=arg1=[true|false]                     Boolean name/value pair workflow arg
  -h, --http
  -i, --hidden
  -r, --number=arg1=100.0                             Number name/value pair workflow arg
  -t, --[no-]transient
  --arg=arg                                           string arg name/value pair
  --button=(single|double)                            [default: single]

  workflow:create:battery  Crossing a charging or discharging threshold
  workflow:create:button   Button taps
  workflow:create:call     Inbound or outbound calling
  workflow:create:event    Event emitted by Relay device
  workflow:create:http     HTTP trigger
  workflow:create:phrase   Spoken phrase
  workflow:create:timer    Immediate or scheduled

Install Device/User IDs

You can install workflows on one or more Relay Devices or Virtual Endpoints (Mobile/Web Apps). To select which devices receive the workflow, use their ID when creating or registering a workflow. You can retrieve Device IDs from the Relay Dash portal under Fleet Management -> Devices :


Each workflow has a trigger action that kicks off the workflow. The trigger can be an action on the Relay device (like a button tap), a remote trigger (HTTP API call) or scheduled to occur on a specific time/date. In the example below, we are using a phrase event to start the workflow when the user speaks 'Hello' into the Relay Assistant (either while on the assistant channel, or using the channel button).

$ relay workflow:create:phrase --uri=wss:// --trigger=hello --name=hello 990007560051804

Additional types include: "button" & "remote". For more details see the triggers section.

Websocket URI and Parameters

Once triggered, your workflow will invoke a websocket connection with a provided URI where your Relay SDK based application lives. In addition to the URI, you can also specify arguments that are sent when the workflow starts. These are key:value pairs that your application can access.