Using Notifications

There are 3 types of notifications that you can use on the Relay platform: Broadcast, Notify, and Alert. In this section we'll go through these different types of notifications and some use cases.

Broadcast

Broadcast is a way for users to send out a single message out to others relay users no matter what channel they are in. This command can be targeted or be sent to a whole group.

At the minimum, 3 things have to be passed into the broadcast function:

  • The name, a unique identifier for that specific broadcast command. The name has to be a unique string
  • The actual text that has needs to be broadcasted. The text has to be a string
  • The targets for where the broadcast is going to. The targets have to be an array of strings. They can either be an array of device names, or an array of group names, or a mix of both. Even if the target is one device, it has to be passed in as an array.
import { relay, Event } from '@relaypro/sdk'

const app = relay()
    
app.workflow(`helloworld`, relay => {
  relay.on(Event.START, async () => {
    //This sends 'hi team, this is a test' out to the engineering group. You can find groups for your organization on Dash
    await relay.broadcast('test_broadcast', 'Hi team, this is a test', ['engineering'])
    
    //This sends out a broadcast to a 2 targeted Relays
    await relay.broadcast('targeted_broadcast', 'Pickup needed in room 237', ['John', 'Steven'])
    
    await relay.terminate()
  })
})

Once the broadcast command runs, the target devices will hear the message once. There won't be any repeats or acknowledgement of the message. However, if you'd like to ensure that your message is repeated and actively acknowledged, this is where Alerts come into place.

Alerts

Alerts have the additional feature of the message being repeatable. The Alert will repeat on the targeted user's Relay until they acknowledge it by tapping the talk button.

At the minimum, 3 things have to be passed into the alert function:

  • The name, a unique identifier for that specific alert command. The name has to be a unique string
  • The actual text that has needs to be send out as an alert. The text has to be a string
  • The targets for where the alert is going to. The targets have to be an array of strings. They can either be an array of device names, or an array of group names, or a mix of both. Even if the target is one device, it has to be passed in as an array.
import { relay, Event } from '@relaypro/sdk'

const app = relay()
    
app.workflow(`helloworld`, relay => {
  relay.on(Event.START, async () => {
    //This sends 'cleanup needed in room 213' out to the cleaning group. You can find groups for your organization on Dash
    await relay.alert('cleanup_alert', 'cleanup needed in room 213', ['cleaning'])
    
    //This sends out a alert to a 2 targeted Relays
    await relay.alert('targeted_alert', 'Delivery recieved at counter 4', ['John', 'Steven'])
    
    await relay.terminate()
  })
})

The alert will repeat the message every 30 seconds until the alert is acknowledged or the alert is cancelled from the originating workflow's. To cancel an an alert, use the relay.cancelAlert() function.

One example scenario of where a cancelAlert may be useful:
Take for example this command: await relay.alert('cleanup_alert', 'cleanup needed in room 213', ['cleaning'])
It sends this alert to the whole cleaning group. But once one person ack's the event, we would want the alert to stop on all the other devices. We wouldn't want everyone in the group to cleanup room 213. Once one person picks up the request, the alert should stop on all the other devices.

Here is an code based example of that:

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

const app = relay()
    
app.workflow(`helloworld`, relay => {
  relay.on(Event.START, async () => {
    //This sends 'cleanup needed in room 213' out to the cleaning group.
    await relay.alert('cleanup_alert', 'cleanup needed in room 213', ['cleaning'])
  })
  
  //once the notification is ack'ed by a user, this function will run
  relay.on(Event.NOTIFICATION, async (notificationEvent) => {
    //notificationEvent has details on who the ack'ed the event
    let acked_user = notificationEvent.source
    
    //Using the unique alert identifier (cleanup_alert), we can target it to stop alerting for that team
    await relay.cancelAlert('cleanup_alert', [`cleaning`])
    
    await relay.terminate()
  })
})

Notify

The notify function is very similar to alerts, the only difference is that the messages are not read out every 30 seconds for notifications like they are for alerts. The Relay instead plays an audible tone to let you know that you have a message every 30 seconds. To view the message, the user would have to go to their message inbox on their Relay and then they'll be able to hear the message. Programmatically, it is very similar to the Alert function with the only difference being that we'll be using the relay.notify() and relay.cancelNotify() functions.

At the minimum, 3 things have to be passed into the notify function:

  • The name, a unique identifier for that specific notify command. The name has to be a unique string
  • The actual text that has needs to be send out as a notify command. The text has to be a string
  • The targets for where the notify is going to. The targets have to be an array of strings. They can either be an array of device names, or an array of group names, or a mix of both. Even if the target is one device, it has to be passed in as an array.
import { relay, Event } from '@relaypro/sdk'

const app = relay()
    
app.workflow(`helloworld`, relay => {
  relay.on(Event.START, async () => {
    //This sends 'cleanup needed in room 213' out to the cleaning group.
    await relay.notify('cleanup_notify', 'cleanup needed in room 213', ['cleaning'])
  })
  
  //once the notification is ack'ed by a user, this function will run
  relay.on(Event.NOTIFICATION, async (notificationEvent) => {
    //notificationEvent has details on who the ack'ed the event
    let acked_user = notificationEvent.source
    
    //Using the unique notification identifier (cleanup_notify), we can target it to stop notifying for that team
    await relay.cancelNotify('cleanup_notify', [`cleaning`])
    
    await relay.terminate()
  })
})