Alarmbridge

Download OpenAPI specification:Download

alarmbridge_0

The Alarmbridge API exposes endpoints that allow alarm events using various IP based or analogue protocols to be sent by the platform.

It also provides functions that interact with ongoing alarm sessions such as properly clear and hang up an ongoing analogue alarm call.

The implicit_callbacks endpoint provides documentation of the various callbacks sent by the service, for example callback events triggered when an alarm event is received by the platform.

Alarmbridge API Endpoints

Base url: https://api.prod-eu-north-1.iotcomms.io/alarmbridge

/{domain}/devicecommand

POST

Send commands within a voice session to an alarm device.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required

This API endpoint will send send commands within a voice session that is established via Alarmbridge to the alarm device.

The Alarmbridge service destination must have the controlCommandsEnabled:true configuration for this function to work.

replyId
string

Set this to the value of replyId received in the /newAlarmbridgeEvent callback request that started the call to be terminated.

sessionId
string

The id for the Alarmbridge session that executes the command. This session id was passed in the /newAlarmbridgeEvent callback request.

object

Object to send command parameters. Currently only applicable for sendTones command.

duration
integer

Duration of each digit sent in DTMF string in milliseconds. Optional value where default is 80ms.

toneString
string

String of DTMF tones to be sent to alarm device when invoking the sendTones command.

command
string
Enum: "keepAlive" "clearDown" "listen" "releaseDoorLock1" "releaseDoorLock2" "releaseSafeLock" "resetSpeechSettings" "selectSpeaker1" "selectSpeaker2" "sendTones" "setVolumeLevel1" "setVolumeLevel2" "setVolumeLevel3" "speak" "switchToDuplex" "switchToSimplex" "volumeDown" "volumeUp"

The command to be sent to the device

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "replyId": "string",
  • "sessionId": "string",
  • "parameters": {
    • "duration": 0,
    • "toneString": "string"
    },
  • "command": "keepAlive"
}

Response samples

Content type
application/json
{
  • "success": true
}

/{domain}/devicecommand

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

/{domain}/hangupalarmcall

POST

Hang up an ongoing Alarmbridge call with normal disconnect reason.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required

When an alarm device has a connected voice call with an alarm center it must be sent a protocol specific command before the call is hung up. If this is not sent the device will think the call was hung up due to failure and will re-dial.

Call this API endpoint to trigger such command to be sent to have the alarm call properly disconnected.

replyId
string

Set this to the value of replyId received in the /newAlarmbridgeEvent callback request that started the call to be terminated.

sessionId
string

The id for the Alarmbridge session that executes the command. This session id was passed in the /newAlarmbridgeEvent callback request.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
success
boolean

Indicates if the API call was successful or not

Request samples

Content type
application/json
{
  • "replyId": "string",
  • "sessionId": "string"
}

Response samples

Content type
application/json
{
  • "success": true
}

/{domain}/hangupalarmcall

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

/{domain}/sendalarmevent

POST

Trigger alarm event to be sent by the Alarmbridge function.

Authorizations:
jwtAuthorizer
path Parameters
domain
required
string
Request Body schema: application/json
required

This API endpoint will send an IP based or analogue alarm event to the specified destination with the selected protocol and alarm parameters. If the eventReceiver property is used an alarmbridge eventreceiver will be matched to find a corresponding eventsender. In that case all parameters to send the actual alarm event is set by the eventsender in the alarmbridge configuration, for example protocol and destination address.

It is an asynchronous function so the API call will return immediately when alarm sending starts and subsequent callback requests will indicate if the alarm was sent successfully or if it failed.

The callback are documented in the implicit_calbacks section.

traceId
string

If a traceId parameter is given then it is used instead of an internally generated UUID. The traceId will be present in all responses, messages, callbacks and alarms sent from the service.

sipFrom
string

Value to be set the user part of the SIP from: URI, used to set calling party number. For example +46890510

toneHandler
string
Value: "transparent"

Indicate what kind of transformation is done to the incoming DTMF tones sent from the ARC towards the device.

