Customizing Your Alerts

In addition to the notification and groups keys, alerts give you the option to further customize your notification. There are 6 optional keys that you can include in your payload when sending the request:

• on_ack : custom message to be spoken on the device that acknowledged the alert (default: nothing is spoken)

• quorum : remaining alerts are canceled after this number of acknowledgements (default: all devices in the group must acknowledge the alert)

• on_quorum : custom message to be spoken on devices that have not yet acknowledged the alert after quorum is met (default: nothing is spoken)

• timeout : remaining alerts are canceled after this time (seconds) (default: 300)

• on_timeout : custom message to be spoken on the devices that have not acknowledged the alert after timeout (default: nothing is spoken)

• name : gives user agents control over serial / concurrent alerting. This also appears in the analytics events for correlation (default: “alerts”)

Upon adding these to the request, our POST command could take the following form:

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

{
   "notification": "hello world",
   "groups": ["mygroup"],
   "on_ack": "thank you",
   "quorum": 1,
   "on_quorum": "already accepted",
   "timeout": 120,
   "on_timeout": "too slow",
   "name": "myname"
}

Let's see how we can customize our alert using some of these options. In the first example, we saw how we could send a simple alert to a group of devices using all of the default configuration settings. In the curl command below, we again trigger an alert with the message “Cleanup needed in the lounge” to the group “housekeeping”. However, this time we include four more key-value pairs into the request. We added in the quorum key with a value of 1, making it so our alert will only require that one device acknowledges the alert as opposed to all devices in the group. Once a device acknowledges the alert, the alert will terminate on all devices. We also included an on_ack key with a value of “thank you”. With this, after the user acknowledges the alert the device will say “thank you” to that user. This acts as a confirmation to the user that they acknowledged the alert. We also added in the timeout and on_timeout keys, making it so if the alert times out because no device tapped the talk button in an allocated 120 seconds, the devices will say “alert timed out!” on all of the devices in the group.

Putting all of this together, we get the curl command below.

$ 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"], "on_ack": "thank you","quorum": 1, "timeout": 120, "on_timeout": "alert timed out!" }' -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"}

See this example in action below, where we run the curl command above to fire the alert, and a device acknowledges the alert by tapping the talk button. Notice that now, after a device acknowledges the alert, the device now says “thank you” to that user, and the alert terminates.