Guides

Video Activated Alarms

ℹ️

Geographic Coverage

The Noonlight Dispatch API is only supported in the US (all 50 states)

1. Set up your developer account

First, you need to sign in to our developer portal to retrieve your sandbox server token. This server token will be used to interact with the Dispatch API from your backend services.

⚠️

Your server token is considered sensitive and it is your responsibility to protect it. It should not be in client-side source code or configs.

2. Create an alarm

In order to send in video footage for Noonlight to review, you'll first need to "create an alarm".

In order to create an alarm, you will need to make sure you have:

  • Primary user’s name
  • Verified phone number
  • Location (address for home or business, as opposed to coordinates, is required for static alarms)
  • PIN (optional)
  • Type of emergency services (optional; defaults to police)

ℹ️

PIN

We generally encourage partners to require a PIN for end user cancelation of alarms. That said, this is not a requirement. Should you choose to leverage a PIN to verify the cancelation of an alarm, you would need to pass that information in when creating the alarm.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'

const alarm = await request({
  method: 'POST',
  url: 'https://api-sandbox.noonlight.com/dispatch/v1/alarms',
  auth: { bearer: token },
  body: {
    location: {
      address: {
        line1: "123 Some Street",
        city: "St. Louis",
        state: "MO",
        zip: "63101"
      }
    },
    name: "John Smith",
    phone: "15554440003",
    pin: "1234"
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
     "location":{
        "address":{
           "line1":"123 Some Street",
           "city":"St. Louis",
           "state":"MO",
           "zip":"63101"
        }
     },
     "name":"John Smith",
     "phone":"15554440003",
     "pin":"1234"
  }'

3. Updating the alarm

Once the alarm is created, you have the ability to pass in additional information which can be leveraged to enhance the efficacy of the resolution process. With more information, we have the ability to verify the alarm, contact other household members to cancel/verify the alarm, etc.

Examples of the types of information that can be added to an alarm are below:

  • Add event specific data:
    • Type and name of the device associated with alarm origination
    • Type, name, time of subsequent and likely related events
  • Add additional people to the alarm

Details related to each of the items above can be found below.

3.1 Adding video as the triggering event to an alarm

Indicate "camera" as the “triggering event” to send in the footage associated with the alarm for Noonlight's dispatcher to review.

Event TypeDescription
alarm.device.activated_alarmWhen triggered automatically by a sensor
alarm.person.activated_alarmWhen triggered manually by a person on a sensor event within your application
import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/events`,
  auth: { bearer: token },
  body: [
    {
      meta: {
        attribute: "camera",
        value: "unknown",
        device_model: "some_model",
        device_name: "some_name",
        device_manufacturer: "some_manufacturer",
        media: "https://noonlight-assets.s3.us-east-2.amazonaws.com/sample-videos/sample-security-video-4.mp4"
      },
      event_type: "alarm.device.activated_alarm",
      event_time: "2020-04-02T08:11:36Z"
    }
  ],
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/events \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[
    {
      "meta":{
        "attribute":"camera",
        "value":"unknown",
        "device_model":"some_model",
        "device_name":"some_name",
        "device_manufacturer":"some_manufacturer",
        "media":"https://noonlight-assets.s3.us-east-2.amazonaws.com/sample-videos/sample-security-video-4.mp4"
      },
      "event_type":"alarm.device.activated_alarm",
      "event_time":"2020-04-02T08:11:36Z"
    }
  ]'

3.2 Adding additional people to an alarm (optional)

If you would like to notify or allow people other than the primary user to cancel the alarm, for example if you’re creating a home alarm and want to allow household members to cancel, then you can do so using the create people endpoint. We will handle reaching out to the additional people as appropriate for your use-case.

In order to add additional people, you will need to have:

  • Associated individual’s name
  • Verified phone number
  • PIN (optional)

ℹ️

Currently there is no limit on how many people you can add to an alarm, but you can only call this endpoint once per alarm.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/people`,
  auth: { bearer: token },
  body: [
    {
      name: "Sue Smith",
      phone: "14445550003"
    },
    {
      name: "Sam Smith",
      phone: "15554440002"
    }
  ],
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/people \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '[
    {
      "name":"Sue Smith",
      "phone":"14445550003"
    },
    {
      "name":"Sam Smith",
      "phone":"15554440002"
    }
  ]'

4. Digesting status updates via webhooks (optional)

After an alarm is created, Noonlight sends webhooks for actions taken by Noonlight dispatchers throughout the handling of an alarm - you can view those events and descriptions below. They are typically leveraged to modify UX or for reporting purposes.

Event TypeDescription
alarm.status.canceledThe alarm being canceled by the user through the Noonlight dispatcher via text/call.
alarm.closedThe alarm being closed by the Noonlight dispatcher.
alarm.psap_contactedAn outbound call to the PSAP. This event can happen multiple times.

ℹ️

Noonlight includes a signature in each webhook’s X-Noonlight-Signature header. This allows you to verify that the webhooks were sent by Noonlight, not a third party. To verify signatures, you can compare the X-Noonlight-Signature header with the Base64 encoded HMAC hash of the webhook body - if they match, then the webhook came from Noonlight. You can see an example of how to do this in Node.js below.

import http from 'http'
import express from 'express'
import bodyParser from 'body-parser'
import { createHmac } from 'crypto'

const app = express()

app.server = http.createServer(app)

app.use(bodyParser.json())

app.post('/webhook', (req, res) => {
  
  // See your secret here: https://developer.noonlight.com/app/dashboard
  const webhookSecret = 'somesecret'
  
  const signature = createHmac('sha256', webhookSecret)
    .update(JSON.stringify(req.body))
    .digest('base64')
  
  if (signature === req.get('X-Noonlight-Signature')) {
    return res.sendStatus(200)
  }
  
  res.sendStatus(401)
})

app.server.listen(process.env.PORT, () => {
  console.log(`Started on port ${app.server.address().port}`)
})

export default app

5. Canceling alarms (optional)

Typically this is user initiated, enabled by you exposing the ability for a user to request to cancel; but can also be done without user involvement in situations where your platform is confident the alarm is not associated with an emergency.

User’s always have the ability to cancel via text/call with Noonlight dispatchers.

If the user cancels the alarm after emergency services have already been dispatched to the PSAP, our request to cancel could be ignored and a wellness check on the user might still be conducted. This is at the discretion of the PSAP, but we will always notify the PSAP that the user has canceled.

import request from 'request-promise'

// Set your server token.
// See your token here: https://developer.noonlight.com/app/dashboard
const token = 'YOUR_SERVER_TOKEN'
const alarmId = 'ALARM_ID_FROM_CREATE_ALARM'

const response = await request({
  method: 'POST',
  url: `https://api-sandbox.noonlight.com/dispatch/v1/alarms/${alarmId}/status`,
  auth: { bearer: token },
  body: {
    status: "CANCELED",
    pin: "1234"
  },
  json: true
})

curl \
  --request POST \
  --url https://api-sandbox.noonlight.com/dispatch/v1/alarms/YOUR_ALARM_ID/status \
  --header 'accept: application/json' \
  --header 'authorization: Bearer YOUR_SERVER_TOKEN' \
  --header 'content-type: application/json' \
  --data '{
     "status":"CANCELED",
     "pin":"1234"
  }'

Updated almost 2 years ago