Skip to main content

Alarms and Notifications

Configuring alerts and delivering notifications when conditions are met.

Overview​

Beacon Tower's alarm system monitors telemetry data in real time and triggers notifications when specified conditions are met. Alarms are rules associated with asset models that check telemetry values against thresholds, while notifications route alerts to appropriate users via email and SMS.

Alarm Rules​

An alarm is a rule defined on telemetry data that triggers when specific conditions are met. Each alarm definition is associated with an asset model, which determines which telemetry values and assets can be monitored.

Key Components​

Every alarm rule consists of:

  • Name: Human-readable identifier for the alarm
  • Type: Classification of the alarm condition
  • Asset Model Association: The entityTypeId determines which assets can trigger this alarm
  • Scope: Monitor all assets of a model, or limit to specific assets via entityIds
  • Condition: A telemetry point, comparison operator, and threshold value
  • Severity: Integer value from 1 (lowest) to 5 (highest) indicating alarm priority

How Alarm Checking Works​

Alarm conditions are evaluated every time telemetry data arrives for the monitored assets. When a value crosses the threshold:

  1. The alarm triggers immediately
  2. It remains active until both conditions are met:
    • The telemetry value returns below the threshold
    • A user acknowledges the alarm

Best Practice: When possible, base alarms on device alarm codes (e.g., a device sending 1 for alarm, 0 for normal) rather than raw sensor values. This reduces false positives and leverages device-level intelligence.

Scoping Alarms​

You can configure alarms to monitor:

  • All assets of a model: Recommended approach to reduce administrative overhead. Any asset of the specified type can trigger the alarm.
  • Specific assets only: Useful for special monitoring requirements, but requires updating the alarm definition when assets are added or removed.

Creating an Alarm​

curl -X POST https://api.beacontower.ai/v1/alarms \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "High Temperature Warning",
    "description": "Alert when temperature exceeds 75 degrees",
    "entityTypeId": "dtmi:com:example:TemperatureController;1",
    "entityIds": [],
    "condition": "{\">\": [{\"var\": \"temperature\"}, 75]}",
    "severity": 3
  }'

The condition field uses JSONLogic syntax to define the alarm rule. For example, {">" : [{"var": "temperature"}, 75]} checks if temperature is greater than 75.

For more details, see the Alarm endpoints in the API Reference.

Alarm States​

Alarms transition through three distinct states based on telemetry values and user acknowledgment:

StateVisual IndicatorDescription
Active, Not AcknowledgedRed alarm iconTelemetry exceeds the rule threshold and no user has acknowledged the alarm yet. Requires immediate attention.
Active, AcknowledgedRed icon with green checkmarkTelemetry still exceeds threshold, but a user has acknowledged the alarm. Indicates the issue is known and being addressed.
Inactive, Not AcknowledgedYellow warningTelemetry value has returned below the threshold, but the alarm has not yet been acknowledged. Requires user review to clear.

Once an alarm is both inactive and acknowledged, it disappears from active alarm lists. This state machine prevents alarm spam: an alarm triggers only once and won't re-trigger until it has been acknowledged and the value returns below threshold.

Checking Alarm Status​

# Get all active alarm statuses for alarms accessible to the user
curl -X GET https://api.beacontower.ai/v1/alarms/status \
  -H "X-API-Key: YOUR_API_KEY"

# Get alarm status for a specific entity (asset)
curl -X GET https://api.beacontower.ai/v1/alarms/status/entity/{entityId} \
  -H "X-API-Key: YOUR_API_KEY"

# Acknowledge an alarm by alarm status ID
curl -X PUT https://api.beacontower.ai/v1/alarms/status/acknowledge/{alarmStatusId} \
  -H "X-API-Key: YOUR_API_KEY"

Notifications​

Notifications are triggered automatically when an alarm activates, delivering alerts to users through email and SMS channels. This system ensures the right people are informed immediately when critical conditions occur.