object

Set properties how to send DTMF tones for Alarmbridge service destination.

calleeDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

callerDtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

dtmfSendType
string
Enum: "2833" "inaudio"

Set this property to control how DTMF tones are sent to remote destinations. Type inaudio which is default injects tones in the audio RTP stream. Type 2833 use RFC2833 tone packets in the RTP stream.

object

The protocolParameters property is an object used to pass on target protocol parameters that are specific for the event sent.

resendAlarmInterval
integer

This optional property is adjusting the re-send interval for analogue alarm events in case they are not acknowledged. Value in milliseconds.

sendAlarmStringDelay
integer

This optional property is adjusting the time to wait to send the initial alarm string after data request tone have been received for analogue alarm events. Value in milliseconds.

object

This property is used to define the alarm event to be sent. It is a a format that is protocol independent and therefore possible to be mapped to the supported protocol specific events.

deviceType
string
Enum: "fixedTrigger" "personalTrigger" "fallDetector" "personalAttackPendent" "panicAlarmButton" "dutySwitch" "dutySwitchRemote" "pillDispenser" "bedMonitor" "matSensor" "doorSensor" "enuresisDetector" "epilepsyDetector" "occupancyDetector" "environmentalMonitor" "naturalGasDetector" "lightningCircuitMonitor" "smokeDetector" "heatingMonitor" "heatDetector" "carbonMonoxideDetector" "bogusCallerSwitch" "intruderDetector" "boundaryDetector" "automaticPersonDown" "systemMonitor" "communicationLinkMonitor" "floodDetector" "bathSensor" "dcPowerSupply" "chairMonitor" "fireAlarm" "monitoringDevice" "radioUnit" "heartbeat" "activityDetector" "unknown" "localUnit" "wanderingSensor" "heartRateMonitor" "perimeter" "sprinkler" "tamper" "printer" "router" "lock" "accessController" "controller" "elevator" "trackingDevice"

The type of device raising the alarm.

controllerId
string

The id of the controller sending the event. NOTE: Different protocols have limits on the string content. BS8521 support a string of length 12 if no deviceId is passed, or a string of lenght 8 if deviceId is passed. Only digits 0-9 allowed.

deviceComponent
string
Enum: "switch1" "switch2" "button1" "button2" "button3" "automatic1" "automatic2" "module1" "module2" "module3" "module4" "module5" "unspecified"

Indicates the trigger type of the alarm for the device

systemConfig
string
Enum: "localUnitAndController" "groupedSupervisorOffDuty" "groupedSupervisorOnDuty" "groupedSupervisorOnDutyArc"

Indicates the configuration mode of the device information sent in the alarm.

location
string
Enum: "unknown" "outdoors" "outside" "basement" "bathRoom" "bedRoom" "diningRoom" "floor" "garage" "garden" "gardenBack" "gardenFront" "gym" "kitchen" "laundry" "stairs" "studyRoom" "workshop" "loft" "shed" "summerHouse" "handicapWC" "door" "frontDoor" "backDoor" "fireDoor" "hallwayUpstairs" "hallwayDownstairs" "livingRoom" "lounge" "communalArea" "office" "room"

Indicates the location of the device raising the alarm

callerId
string

This value is mapped to caller-id specific fields in target protocol, such as <crd> for SCAIP.

eventType
string
Value: "common"

Indicates the type of event passed. Currently only the common type is supported, which is automatically mapped to the protocol specific event types.

audio
string
Enum: "none" "simplex" "duplex"

Indicates the audio capabilities supported by the device for the alarm event. Set to none if no follow up voice call is expected.

priority
number

Sets the priority for the alarm event, allowed values are the range 0-9 where 0 is lowest priority and 9 is highest

deviceId
string

The id a device attached to the controller sending the event. NOTE: Different protocols have limits on the string content. BS8521 support a string of length 4. Only digits 0-9 allowed.

customerSiteId
string

It will also be used as to prefix controllerId:deviceId string for alarm device authentication lookup against provisioned devices. A provisioned devices identifier must be unique for a tenant, and this prefix allow different customer sites to use overlapping controllerId:deviceId configurations.

