Create your first workflow

Setup
So you just got your first Relay device and want to create your first workflow. We'll walk you through the process, step by step here with a simple notification workflow.

Before we begin, make sure you have a couple pieces of information handy - you should have node 16.12.0 or higher installed, have your Relay account login & password handy (we'll use these to authenticate the Relay CLI tool) and your device ID for the device you want to install your workflow on (you can list these in the CLI or pull them from Relay Dash).

Initialize & Install the SDK
First, we'll create our project and initialize. This example is in node so we'll begin by initializing our project in a directory of our choosing. Next, we'll install the SDK. You can either use directly from github or install via npm in your project directory:

$ npm init
$ npm install -g @relaypro/sdk

Then, create your first workflow. Here we're creating a simple Hello workflow from the relay-samples github repo. You can pull down the code with git clone [email protected]:relaypro/relay-samples.git. In your workflows directory, you'll see a file named helloworld.js, this contains the code our workflow will be running - we're getting the Relay device name, asking the user for their name and then speaking back a greeting that we'll set on workflow registration.

import { Event, createWorkflow } from '@relaypro/sdk'

export default createWorkflow(relay => {
  relay.on(Event.START, async () => {
    const greeting = await relay.getVar(`greeting`)
    const name = await relay.getDeviceName()
    await relay.say(`What is your name ?`)
    const user = await relay.listen()
    await relay.say(`Hello ${user.text}, from ${name}`)
    await relay.terminate()
  })
})

This contains the workflow code. Next, run your workflow by going to the root directory, and running the index.js file: node index.js. This registers each separate workflow against a unique URI that we'll use to register individual workflows. I've included the relevant sections below.

import { relay } from '@relaypro/sdk'
import helloworld from './workflows/helloworld.js'

const express1 = express()
const port = process.env.PORT || 3000

const server = express1.listen(port, () => {
  console.log(`express listening on ${port}`)
})

const app = relay({server})

// "named" workflows must match the WS path
// e.g. wss://host:port/helloworld
app.workflow(`helloworld`, helloworld)

You should see something like this:

$ node index.js
$ Default workflow set
$ express listening on 3000

Next, we'll expose our workflow to the world using a utility called ngrok:

$ npm install ngrok
$ ngrok http 3000

You should see a randomized public URI for your workflow, forwarded to your local machine. We'll use this in the next step to register our workflow. Here, we're using the phrase trigger 'Hello' on the device and pointing that to our workflow. To get usage details, you can use the --help on any Relay CLI command.

$ npm install @relaypro/cli
$ relay login
$ relay workflow:create:phrase -n Hello -u 'wss://fb4ce55dbf21.ngrok.io/helloworld' --trigger="Hello" -a greeting=hello -i 99000756002XXXX
=== Installed Workflow
ID                               Name  Type         Uri                                    Args                    Installed on
wf_Hello_ONkUx9CWHQLYtdPINECmqkC Hello phrase:Hello wss://fb4ce55dbf21.ngrok.io/helloworld greeting=hello | string 99000756002XXXX

Nice work! Now you can go to your device and try it out. To use a phrase trigger, either navigate to the 'Relay Assistant' channel and use the big talk button on the front of the device or from any channel, press and hold the channel button (the button between the '+' & '-' keys on the side) and speak your trigger phrase of 'Hello'.