API docs by Redocly

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}/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

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 samples

Content type
application/json
{ }

/{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" "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

Request samples

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

Response samples

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

/{domain}/devicecommand

OPTIONS
path Parameters
domain
required
string

Responses

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 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

Request samples

Content type
application/json
{
  • "traceId": "string",
  • "sipFrom": "string",
  • "toneHandler": "transparent",
  • "toneSettings": {
    },
  • "protocolParameters": {
    },
  • "alarmEvent": {
    },
  • "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 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.<region>.iotcomms.io",
  • "alarmString": "A123456#",
  • "dialogId": "06ae32d0-4b3a-11ee-8f58-c544331006b3",
  • "protocol": "bs8521",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511"
}

/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.<region>.iotcomms.io",
  • "alarmString": "A123456#",
  • "dialogId": "06ae32d0-4b3a-11ee-8f58-c544331006b3",
  • "protocol": "bs8521",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf"
}

/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.<region>.iotcomms.io",
  • "protocol": "bs8521",
  • "warning": "Failed to send alarm event",
  • "reason": "noBS8521DataAckReceived",
  • "callingParty": "+46890510",
  • "serviceProvider": "+46890511",
  • "traceId": "9851cf70-1cc8-11ef-b3dd-9b598c1e38cf"
}

/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" "diningRoom" "frontDoor" "garage" "garden" "gardenBack" "gardenFront" "hallwayDownstairs" "hallwayUpstairs" "handicapWC" "kitchen" "laundry" "livingRoom" "loft" "office" "shed" "stairs" "studyRoom" "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

Request samples

Content type
application/json
{
  • "sessionId": "9bb07660-c747-11ea-afa0-bd07728b88b7",
  • "ivrServer": "10.85.0.123",
  • "customerSiteId": "site12",
  • "domain": "customer.<region>.iotcomms.io",
  • "sourceAlarmProtocol": "scaip",
  • "targetAlarmProtocol": "scaip",
  • "sipFrom": "+46890510",
  • "calledParty": "alarm",
  • "alarmEvent": {
    },
  • "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": { }
}