statusCode
string
Enum: "normal" "privacySwitchOperated" "faultRectified" "lowBattery" "busy" "outOfService" "occupied" "open" "online" "offline" "temperatureHigh" "temperatureLow" "temperatureRateOfRise" "communicationLinkIPFailure" "communicationLinkPrimaryFailure" "communicationLinkRedundantFailure" "communicationLinkPOTSFailure" "tamper" "absent" "failure" "malfunction" "inactive" "acknowledge" "trespass" "maintenanceScheduled" "maintenanceUrgent" "cancel" "presencePlanned" "resetAutomatic" "resetManual" "pillTaken" "disconnected" "inBed" "highLevel" "pillReminder" "pillNotTaken" "activated" "alarm" "alarmManual" "alert" "batteryFailure" "batteryFull" "closed" "communicationLinkGSMFailure" "powerFailure" "powerRestored" "presenceUponAlarm" "reset" "restoral" "rfInterference" "stopped" "checkout" "communicationLinkIPRestored" "communicationLinkGSMRestored" "communicationLinkPOTSRestored" "movement" "present" "radioTestFailed" "radioTestRestored" "armed" "offIndication" "onIndication" "locked" "unauthorizedAccess"

Indicates the alarm status for the alarm

eventReceiver
string

The eventReceiver string is matched to the value of the destinationMatch field of the eventReceiver provisioned earlier.

callbackSipFrom
string

the SIP From header used for the voice call towards the device.

protocol
string
Enum: "bs8521" "scaip"

The alarm protocol to be used to send the event.

alarmVoiceCallbackDestination
string

The destination address to do a voice callback to. Normally the alarm device.

password
string

the password to use for SIP authentication.

destAddr
string

The destination address for the alarmEvent, it must be a SIP URL of format sip:destination@domain.

username
string

the username to use for SIP authentication.

defaultEmergencyDestination
string

This parameter specifies the voice destination address in case of CRE61. Can be overriden when provisioning the alarmEventMapper.

Responses

Response Headers
Access-Control-Allow-Origin
string
Response Schema: application/json
traceId
string

An id that is common to an entire call and is used for trcing of calls.

success
boolean

Indicates if the API call was successful or not

sessionId
string

The session id created by the operation performed.

message
string

A textual description of what operation has been performed. Informational only.

Request samples

Content type
application/json
{
  • "traceId": "string",
  • "sipFrom": "string",
  • "toneHandler": "transparent",
  • "toneSettings": {
    • "calleeDtmfSendType": "2833",
    • "callerDtmfSendType": "2833",
    • "dtmfSendType": "2833"
    },
  • "protocolParameters": {
    • "resendAlarmInterval": 0,
    • "sendAlarmStringDelay": 0
    },
  • "alarmEvent": {
    • "deviceType": "fixedTrigger",
    • "controllerId": "string",
    • "deviceComponent": "switch1",
    • "systemConfig": "localUnitAndController",
    • "location": "unknown",
    • "callerId": "string",
    • "eventType": "common",
    • "audio": "none",
    • "priority": 0,
    • "deviceId": "string",
    • "customerSiteId": "string",
    • "statusCode": "normal"
    },
  • "eventReceiver": "string",
  • "callbackSipFrom": "string",
  • "protocol": "bs8521",
  • "alarmVoiceCallbackDestination": "string",
  • "password": "string",
  • "destAddr": "string",
  • "username": "string",
  • "defaultEmergencyDestination": "string"
}

Response samples

Content type
application/json
{
  • "traceId": "string",
  • "success": true,
  • "sessionId": "string",
  • "message": "string"
}

/{domain}/sendalarmevent

OPTIONS
path Parameters
domain
required
string

Responses

Response Headers
Access-Control-Allow-Origin
string
Access-Control-Allow-Methods
string
Access-Control-Allow-Headers
string
Response Schema: application/json
object (Empty Schema)

Response samples

Content type
application/json
{ }

