Custom Priority Alerts

Omnilert provides "Custom Priority Alerts" to allow third-party services/devices to initialize Priority Alerts sent to the Omnilert App (mobile or desktop).

Custom Priority Alerts can include media links and/or map coordinates to enhance the experience for the recipients. You can also create optional custom "actions" which will create custom buttons to further extend functionality. 

Please note: Some basic knowledge of web API programming is needed to set up a Custom Priority Alert. 

Creating a new Custom Priority Alert

To create a new Custom Priority Alert, go to Priority Alerts > Custom Alert and then click Add new custom alert.

Then enter a name for your new Custom Alert and click Add Alert to save it.

Once added, you'll need to configure and activate your new custom alert before it can be used. The new custom alert will be listed as "Inactive" until you complete the configuration and link it to at least 1 private group. (See below)

Configuring/Editing a Custom Priority Alert

Go to Priority Alerts > Custom Alert > Manage Custom Alerts to view a list of your custom alerts. Click on your newly created custom alert in the list to view its configuration. 

Details tab

The Details tab will include basic information about this custom alert as well as a checkbox to indicate whether or not the alert is activated.

• API Key: Use this value in the header of your HTTP POST requests as x-api-key
• Alert URL: The URL for your custom alert. This is where you will send your POST requests when posting alerts to your custom alert. Each custom alert will have its own unique URL. 
• Alert name: This is the text label for your custom alert. It is not displayed to recipients. Use this to name the custom alert appropriately for your own internal purposes. 
• Auto launch scenario: Link an Omnilert Scenario that will automatically launch whenever this custom alert is activated by an external event. This is an optional setting. Use auto-launch with caution as Omnilert will launch the scenario every single time a triggering event occurs. 

'Activate this priority alert' This checkbox is used to enable/disable this custom priority alert. You must select at least one group (see next section) before this box can be checked. 

Groups

The Groups tab is used to indicate which group(s) will be sent a priority alert whenever an HTTP POST request for this custom alert is received.

Note: At least 1 group must be selected before you can activate your custom alert. 

Scenarios

The Scenarios tab is used to select one or more Omnilert Scenarios to link to this priority alert. Linked scenarios will be shown as buttons in the priority alert. The recipients can tap the button to launch the scenario from the Omnilert App.  

Creating Custom Priority Alert requests with the Priority Alert API

Custom Alerts are generated by sending Omnilert's server an HTTP POST request to the 'Alert URL' provided by Omnilert for your custom alert. 

The format of that POST request is detailed below. 

(In these examples, we're using "Postman" to generate the HTTP POST requests to Omnilert. Your application may be different, but the principle functionality would be the same. )

Request Header:

Your HTTP POST header section must include a value for x-api-key. That key value is the 'API Key' provided by Omnilert.

Request Body:

The body of your HTTP request should be JSON content. The following JSON fields are supported:

Example: Simple message

In its simplest form, your JSON content can just pass the 3 required fields to generate a priority alert.

As such, you could send something as simple as the following:

{ 
 "header": "This is sample alert",
 "title": "Test Message",
 "body": "This is a test message. This is only a test."
}

This would send a very simple priority alert with a header, title, and message.

Example: Simple message with media and map pin (location)

Next, we can enhance our message by sending links to media (images) and map coordinates. 

{
"header": "This is sample alert",
"title": "Test Message",
"body": "This is a test message. This is only a test.",
"media": [
   "https://img.yourserver.com/image.jpg",
   "https://img.yourserver.com/image2.jpg"
],
"location": {
   "lat": "40.73181029939087",
   "lng": "-73.98923340406425"
}
}

As you can see, your API calls can include multiple media links as well as map coordinates. (Map coordinates will automatically be converted into a map with a pin at that location.)

Priority Alert Actions

Customized "Priority Alert Actions" allow you to extend the functionality of Omnilert's Priority alert by integrating these alerts with third-party apps and services. Priority Alert Actions provide your priority alerts with usable buttons to activate those services. For example, you may want an option to post a message to a chat app, such as Slack, or activate an alarm. 

All of this is done by including an 'actions' block within your JSON content. An action block is a self-contained API call.

Each 'action' included in the 'actions' block creates a button in the Omnilert Priority Alert card. If/when a recipient taps on a button, that action's API call is run. 

The action block can contain the following elements:

Example: Custom Priority Alert with a Custom Action 

In this example, we have included the code to add a "Post to Slack" button as part of a simple alert. This button generates a simple "webhook" request to Slack and posts a "Hello World!" message.

{
"header": "This is sample alert",
"title": "Test Message",
"body": "This is a test message. This is only a test.",
"actions": [
 {
  "title": "Post to Slack",
  "text": "Post message to Slack!",
  "headers": {
       "Content-Type": "application/json"
    },
  "method": "POST",
  "url": "https://hooks.slack.com/services/T04KC7ARU/B0264P2BBR8/abcdefg",
  "data": {
     "text": "Hello, World! (This is a test)"
   }
 }
]
}

This simple block of code will generate a custom button within the Priority Alert. If/when a subscriber taps that button, the code executes, and a message is sent. (In this example, a message is sent to Slack saying "Hello, World! (This is a test)".)

Example: Custom Priority Alert with two or more Custom Actions

To include multiple buttons, simply include additional blocks within the 'actions' section of your JSON code.

In the example below, we've added a second section to POST to an alarm system server:

{
"header": "This is sample alert",
"title": "Test Message",
"body": "This is a test message. This is only a test.",
"actions": [
 {
  "title": "Post to Slack",
  "text": "Post message to Slack!",
  "headers": {
       "Content-Type": "application/json"
    },
  "method": "POST",
  "url": "https://hooks.slack.com/services/T04KC7ARU/B0264P2BBR8/abcdefg",
  "data": {
     "text": "Hello, World! (This is a test)"
   }
 },
 {
 "title": "Activate Alarm",
 "text": "Activate Alarm",
 "headers": {
 "Content-Type": "application/json"
 },
 "method": "POST",
 "url": "https://api.example.com/alarmserver",
 "data": {
   "access_code": "5551234"
   }
 }
]
}

Using this framework, any number of 3rd party devices and services can be integrated into your Omnilert Priority Alerts. Simply stack together the elements required by the destination service and Omnilert will make the request whenever your custom button is pressed.