How Notifications Work​

When an alarm first transitions to the active state:

  1. Beacon Tower checks which notifications are mapped to that alarm
  2. For each notification, it resolves the recipient list based on contact groups
  3. Messages are sent via configured channels (email, SMS, or both)

Important: Notifications are sent only when an alarm is first created — they are not re-sent if the alarm remains active. This prevents notification spam from telemetry values that fluctuate around the threshold. A new notification will only be sent after the alarm has fully cleared (inactive and acknowledged) and then triggers again.

Notification Components​

A notification definition includes:

  • Display Name: Human-readable identifier
  • Description: Purpose or context for the notification
  • Trigger: An object containing alarmTrigger — a list of alarm definition IDs that activate this notification
  • Broadcast: Whether to send to all eligible users in the organization
  • Channels: Configuration for email and/or SMS delivery, including templates, sender, and subject
  • Organization ID: The organization this notification belongs to
  • Subscribers: Contact groups that receive the notification

Notification Recipients and Organization Access​

Best practice: Use default contacts configured at the organization level. This allows notifications to automatically route to the appropriate users based on which asset triggers the alarm, without requiring per-notification recipient management.

For a user to receive a notification, their organization must have access to:

  • The asset that triggered the alarm
  • The alarm definition
  • The notification itself

See Organizations and Permissions for details on managing access.

Notification Content Variables​

Notification messages support these template variables:

  • {{alarmName}}: The name of the triggered alarm
  • {{assetName}}: The asset that triggered the alarm
  • {{ackUrl}}: Direct link to acknowledge the alarm in the UI

Creating a Notification​

curl -X POST https://api.beacontower.ai/v1/notifications \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Critical Temperature Alerts",
    "description": "Notifications for high temperature alarms",
    "trigger": {
      "alarmTrigger": ["alarm-uuid-here"]
    },
    "broadcast": false,
    "channels": {
      "email": {
        "active": true,
        "template": "{{alarmName}} triggered on Asset: {{assetName}}. Click here to acknowledge: {{ackUrl}}",
        "from": "alerts@example.com",
        "subject": "Temperature Alert"
      },
      "sms": {
        "active": true,
        "template": "{{alarmName}} - {{assetName}}. Acknowledge: {{ackUrl}}",
        "from": "BeaconTower"
      }
    },
    "organizationId": "org-uuid-here"
  }'

Managing Notification Subscribers​

# Add a contact group to a notification
curl -X POST https://api.beacontower.ai/v1/notifications/{notificationId}/subscribers \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "contactGroupId": "group-uuid-here"
  }'

# Remove a subscriber (contact group)
curl -X DELETE https://api.beacontower.ai/v1/notifications/{notificationId}/subscribers/{contactGroupId} \
  -H "X-API-Key: YOUR_API_KEY"

For complete API documentation, see the Notification endpoints in the API Reference.

Contact Groups​

Contact groups organize users and user groups for notification routing. They provide a flexible way to define who should be notified when specific alarms trigger, without hardcoding recipient lists in each notification.

Contact Group Structure​

A contact group contains:

  • Display Name: Human-readable identifier
  • Description: Purpose or scope of this group (optional)
  • Organization ID: The organization that owns this contact group
  • User Groups: Collections of users defined in your organization (optional)
  • Users: Individual users to notify (optional)

Creating a Contact Group​

curl -X POST https://api.beacontower.ai/v1/contactgroups \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Facilities Team",
    "description": "Building management and maintenance staff",
    "organizationId": "org-uuid-here",
    "userGroups": ["usergroup-uuid-1"],
    "users": ["user-uuid-1", "user-uuid-2"]
  }'

Updating Contact Groups​

curl -X PATCH https://api.beacontower.ai/v1/contactgroups/{contactGroupId} \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "displayName": "Updated Facilities Team",
    "users": ["user-uuid-1", "user-uuid-2", "user-uuid-3"]
  }'