Template Parameters

Each notification template has a type that determines which parameters are available. The type must match the trigger you plan to use it with — for example, an Alarm template can only be used in an alarm notification rule. For an overview of templates and rules, see Notification center.

When to use: Any notification that isn’t tied to a specific system event — maintenance announcements, custom broadcasts, or one-off messages sent manually or via the REST API.

Example:

Subject: Scheduled maintenance tonight, ${recipientFirstName:capitalize}
Message: Hi ${recipientFirstName:capitalize}, the platform will be offline for maintenance on March 5 from 2:00–4:00 AM UTC.

When to use: Alert engineers or operators when a device or asset alarm is created, changes severity, is acknowledged, cleared, or deleted. Pair with the Alarm notification rule and an escalation chain for on-call routing.

Example:

Subject: New ${alarmSeverity:upperCase} alarm: ${alarmType}
Message: ${alarmOriginatorEntityType} "${alarmOriginatorName}" triggered a ${alarmSeverity} alarm. Status: ${alarmStatus}.

Renders as: New CRITICAL alarm: High Temperature / Device “Compressor BJ-66” triggered a critical alarm. Status: ACTIVE.

Includes all General parameters, plus:

The alarm’s details JSON is flattened into separate parameters before the notification renders. Every key receives a details. prefix, and nested objects keep their full path:

A key whose value is a JSON array produces no parameter.

Which keys exist depends on how the alarm was created:

The details.<key> parameters belong to the Alarm type only. Alarm Comment and Alarm Assignment templates receive the alarm fields without its details.

A reading that caused the alarm, like a temperature or a signal level, is not a template parameter on its own. Store it in the alarm details first, then reference the key it lands under.

In the alarm rule, write Additional info as plain text with ${argumentName} placeholders:

RSSI ${RSSI} dropped below the threshold ${rssiThreshold}

The rule renders that text and stores it under the data key:

{
  "data": "RSSI -65 dropped below the threshold -70"
}

The template then reads that one key:

Subject: New ${alarmSeverity:upperCase} alarm: ${alarmType}
Message: ${alarmOriginatorName}: ${details.data}

Renders as: New CRITICAL alarm: Low Signal / Sensor T1: RSSI -65 dropped below the threshold -70.

To address each value through its own parameter, create the alarm from a rule chain with the Create alarm node instead. Its details script returns an object whose keys are preserved, so a script returning {"currentRssi": -65, "threshold": -70} exposes ${details.currentRssi} and ${details.threshold}. For details, see Enrich alarms with details.

When to use: Notify operators when a device goes offline unexpectedly or comes back online. Useful for monitoring field devices with intermittent connectivity.

Example:

Subject: Device "${deviceName}" is now ${eventType}
Message: Device "${deviceName}" (type: ${deviceType}) changed status to ${eventType}.

Renders as: Device “Compressor BJ-66” is now inactive / Device “Compressor BJ-66” (type: HVAC) changed status to inactive.

Includes all General parameters, plus:

When to use: Audit trail notifications when entities (devices, assets, customers, users) are created, modified, or deleted. Useful for change control in large teams.

Example:

Subject: ${entityType:capitalize} ${actionType} by ${userEmail}
Message: ${entityType} "${entityName}" was ${actionType} by ${userFirstName:capitalize} ${userLastName:capitalize} (${userEmail}).

Renders as: Device added by admin@company.io / Device “Sensor NM-12” was added by John Doe (admin@company.io).

Includes all General parameters, plus:

When to use: Keep the alarm owner or team in the loop when a colleague comments on an active alarm. Avoids the need to manually check the alarm timeline.

Example:

Subject: New comment on "${alarmType}" alarm
Message: ${userFirstName:capitalize} ${userLastName:capitalize} ${action} a comment on the ${alarmSeverity} alarm for "${alarmOriginatorName}": "${comment}"

Renders as: New comment on “High Temperature” alarm / Jane Smith added a comment on the critical alarm for “Compressor RK-25”: “Checked on-site — coolant level is low.”

Includes all Alarm parameters except details.<key>, plus:

When to use: Notify the assigned engineer when an alarm is routed to them, or notify the team when an alarm is unassigned.

Example:

Subject: Alarm "${alarmType}" assigned to you
Message: ${userEmail} assigned a ${alarmSeverity} alarm on "${alarmOriginatorName}" to ${assigneeEmail}.

Renders as: Alarm “High Temperature” assigned to you / supervisor@company.io assigned a critical alarm on “Compressor BJ-66” to engineer@company.io.

Includes all Alarm parameters except details.<key>, plus:

When to use: Alert developers or platform admins when a rule chain or node fails to start, typically due to misconfiguration after a deployment or update.

Example:

Subject: ${action:capitalize} failure in rule chain "${ruleChainName}"
Message: ${componentType:capitalize} "${componentName}" failed to ${action}. Error: ${error}

Renders as: Start failure in rule chain “Root Rule Chain” / Rule node “Kafka Producer” failed to start. Error: Connection refused to broker:9092.

Includes all General parameters, plus:

When to use: Build fully custom notifications from within a rule chain using the Send notification node. The message can include any field from the incoming message’s data or metadata — for example, a telemetry reading or a calculated value.

Example (incoming message data contains temperature and deviceName):

Subject: High temperature alert on ${deviceName}
Message: ${deviceName} reported ${temperature}°C, which exceeds the safe threshold.

Renders as: High temperature alert on Boiler A / Boiler A reported 94°C, which exceeds the safe threshold.

Includes all General parameters, plus:

When to use: Alert Tenant Administrators when a data integration fails to start or stops unexpectedly, typically due to misconfiguration or an unreachable external service.

Example:

Subject: ${integrationType} integration start failure
Message: Integration "${integrationName}" failed to start. Error: ${error}

Renders as: MQTT integration start failure / Integration “Factory MQTT” failed to start. Error: Connection refused to mqtt.factory.io:1883.

Includes all General parameters, plus:

When to use: Notify Tenant Administrators when an Edge instance connects or disconnects from the cloud, so they can respond to outages at remote sites.

Example:

Subject: Edge "${edgeName}" connection status changed
Message: Edge "${edgeName}" is now ${eventType}.

Renders as: Edge “Factory Floor A” connection status changed / Edge “Factory Floor A” is now disconnected.

When to use: Alert admins to specific failures during Edge synchronization, such as data sync errors or command delivery failures — distinct from a full disconnect.

Example:

Subject: Communication failure on Edge "${edgeName}"
Message: Edge "${edgeName}" reported a communication failure: ${failureMsg}

Renders as: Communication failure on Edge “Warehouse B” / Edge “Warehouse B” reported a communication failure: Failed to sync telemetry batch — timeout after 30s.

When to use: Warn Tenant Administrators before they hit their entity quota (devices, assets, etc.), giving them time to request a limit increase. Available to System Administrators only.

Example:

Subject: ${entityType} limit will be reached soon for "${tenantName}"
Message: ${entityType} usage for tenant "${tenantName}": ${currentCount} of ${limit} (${percents}%).

Renders as: Device limit will be reached soon for “Acme Corp” / Device usage for tenant “Acme Corp”: 800 of 1000 (80%).

Includes all General parameters, plus:

When to use: Warn Tenant Administrators before they exhaust an API feature quota — for example, approaching the monthly alarm limit or message count. Available to System Administrators only.

Example:

Subject: ${feature} limit warning for "${tenantName}"
Message: ${feature} is ${status:upperCase} for tenant "${tenantName}": ${currentValue} of ${limit} ${unitLabel}s used.

Renders as: Alarms limit warning for “Acme Corp” / Alarms is WARNING for tenant “Acme Corp”: 8000 of 10000 alarms used.

Includes all General parameters, plus:

When to use: Inform System Administrators and Tenant Administrators when a new ThingsBoard release is available so they can plan upgrades. Available to System Administrators only.

Example:

Subject: ThingsBoard ${latestVersion} is available
Message: A new version is available. You are on ${currentVersion}. Upgrade to ${latestVersion}: ${upgradeInstructionsUrl}

Renders as: ThingsBoard 3.7.0 is available / A new version is available. You are on 3.6.4. Upgrade to 3.7.0: /docs/installation/upgrade-instructions/

Includes all General parameters, plus:

When to use: Alert System Administrators when a tenant or device is being throttled due to rate limit violations — useful for diagnosing data loss or connectivity issues. Available to System Administrators only.

Example:

Subject: Rate limits exceeded for "${limitLevelEntityName}"
Message: Rate limits for "${api}" were exceeded by ${limitLevelEntityType} "${limitLevelEntityName}" (tenant: ${tenantName}).

Renders as: Rate limits exceeded for “Acme Corp” / Rate limits for “REST API requests” were exceeded by Tenant “Acme Corp” (tenant: Acme Corp).

Includes all General parameters, plus:

Wrap any parameter name in ${...} — for example, ${recipientFirstName}. Apply a suffix after a colon to transform the value:

Tip: Combine parameters with plain text to compose natural sentences. For example:

Subject: New ${alarmSeverity:upperCase} alarm on ${alarmOriginatorName}
Message: Hi ${recipientFirstName:capitalize}, a ${alarmSeverity} alarm of type "${alarmType}" was ${action} on device "${alarmOriginatorName}".

Renders as: New CRITICAL alarm on Compressor BJ-66 / Hi Jane, a critical alarm of type “High Temperature” was created on device “Compressor BJ-66”.