Alarmbridge API Callbacks

/alarmQueued

POST

/alarmQueued callback is sent when an alarm event triggered by /sendalarmevent API where the sent event is acting as a group scheme. This will delay the /alarmSent calback until the subunit has been selected. The /alarmQueued callback is sent when the alarm event has been acked by the receiver.

Request Body schema: application/json

Callback sent by Alarmbridge service when a group scheme alarm event sent by calling the /sendalarmevent API have successfully been delivered and acknowledged by receiver and is waiting for a subunit to be selected.

sessionId
string

The sessionId identifies the session

ivrServer
string

The ivrServer is the IP address of the node that sends the command

domain
string

The customer domain handling the alarm event

alarmString
string

String representing the native event sent

dialogId
string

The dialogId for the underying media server session

protocol
string

Protocol used to sent alarm event

callingParty
string

The SIP user/phone number of the device sending the alarm event

serviceProvider
string

The SIP user/phone number of the target destination for the alarm event

Responses

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "127.0.0.1",
  • "domain": "customer.&lt;region&gt;.iotcomms.io",
  • "alarmString": "A123456#",
  • "dialogId": "06ae32d0-4b3a-11ee-8f58-c544331006b3",
  • "protocol": "bs8521",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511"
}

/alarmSendFailure

POST

/alarmSendFailure callback is sent when an alarm event triggered by /sendalarmevent failed.

Request Body schema: application/json

Callback sent by Alarmbridge service in case it fail to deliver an alarm event that was sent by calling the /sendalarmevent

sessionId
string

The sessionId identifies the session

ivrServer
string

The ivrServer is the IP address of the node that sends the command

domain
string

The customer domain handling the alarm event

protocol
string

Protocol used to sent alarm event

warning
string

Type of failure

reason
string

Indicates cause of failure

callingParty
string

The SIP user/phone number of the device sending the alarm event

serviceProvider
string

The SIP user/phone number of the target destination for the alarm event

traceId
string

The traceId is conveyed throughout the service and can be provided in the initial API-call.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "127.0.0.1",
  • "domain": "customer.&lt;region&gt;.iotcomms.io",
  • "protocol": "bs8521",
  • "warning": "Failed to send alarm event",
  • "reason": "noBS8521DataAckReceived",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf"
}

/alarmSent

POST

/alarmSent callback is sent when an alarm event triggered by /sendalarmevent is acknowledged.

Request Body schema: application/json

Callback sent by Alarmbridge service when a alarm event sent by calling the /sendalarmevent API have successfully been delivered and acknowledged by receiver

sessionId
string

The sessionId identifies the session

ivrServer
string

The ivrServer is the IP address of the node that sends the command

domain
string

The customer domain handling the alarm event

alarmString
string

String representing the native event sent

dialogId
string

The dialogId for the underying media server session

protocol
string

Protocol used to sent alarm event

callingParty
string

The SIP user/phone number of the device sending the alarm event

serviceProvider
string

The SIP user/phone number of the target destination for the alarm event

traceId
string

The traceId is conveyed throughout the service and can be provided in the initial API-call.

Responses

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "127.0.0.1",
  • "domain": "customer.&lt;region&gt;.iotcomms.io",
  • "alarmString": "A123456#",
  • "dialogId": "06ae32d0-4b3a-11ee-8f58-c544331006b3",
  • "protocol": "bs8521",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf"
}

/auditRecordingReady

POST

/auditRecordingReady is sent when the Alarmbridge service has finalized and stored the audit recording for an alarm session, and attached a vCon document describing the session (including DTMF/protocol timeline and metadata).

Request Body schema: application/json

Callback sent by Alarmbridge after an alarm session’s audit audio has been written and is available for retrieval. Audit recordings is enabled by setting the auditRecording property to true in the Alarmbridge event receiver.

sessionId
string

Identifier for the session within Alarmbridge

ivrServer
string

The ivrServer is the IP address of the node that sends the callback

domain
string

The customer domain handling the alarm event related to the audit recording

event
string
Value: "auditRecordingReady"

