Send alarms using REST

How to submit alarms to evalink talos programmatically.

To send an alarm via a REST API method, you need to submit the following request:

create a simple alarm via the API

POST https://talos.evalink.io/api/alarm-service/alarms

Use this endpoint to send an alarm in evalink talos for a specific site (device) and company. NOTE: The endpoint might respond with HTTP 406 Not Acceptable - this should be treated as success. HTTP 406 means that talos is configured to not accept this particular alarm, but the transmission itself was successful. NOTE: The endpoint might respond with HTTP 400 Bad Request - you should not retry the transmission. When the endpoint returns HTTP 400 it means that something is wrong with your request, in this case the client should declare a failure and not retry transmission of the alarm as any subsequent transmission will also fail.

Headers

Name
Type
Description

Authorization

string

Use 'Bearer' followed by your API token.

Request Body

Name
Type
Description

evalinkDeviceId

string

Alternatively to providing the deviceId field you can provide the evalinkDeviceId to identify the Site. (max 30 characters).

timestamp

number

Time of alarm occurrence in milliseconds

source

string

Name of the system where the alarm originated from (e.g. virtual-vds-receiver, talos-ui)

alarmMsg

string

Optional message to show alongside the alarm code, if not provided the message is chosen from the alarm definition

alarmDefinition

string

The name of an existing alarm definition in the talos company - if not provided the proper alarm definition is selected automatically

testMessage

boolean

Optional flag to mark an alarm as testMessage

alarmValue

boolean

The alarmValue of the alarm, true = alarm, false = restore. For SIA this field isn't required because the alarm values are defined in the talos alarm definitions.

headers

string

A list of key/value pairs to add arbitrary information to the alarm like video verification, geolocation, messages etc.

partitionName

string

The readable name of the partition where the alarm occurred

partition

string

The partition id where the alarm occurred (also known as "area")

alarmZoneName

string

The readable name of the zone where the alarm occurred

alarmZone

string

The zone id where the alarm occurred

companyId

string

The Company ID, as it is displayed on the evalink talos Web Interface. (At the API Token page) - 36 characters.

deviceId

string

The Device ID, as it is displayed in the evalink talos interface. (In the URL when looking at a Site) - 32 characters. Alternatively you can also provide the evalinkDeviceId field and talos will internally resolve it to the correct deviceId.

alarmCode

string

The relevant alarm code, e.g. 100, 101, FA etc. - can be any string, but its best to follow a defined alarming standard.

{
    "id": "5e85a1a278fd457b997dc35a54058XXX",
    "shortId": "7534-6539",
    "headers": [
        {
            "name": "x-tags",
            "value": "centralsite;headquarters"
        }
    ],
    "companyId": "bc2b4013-664a-46ab-a1be-a85c31a6xxxx",
    "deviceId": "8a81b69d749bc70f0174b0db7b9dxxxx",
    "deviceGroupId": "8a81cfd075080abb01752c2db145XXXX",
    "alarmStatus": "IN_WORK",
    "timestamp": 1607598290721,
    "alarmStoredTimestamp": 1607598290721,
    "source": null,
    "testMessage": false,
    "messageId": null,
    "payload": null,
    "alarmValue": true,
    "alarmCode": "BA",
    "alarmMsg": null,
    "alarmZone": null,
    "alarmZoneName": null,
    "partition": null,
    "partitionName": null,
    "technical": false,
    "alarmType": "BURGLARY",
    "severity": 6,
    "definition": "sit:SIA",
    "channelId": null
}

Example Request:

{
  "companyId": "<companyId>",
  "deviceId": "<deviceId>",
  "alarmCode": "BA",
  "alarmValue": true,
  "timestamp": 1629981339172,
  "alarmZone": "1",
  "alarmZoneName": "Garage",
  "partition": "5",
  "partitionName": "Office Building",
  "source": "virtual-dc09-receiver",
  "headers": [
    {
      "name": "latitude",
      "value": "38.8951"
    },
    {
      "name": "longitude",
      "value": "-77.0364"
    },
    {
      "name": "message",
      "value": "Some message that is shown in the alarm list"
    },
    {
      "name": "attachment.url",
      "value": "https://some-url-to-show-the-operator"
    },
    {
      "name": "attachment.image",
      "value": "https://url-to-some-image"
    },
    {
      "name": "attachment.widget",
      "value": "src=https://url-to-a-widget-website;height=300px"
    },
    {
      "name": "attachment.talos.video",
      "value": "/api/storage-service/uploads/{file-id}"
    },
    {
      "name": "attachment.talos.image",
      "value": "/api/storage-service/uploads/{file-id}"
    },
    {
      "name": "attachment.talos.file",
      "value": "/api/storage-service/uploads/{file-id}"
    }
  ]
}

Last updated