Usage

Setup Overview

1. Create an Octopush Notification profile (Services > Alarming > Notification)
2. Enter the API Login and API Key, plus the optional Sender, Audit Profile, and Callback settings
3. Add each recipient's phone number as an SMS contact (see Configuration)
4. Add an Octopush notification block to an alarm pipeline and set its Message / Throttled Message / Voice options / With Reply / Test Mode and roster
5. For replies or delivery auditing, configure Octopush to POST callbacks to /system/octopush with the X-Ignition-Octopush-Token header (see Configuration)

---

Alarm Pipeline

Notification Block Parameters

Parameter	Type	Default	Description
Message	Expression	See below	Content of the message to send
Throttled Message	Expression	See below	Message when multiple alarm events are batched
Voice	Boolean	false	Send via Voice SMS (text-to-speech) instead of text SMS
Voice Gender	Enum	male	Voice gender: male or female
Voice Language	Enum	en-GB	Text-to-speech language: en-US, en-GB, el-GR, pl-PL, hu-HU, sv-SE, de-DE, es-ES, es-LA, fr-FR, it-IT, pt-BR, ru-RU
Voice Repeat	Integer	3	Number of times the whole spoken message is repeated (values <1 are clamped to 1)
With Reply	Boolean	false	Enable acknowledgement (SMS reply code, or voice keypress)
Test Mode	Boolean	false	Use Octopush simulation mode (no actual delivery)

---

Message Templates

Expression Syntax

The Message and Throttled Message fields support Ignition's expression syntax, allowing dynamic content based on alarm properties.

Default Message:

At {eventTime|hh:mm:ss}, alarm "{name}" at "{displayPath}" transitioned to {eventState}.

Default Throttled Message:

{alarmEvents.Count} alarm events have occurred.

Available Variables

Variable	Description	Example
{name}	Alarm name	High Temperature
{displayPath}	Alarm source path	Furnace/Zone1/TempSensor
{eventTime|format}	Event timestamp with format	{eventTime|hh:mm:ss}
{eventState}	Alarm state	Active, Cleared, Acknowledged
{alarmEvents.Count}	Number of throttled events	5

Message Examples

Simple notification:

ALARM: {name} is {eventState} at {eventTime|HH:mm}

Throttled events:

ATTENTION: {alarmEvents.Count} alarms require your attention.

---

SMS Text Notifications

Standard SMS notifications send a text message to all configured SMS contacts in the alarm roster, using the Octopush sms channel.

Characteristics:

• The optional Alphanumeric Sender (if configured) appears as the message sender (ignored for With-Reply messages)
• Message length and pricing depend on your Octopush plan

---

Voice SMS Notifications

When Voice is enabled, the module places an automated text-to-speech call (Octopush voice_sms channel) instead of sending a text message.

Characteristics:

• Text-to-speech synthesis reads the evaluated message
• Voice Gender (male / female), Voice Language, and Voice Repeat are configured on the notification block
• The whole spoken message is repeated Voice Repeat times (default 3)
• When With Reply is enabled, the message appends Press 1 to acknowledge. and keypresses made during the call are reported back to the gateway

---

Acknowledgement Flow

When With Reply is enabled, the module enables two-way acknowledgement. The mechanism differs between SMS and voice.

SMS Acknowledgement

1. The module appends Send <code> to acknowledge to the message, where <code> is a random integer in the range 0-99999 (1-5 digits; it is not a fixed 5-digit, zero-padded code)
2. The user receives the SMS and replies with the code
3. Octopush POSTs the reply to the callback servlet at /system/octopush
4. The alarm is acknowledged in Ignition

Example SMS (with reply):

At 14:03:21, alarm "High Temp" at "Furnace/Zone1" transitioned to Active. Send 48217 to acknowledge

Voice Acknowledgement

1. The spoken message appends Press 1 to acknowledge. (repeated Voice Repeat times)
2. If the recipient presses a key during the call, Octopush reports it to the callback servlet at /system/octopush - there is no code to key in
3. The keypress is correlated to the alarm by the call's Octopush ticket number
4. Key 1 acknowledges the alarm in Ignition. Any other key is recorded on the delivery audit record but does not acknowledge

Acknowledging is optional - the call is delivered either way, and pressing nothing simply leaves the alarm unacknowledged.

Callback required

Acknowledgement requires the callback servlet to be enabled (i.e. Disable Callback unchecked) and Octopush configured to POST to /system/octopush. See Configuration.

---

Test Mode

Enable Test Mode to use Octopush's simulation mode (simulation_mode). The request is processed by Octopush but nothing is actually sent.

Use cases:

• Testing alarm pipeline configuration
• Verifying API credentials are accepted
• Development and debugging

Simulation Mode

In test mode, the Octopush API validates the request and returns a ticket number, but no SMS or call is delivered. Check the gateway logs for confirmation.

---

Send Behavior (API detail)

Notifications are sent as an HTTP POST to:

https://api.octopush.com/v1/public/multi-channel/send

with headers Content-Type: application/json, api-login, and api-key. The JSON body includes:

• recipients: [{ phone_number }]
• purpose: "alert"
• sender: included when an Alphanumeric Sender is configured
• channel: "sms" or "voice_sms"
• metadata: for voice, adds type / voice_gender / voice_language; with-reply voice adds get_back_pressed_keys: true; with-reply SMS adds with_replies: true
• text: the evaluated message
• simulation_mode: included when Test Mode is enabled

---

Audit Logging

When an Audit Profile is configured on the notification profile, the module records the notification lifecycle. Audit actions include:

• SMS / Voice SMS Request
• SMS / Voice SMS Delivery
• SMS / Voice SMS Acknowledgement

Delivery and acknowledgement records depend on inbound callbacks, so they require the callback servlet to be enabled.

---

Troubleshooting

Issue	Possible Cause	Solution
Profile in error state	API Key secret cannot be retrieved	Fix the Ignition Secret (Embedded/Referenced) for the API Key
Notifications not sent	Invalid API credentials	Verify API Login and API Key in profile settings
Notifications not sent	Network issue	Check outbound HTTPS connectivity to api.octopush.com
Notifications not sent	Trial expired	Activate a license — see Licensing
Acknowledgement not working	Callback disabled	Uncheck Disable Callback on the profile
Acknowledgement not working	Callback not configured	Configure Octopush to POST to /system/octopush
Acknowledgement returns 403	Missing/incorrect auth header	Ensure Octopush sends the correct X-Ignition-Octopush-Token value
Acknowledgement not working	Firewall blocking	Allow inbound POST from Octopush to /system/octopush

---

Best Practices

1. Test first - Validate the pipeline with Test Mode enabled before going live
2. Use throttling - Configure appropriate throttling to avoid message floods
3. Enable auditing - Configure an Audit Profile for troubleshooting and compliance
4. Protect the callback - Set a Callback Authentication Secret and terminate TLS in front of the gateway
5. International format - Ensure all SMS contact phone numbers include country codes