Callback event type

object

vCon document describing the alarm session with Alarmbridge extensions

vcon
string

vCon container version

uuid
string

vCon UUID

subject
string

Short description of the session

Array of objects

Actors in the session; Alarmbridge adds party.type for readability

Array
name
string
uuid
string

Party UUID which maps to Alarmbridge participantId

type
string

Role of the party (extension)

sip
string

SIP URI if applicable

Array of objects

Media/dialog segments; Alarmbridge adds dialog.uuid and dialog.label

Array
type
required
string

Dialog type (e.g., recording)

start
required
string

Start time of this dialog in ISO string format

uuid
required
string

Dialog UUID which maps to Alarmbridge connectionId

parties
required
Array of integers

Indexes into the parties array participating in this dialog

Array of objects

Per-party timeline of events during the dialog (extensions). Currently supports dtmf; may include decoder results etc.

Array
event
string
Value: "dtmf"

Event type

party
integer

Party index the event relates to

direction
string
Enum: "send" "receive"

Whether the tone was sent or received by the party

object

Event-specific data (DTMF extension)

digit
string

DTMF digit

duration
integer

Tone duration in milliseconds

toneType
string
Enum: "inaudio" "2833"

Transport of the tone

time
string <date-time>

Timestamp for the event in ISO string format

originator
integer

Party index of the originator of the dialog

label
string

Human-readable dialog label (extension)

content_hash
string

Integrity hash token of the media object (e.g., sha512-...)

duration
required
number

Duration in seconds

mediatype
string

Media type of the recording

fileName
string

File name of the stored audio object

url
required
string <uri>

URL to fetch the media object

traceId
string

Trace correlation id for the session

httpTransactionId
string

Identifier for the HTTP transaction that delivered the callback

Responses

Request samples

Content type
application/json
{
  • "sessionId": "b3e555d1-8f37-11f0-b8cf-89e1bd2e1911",
  • "ivrServer": "127.0.0.1",
  • "domain": "customer.&lt;region&gt;.iotcomms.io",
  • "event": "auditRecordingReady",
  • "vCon": {
    • "vcon": "0.0.2",
    • "uuid": "b42c70f0-8f37-11f0-b8cf-89e1bd2e1911",
    • "subject": "Inbound scaip voicebridge session",
    • "parties": [
      • {
        • "name": "systemtest",
        • "uuid": "b3e57ce0-8f37-11f0-b8cf-89e1bd2e1911",
        • "type": "alarmdevice",
        • "sip": "sip:systemtest@127.0.0.1"
        }
      ],
    • "dialog": [
      • {
        • "type": "recording",
        • "start": "2025-09-11T17:49:45.727Z",
        • "uuid": "b42c49e0-8f37-11f0-b8cf-89e1bd2e1911",
        • "parties": [
          • 0,
          • 1
          ],
        • "party_history": [
          • {
            • "event": "dtmf",
            • "party": 0,
            • "direction": "send",
            • "data": {
              • "digit": "3",
              • "duration": 80,
              • "toneType": "2833"
              },
            • "time": "2025-09-11T17:49:53.044Z"
            }
          ],
        • "originator": 0,
        • "label": "voicebridge",
        • "content_hash": "sha512-JGZdLAqtT4Da7DM9N8CVbJtVYlDzALHDyInsmcMC_jql39-4U4xfCl1rxDYe3smVaHT0eMclMGE8kPkEfSadjQ",
        • "duration": 13.389,
        • "mediatype": "x-mp3",
        • "fileName": "b3e555d1-...-alarmAudit.mp3",
        • "url": "https://api.dev.iotcomms.io/mediaservice/127.0.0.1/promptfile/...-alarmAudit.mp3"
        }
      ]
    },
  • "traceId": "b3e555d0-8f37-11f0-b8cf-89e1bd2e1911",
  • "httpTransactionId": "bc719920-8f37-11f0-b8cf-89e1bd2e1911"
}

/newAlarmbridgeEvent

POST

