Triggers are what start a workflow. When you register a workflow with the Relay server, you specify the triggers that you want to start your workflow. As the Relay server sees things happening across the whole system, if it sees a trigger that you have registered for, it will create an instance of your workflow by establishing a websocket connection to your workflow application server and sending it a START event. With that websocket connection, your workflow code can receive events and send actions.

There are several types of Triggers that can start a workflow, they are described below.

Workflow Triggers

  • phrase : This is a spoken phrase to the Assistant, either on any channel while holding the Assistant button, or while on the Assistant channel holding the Talk button. It can include one or more words that are spoken into the assistant, all of which must match. When registering your trigger phrase, make sure it is in all lower-case (i.e.,--trigger=hello), as the transcription of the spoken phrase is all lower-case and the matching is case sensitive. The phrase trigger also supports the notion of "spillover text": for example you can register the workflow with the phrase trigger "query status", and when the user speaks "query status Alice" the "query status" workflow will be started, and passed in to it will be spillover text "Alice" - this is a way to pass in a parameter via voice. You can add multiple --trigger arguments to associate more than one phrase with a single trigger.


Built-in Assistant Phrases

Be aware that if you want to use a phrase trigger that is similar to a built-in trigger, you should include it in your list of phrases to match. For example: --trigger=flattery --trigger=battery.

  • button: This is a tap of the Talk button (the button in the center of the device surrounded by the LEDs) when a user is on the Assistant channel. Can be a single tap or double tap. The Relay device is smart enough to handle differentiating between a single and double tap such that you receive only one trigger of the correct type.

  • http: This is a remote trigger that can be invoked with an HTTP POST (webhook) by any external system. The originator of this sends the HTTP POST to the Relay server, not to your workflow server. This trigger can occur independent of any device, and is commonly sent by a non-device third-party system. If desired, the sender of this webhook can include a JSON payload with additional key/value pairs that will be passed in to the workflow as arguments - this is a way to pass in external parameters. See the HTTP Trigger section for more information. Authentication is required when sending this trigger, so that only authorized parties can cause it to happen.

  • nfc: This is when a Relay device is tapped against a Relay-manufactured NFC tag. The label registered to the tag will be passed in to your workflow so you know which tag was tapped. See the NFC Tags section for more information.

  • timer: This is a scheduled trigger based on a date/time. It can occur once at a specific time, or it can also be recurring at a specific interval.

  • battery: This trigger is when any device on the account crosses a charging or discharging threshold.

CLI Help Command for Triggers

If you ever forget how to register a workflow with a particular trigger, entering the following commands in the terminal will provide a description of what arguments are needed to register a workflow. For example, the output below is what you will see after entering the relay help workflow create button command on the third line:

$ relay help
$ relay help workflow
$ relay help workflow create
$ relay help workflow create button

Create or update a workflow triggered by button taps

  $ relay workflow create button -n <value> -u <value> --trigger single|double [-N] [-i <value> | -A] [-t] [-e] [-a <value>] [-b <value>] [-r <value>]

  -A, --install-all                Enable rule to install workflow on all device and users on the account
  -N, --dry-run
  -a, --arg=<value>...             String name/value pair workflow arg
  -b, --boolean=arg1=[true|false]  Boolean name/value pair workflow arg
  -e, --hidden                     Hide channel from originating device
  -i, --install=<value>...         device / user ID to install workflow on
  -n, --name=<value>               (required) Name of the workflow
  -r, --number=arg1=100.0          Number name/value pair workflow arg
  -t, --[no-]transient             Allow workflow to run in the background; otherwise terminate workflow
  -u, --uri=<value>                (required) WebSocket URI workflow can be accessed
  --trigger=(single|double)        (required) [default: single] Number of button taps to trigger this workflow

  Create or update a workflow triggered by button taps

From the output, you can see which flags are required. For the button trigger, it requires a human-readable name for the workflow, a URL of your workflow server, and a choice of a single or double tap as the trigger. All of the workflow registrations will require a URL, a trigger, and name. Some other trigger types like timer will require additional flags (i.e., timezone, repeat period, etc.).

How Triggers Work

When a trigger occurs that matches your workflow registration, the Relay server considers this a new instance of your workflow, and will establish a new websocket connection to your workflow application and send a START event. In starting a workflow, the Relay server is the websocket client, and your workflow application is the websocket server. The Relay SDK usually includes a websocket server implementation that can listen for incoming requests from the Relay server. This also means that your workflow server needs to be reachable on the Internet by the Relay server. When you are done with actions in your workflow, you terminate any interactions and terminate the workflow. Then the Relay server will close the websocket, the workflow instance will go away, and your workflow application will be idle until the next trigger creates a new workflow instance. Because different triggers may happen near-simultaneously, the workflow application may have several instances running in parallel, so your workflow should be written such that it is thread-safe.

It is possible to have multiple triggers that point to the same workflow application. For example, you may wish for the same workflow to run if there is either an NFC tap or a spoken phrase. Or you may have two different phrases that start the same workflow, because one phrase is an alias for the other, or you have slightly different handling between the two phrases with common code and someif statements.

From a device perspective, if there are multiple workflows with the same trigger installed on the same device, then upon that trigger it is non-deterministic (random) which workflow will get started. Thus each workflow installed on a device should have a unique trigger.