Triggering an Alert

An alert is a message that is played out on devices within a specified group every 30 seconds until it is acknowledged.

An alert can be started through a simple POST request to our server into our /alerts endpoint.

The POST command to send an alert should take the following form:

POST /subscribers/{id}/api/v1/alerts
Authorization: RelayApiKey {apikey}
Content-type: application/json

{
   "notification": "hello world",
   "groups": ["mygroup"],
}

Headers and Subscriber ID Path

• apikey : you should contact Relay to get your API key, as it is not available via self-service. Your key should be included within the Authorization header. Don’t forget to include “RelayApiKey” before your actual key.

• id : your subscriber ID, which can be found on the Relay Dash through Help → Server Details under Subscriber

Required Content

• notification : custom message to be spoken on the group of devices. The Relay server will automatically convert your written text into spoken audio (text-to-speech)

• groups : a list containing the group names or URNs to send the alert to.

Example

The following example is a curl command that sends an alert request up to our server.

$ export subscriber_id=yourcustomersID
$ export apikey=myapikey123
$ curl -X POST -H "Authorization: RelayApiKey $apikey" "https://api.relaypro.com/subscribers/$subscriber_id/api/v1/alerts" -d '{"notification": "Cleanup needed in the lounge", "groups": ["housekeeping"]}' -i

HTTP/2 200 
date: Mon, 11 Dec 2023 14:31:36 GMT
content-type: application/json
content-length: 38
server: nginx/1.20.0
location: /subscribers/xxx/api/v1/alerts/P9CThKfTsEbJx23trAArHCD

{"task_id":"P9CThKfTsEbJx23trAArHCD"}

This curl command alerts the group “housekeeping” that there is “Cleanup needed in the lounge”. The alert will continue to sound on a user’s device every 30 seconds until it is acknowledged by the user tapping the talk button. Once the user taps the talk button, the alert will stop sounding on the device. If the user does not acknowledge the alert after 5 minutes, the alert will timeout and cease playing. See what this alert looks like on the device in the video below.