/newAlarmbridgeEvent callback is sent when platform receives incoming alarm event.

Request Body schema: application/json

This callback is triggered when an alarm event is received from a remote device to an Alarmbridge service destination. It may either be an IP based protocol such as SCAIP or and analogue protocol such as BS8521.\n\nThe response to the callback request provides instruction to the Alarmbridge service how to further process the alarm session.\n\nThe object passed in the request body below is the default format. It is possible to customize the object properties and values sent per the information in the getting-started guide Alarmbridge custom event mappings.

sessionId
string

The sessionId identifies the session

ivrServer
string

The ivrServer is the IP address of the node that received the alarm event

customerSiteId
string

If the Alarmbridge service destination is provisioned with customerSiteId property the it's value is copied to this property

domain
string

The customer domain handling the alarm event

sourceAlarmProtocol
string
Enum: "scaip" "bs8521" "tt92" "ttnew" "rb2000"

The protocol that the incoming alarm event was decoded with sucessfully

targetAlarmProtocol
string
Enum: "scaip" "bs8521" "tt92" "ttnew" "rb2000"

The protocol that the alarmbridge service destination or device was provisioned to use for decoding of alarm event

sipFrom
string

The user part from the SIP URI of the incoming alarm event, typically the calling party phone number for analogue alarm calls or the device SIP user for SCAIP events.

calledParty
string

The user part from the request URI of the incoming alarm event, typically the called number for analogue alarm calls or the user part of SIP URI for SCAIP events.

object

This property holds the alarm event that was received. It is a a format that is protocol independent and therefore possible to be mapped to the supported protocol specific events.

eventType
string
Value: "common"

Indicates the type of event passed. Currently only the common type is supported, which is automatically mapped to the protocol specific event types.

deviceType
string
Enum: "activityDetector" "automaticPersonDown" "auxInput" "bathSensor" "bedMonitor" "bogusCallerSwitch" "boundaryDetector" "carbonMonoxideDetector" "chairMonitor" "co2gasDetector" "communicationLinkMonitor" "dcPowerSupply" "doorSensor" "dutySwitch" "enuresisDetector" "environmentalMonitor" "epilepsyDetector" "fallDetector" "fireAlarm" "floodDetector" "heartbeat" "heatDetector" "heatingMonitor" "intruderDetector" "lightningCircuitMonitor" "matSensor" "naturalGasDetector" "occupancyDetector" "panicAlarmButton" "personalAttackPendent" "personalTrigger" "pillDispenser" "radioUnit" "smokeDetector" "specialFunction" "systemMonitor"

The type of device raising the alarm.

deviceComponent
string
Enum: "switch1" "switch2" "button1" "button2" "button3" "automatic1" "automatic2" "module1" "module2" "module3" "module4" "module5" "unspecified"

Indicates the trigger type of the alarm for the device

statusCode
string
Enum: "absent" "alarm" "alarmManual" "busy" "communicationLinkIPFailure" "communicationLinkPOTSFailure" "communicationLinkPrimaryFailure" "communicationLinkRedundantFailure" "faultRectified" "highLevel" "inBed" "lowBattery" "normal" "occupied" "offline" "online" "open" "outOfService" "pillNotTaken" "pillReminder" "privacySwitchOperated" "tamper" "temperatureHigh" "temperatureLow" "temperatureRateOfRise"

Indicates the alarm status for the alarm

location
string
Enum: "backDoor" "basement" "bathRoom" "bedRoom" "communalArea" "diningRoom" "door" "fireDoor" "floor" "frontDoor" "garage" "garden" "gardenBack" "gardenFront" "hall" "hallwayDownstairs" "hallwayUpstairs" "handicapWC" "kitchen" "laundry" "livingRoom" "loft" "lounge" "office" "room" "shed" "shower" "stairs" "studyRoom" "summerHouse" "wc" "workshop" "unknown"

Indicates the location of the device raising the alarm

priority
number

Sets the priority for the alarm event, allowed values are the range 0-9 where 0 is lowest priority and 9 is highest

controllerId
string

The id of the controller sending the event. NOTE: Different protocols have limits on the string content. BS8521 support a string of length 12 if no deviceId is passed, or a string of length 8 if deviceId is passed. Only digits 0-9 allowed.

deviceId
string

The id a device attached to the controller sending the event. NOTE: Different protocols have limits on the string content. BS8521 support a string of length 4. Only digits 0-9 allowed.

audio
string
Enum: "none" "duplex"

Indicates if the device that sent the alarm event want to establish an audio session to follow the alarm event.

systemConfig
string
Enum: "localUnitAndController" "groupedSupervisorOffDuty" "groupedSupervisorOnDuty" "groupedSupervisorOnDutyArc"

Indicates the configuration mode of the device that sent the alarm.

sourceAlarmEvent
object

JSON representation of the native event that triggered the event and which is converted into the common format.

replyId
string

The replyId string is used in subsequent API call towards Alarmbridge service to identify the alarm handling session, for example when calling the /hangupalarmcall endpoint.

Responses

Response Schema: application/json
action
string
Enum: "drop" "callEmergencyCenter"

The action property value determines how Alarmbridge will further process the incoming alarm. The following actions are supported:

  • drop - The incoming alarm event is acknowledged.
    • In case of an analogue alarm protocol the remote device is asked to clear the alarm and hang up the call.
    • In case of SCAIP event the response does not request a call to be set up.
  • callEmergencyCenter - The incoming alarm event is acknowledged and the device is connected to the destination configured in the emergencyDestination property in the serviceData.alarmbridge object configured for the device that triggered the alarm. If this is not provisioned it will use the defaultEmergencyDestination property for the Alarmbridge service destination that handled the incoming alarm event.
    • In case of analogue alarm protocol the existing call with the Alarmbridge is transferred to the destination.
    • In case of SCAIP event the SCAIP response will tell the device to place a call to the destination.

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "10.85.0.123",
  • "customerSiteId": "site12",
  • "domain": "customer.&lt;region&gt;.iotcomms.io",
  • "sourceAlarmProtocol": "scaip",
  • "targetAlarmProtocol": "scaip",
  • "sipFrom": "+46890510",
  • "calledParty": "alarm",
  • "alarmEvent": {
    • "eventType": "common",
    • "deviceType": "activityDetector",
    • "deviceComponent": "switch1",
    • "statusCode": "absent",
    • "location": "backDoor",
    • "priority": 0,
    • "controllerId": "string",
    • "deviceId": "string",
    • "audio": "none",
    • "systemConfig": "localUnitAndController"
    },
  • "sourceAlarmEvent": { },
  • "replyId": "string"
}

Response samples

Content type
application/json
{
  • "action": "drop"
}

Alarmbridge API Service Alarms

/<domain_configured>

POST

You have not configured a domain for your service alarm notifications! You can do so here.

The configured domain for your notifications were retrieved from your settings. You can view and modify these settings here.

Request Body schema: application/json

Notifications sent by the Alarmbridge to indicate unexpected events.

type
string
Enum: "alarmbridgeAuthError" "newAlarmbridgeEventError" "alarmbridgeCallFailure"

The type of alarm event. The following types may be sent with the specified error types

  • alarmbridgeAuthError - An unauthorized device is sending alarm events to the service.
domain
string

The domain that triggered the alarm event

sessionId
string

The sessionId of the call that triggered the alarm event

error
string
Enum: "unprovisionedDevice" "unknownProtocol" "noEmergencyDestination" "invalidAction" "callSetupFailure" "unknown"

The type of error that triggered the alarm event

traceId
string

The traceId is conveyed throughout the service and can be provided in the initial API-call.

errorDetails
object

Object with error specific details

Responses

Request samples

Content type
application/json
{
  • "type": "alarmbridgeAuthError",
  • "domain": "customer.prod-eu-north-1.iotcomms.io",
  • "sessionId": "8eaf1600-c20b-11eb-9fdb-f32f171bb218",
  • "error": "unprovisionedDevice",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf",
  • "errorDetails": { }
}