├── .editorconfig
├── .gitignore
├── LICENSE
├── README.md
├── alarm_api_v1.md
├── dashboard_api_v1.md
├── examples
├── alarm-api
│ └── php
│ │ └── alarm-api-example.php
└── dashboard-api
│ ├── javascript
│ └── dashboard-api-example.html
│ └── php
│ ├── dasboard-api-dasboard-example.php
│ └── dasboard-api-login-example.php
├── import_api_v1.md
└── sms_api_v1.md
/.editorconfig:
--------------------------------------------------------------------------------
1 | root = true
2 |
3 | [*.md]
4 | ident_style = space
5 | end_of_line = lf
6 | charset = utf-8
7 | trim_trailing_whitespace = false
8 | insert_final_newline = true
9 |
--------------------------------------------------------------------------------
/.gitignore:
--------------------------------------------------------------------------------
1 | # Created by https://www.gitignore.io/api/intellij+iml,linux
2 |
3 | ### Intellij+iml ###
4 | # Covers JetBrains IDEs: IntelliJ, RubyMine, PhpStorm, AppCode, PyCharm, CLion, Android Studio and Webstorm
5 | # Reference: https://intellij-support.jetbrains.com/hc/en-us/articles/206544839
6 |
7 | # User-specific stuff:
8 | .idea/workspace.xml
9 | .idea/tasks.xml
10 |
11 | # Sensitive or high-churn files:
12 | .idea/dataSources/
13 | .idea/dataSources.ids
14 | .idea/dataSources.xml
15 | .idea/dataSources.local.xml
16 | .idea/sqlDataSources.xml
17 | .idea/dynamic.xml
18 | .idea/uiDesigner.xml
19 |
20 | # Gradle:
21 | .idea/gradle.xml
22 | .idea/libraries
23 |
24 | # Mongo Explorer plugin:
25 | .idea/mongoSettings.xml
26 |
27 | ## File-based project format:
28 | *.iws
29 |
30 | ## Plugin-specific files:
31 |
32 | # IntelliJ
33 | /out/
34 |
35 | # mpeltonen/sbt-idea plugin
36 | .idea_modules/
37 |
38 | # JIRA plugin
39 | atlassian-ide-plugin.xml
40 |
41 | # Crashlytics plugin (for Android Studio and IntelliJ)
42 | com_crashlytics_export_strings.xml
43 | crashlytics.properties
44 | crashlytics-build.properties
45 | fabric.properties
46 |
47 | ### Intellij+iml Patch ###
48 | # Reason: https://github.com/joeblau/gitignore.io/issues/186#issuecomment-249601023
49 |
50 | *.iml
51 | modules.xml
52 | .idea/misc.xml
53 | *.ipr
54 |
55 |
56 | ### Linux ###
57 | *~
58 |
59 | # temporary files which can be created if a process still has a handle open of a deleted file
60 | .fuse_hidden*
61 |
62 | # KDE directory preferences
63 | .directory
64 |
65 | # Linux trash folder which might appear on any partition or disk
66 | .Trash-*
67 |
68 | # .nfs files are created when an open file is removed but is still being accessed
69 | .nfs*
--------------------------------------------------------------------------------
/LICENSE:
--------------------------------------------------------------------------------
1 | MIT License
2 |
3 | Copyright (c) 2016 blaulicht SMS
4 |
5 | Permission is hereby granted, free of charge, to any person obtaining a copy
6 | of this software and associated documentation files (the "Software"), to deal
7 | in the Software without restriction, including without limitation the rights
8 | to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9 | copies of the Software, and to permit persons to whom the Software is
10 | furnished to do so, subject to the following conditions:
11 |
12 | The above copyright notice and this permission notice shall be included in all
13 | copies or substantial portions of the Software.
14 |
15 | THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16 | IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17 | FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18 | AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19 | LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20 | OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21 | SOFTWARE.
22 |
--------------------------------------------------------------------------------
/README.md:
--------------------------------------------------------------------------------
1 | # blaulichtSMS documentation
2 |
3 | ## Alarm API
4 |
5 | > Create and search for alarms using an automated alarm trigger
6 |
7 | * API description: [Alarm API](./alarm_api_v1.md)
8 | * PHP example implementation: [Alarm API PHP example](./examples/alarm-api/php/alarm-api-example.php)
9 |
10 | Please contact us if you would like to use an automatic alarm trigger: [contact](https://blaulichtsms.net/support/#kontaktformular)
11 |
12 |
13 | ## SMS API
14 |
15 | > Create alarms by SMS
16 |
17 | * API description: [SMS API](./sms_api_v1.md)
18 |
19 | Please contact us if you would like to use an SMS alarm trigger: [contact](https://blaulichtsms.net/support/#kontaktformular)
20 |
21 | ## Dashboard API
22 |
23 | > Displays information about the most recent alarm.
24 |
25 | * API description: [Dashboard API](./dashboard_api_v1.md)
26 | * Javascript example implementation: [Dashboard API Javascript Beispiel](./examples/dashboard-api/javascript/)
27 | * PHP example implementation: [Dashboard API PHP Beispiel](./examples/dashboard-api/php/)
28 |
29 | You need the login data of a dashboard to use this API. A dashboard can be created by an admin on the web platform (start.blaulichtsms.net).
30 |
31 | ## Import API
32 |
33 | > Import participants, alarm triggers, and groups via JSON or csv.
34 | >
35 | > CAUTION: This API overwrites all existing data.
36 |
37 | * API description: [Import API](./import_api_v1.md)
38 |
39 | ## Questions in case of problems
40 |
41 | * Do not hesitate to [contact us](https://blaulichtsms.net/support/#kontaktformular)
42 |
43 | ### Trial account
44 |
45 | We provide developers with a free trial account. If you are interested please [contact us](https://blaulichtsms.net/support/#kontaktformular).
46 |
47 | ## Community projects
48 |
49 | * HDMI-CEC control for the dashboard https://github.com/stg93/blaulichtsms_einsatzmonitor_tv_controller
50 | * [Node-RED](https://nodered.org/) Node for incorporating blaulichtSMS alarms https://github.com/riederch/node-red-contrib-blaulicht-sms
51 |
52 |
53 |
54 |
55 |
56 |
--------------------------------------------------------------------------------
/alarm_api_v1.md:
--------------------------------------------------------------------------------
1 | # blaulichtSMS Alarm API
2 |
3 | ## Version
4 | - V1.0: First Version (2016-08-12)
5 | - V1.1: Alarm Query Endpoint
6 | - V1.2: recipientConfirmation parameter added
7 | - V1.3: List Alarm end point added
8 | - V1.4: Change of Alarm Data Element: extension of recipients, deprecation of participants, Geolocation added (2017-01-19)
9 | - V1.5: extended the API by indexNumber
10 |
11 | ## General
12 |
13 | ### Encoding
14 | Encoding shall be UTF-8.
15 |
16 | ### Test Base URL
17 | https://api-staging.blaulichtsms.net/blaulicht
18 |
19 | ### Live Base URL
20 | https://api.blaulichtsms.net/blaulicht
21 |
22 | ## Alarm API
23 |
24 | In order to be able to use this API, an "automatic alarm trigger" with username and password must be configured for the relevant customerId(s).
25 |
26 | ### Trigger Alarm
27 | _**/api/alarm/v1/trigger**_
28 |
29 | To trigger an alarm, send an HTTP POST REQUEST with header `Content-Type: application/json` to the above URL.
30 |
31 | - username: string - mandatory - username
32 | - password: string - mandatory - password
33 | - customerId: string - mandatory - customer ID
34 | - type: alarm | info - mandatory - event type
35 | - hideTriggerDetails: boolean - optional - do not send details of alarm trigger
36 | - alarmText: string - optional - content of alarm
37 | - indexNumber: integer- optional - The index number serves to distinguish different alarms. A second alarm with the same index number will be ignored.
38 | - needsAcknowledgement: boolean - mandatory - reply function
39 | - startDate: string - optional - The date of an alarm in case it is to be triggered in the future. The format shall be UTC e.g. :`"2017-01-27T14:49:52.000Z"`
40 | - duration: integer - conditional - duration for which the reply function is enabled
41 | - recipientConfirmation: boolean - optional - turn on/off confirmation that SMS was received (charges apply)
42 | - recipientConfirmationTarget: string - optional - msisdn of recipient of SMS confirmation
43 | - template: string - optional - Alarm text code e.g. `"A1"`
44 | - groupCodes: list of strings - optional - Alarm group(s) e.g. `["G1"]`
45 | - additionalMsisdns: list of strings - optional - additional msidns to be alerted e.g.: `["+4366412345678", "+4367612345678"]`
46 | - coordinates: object of Type Coordinate - optional - coordinated of location of alarm
47 | - geolocation: object of Type Geolocation - optional - instead of coordinates, a Geolocation object containing an address may also be provided. This address will then be converted to coordinates e.g.: `{"address": "Getreidemartk 11, 1060 Wien"}`
48 |
49 | An example:
50 |
51 | {
52 | "username" : "myUser",
53 | "password" : "mySuperSecretPwd",
54 | "customerId" : "100027",
55 | "hideTriggerDetails" : false,
56 | "alarmText" : "This is a test",
57 | "type" : "alarm",
58 | "needsAcknowledgement" : true,
59 | "duration" : 60,
60 | "recipientConfirmation" : false,
61 | "template" : "A1",
62 | "groupCodes" : ["G1", "G2"],
63 | "additionalMsisdns" : [],
64 | "coordinates" : {
65 | "lat" : 48.205587,
66 | "lon" : 16.342917
67 | }
68 | }
69 |
70 | The following is an exapmple of a successful API call.
71 | A list of all possible values of **result** is provided further down. In case of an error the field **description** contains a description of the error.
72 |
73 | {
74 | "result" : "OK",
75 | "alarmId" : "dakldjsfal-2343232-afsdaddfa-234",
76 | "customerId" : 100027,
77 | "description" : null
78 | "alarmData" : { see description AlarmData Object }
79 | }
80 |
81 |
82 | ### QUERY ALARM
83 | _**/api/alarm/v1/query**_
84 |
85 | To search for an alarm, send an HTTP POST Request with header `Content-Type: application/json` to the URL mentioned above.
86 |
87 | - username: string - mandatory - username
88 | - password: string - mandatory - password
89 | - customerId: string - mandatory - customer ID
90 | - alarmid: string - mandatory - AlarmId (is returned upon triggering an alarm)
91 |
92 | An example:
93 |
94 | {
95 | "username" : "myUser",
96 | "password" : "mySuperSecretPwd",
97 | "customerId" : "100027",
98 | "alarmId" : "dakldjsfal-2343232-afsdaddfa-234"
99 | }
100 |
101 | The following is an exapmple of a successful API call.
102 | A list of all possible values of **result** is provided further down. In case of an error the field **description** contains a description of the error.
103 |
104 | {
105 | "result" : "OK",
106 | "alarmId" : "dakldjsfal-2343232-afsdaddfa-234",
107 | "customerId" : 100027,
108 | "description" : "ok",
109 | "alarmData" : { see description AlarmData object }
110 | }
111 |
112 |
113 | ### LIST ALARM
114 | _**/api/alarm/v1/list**_
115 |
116 | To get a list of alarms, send an HTTP POST Request with header `Content-Type: application/json` to the URL mentioned above. You will receive a list of AlarmData objects. Only 100 alarms will be returned, sorted by the end date of the alarm.
117 |
118 | - username: string - mandatory - username
119 | - password: string - mandatory - password
120 | - customerIds: list of string - mandatory - list of customer IDs
121 | - startDate: date in iso format - optional - start date for search (all alarms with later end date will be returned)
122 | - endDate: date in iso format - optional - end date for search (all alarms with prior start date will be returned)
123 |
124 | Ein Beispiel:
125 |
126 | {
127 | "username" : "myUser",
128 | "password" : "mySuperSecretPwd",
129 | "customerIds" : ["100027", "900027"],
130 | "startDate" : "2016-01-01T17:00:00.000Z",
131 | "endDate" : "2016-01-01T17:30:00.000Z"
132 | }
133 |
134 | The following is an exapmple of a successful API call.
135 | A list of all possible values of **result** is provided further down. In case of an error the field **description** contains a description of the error.
136 |
137 | {
138 | "result" : "OK",
139 | "description" : "ok",
140 | "alarms" : [{ see description AlarmData object }]
141 | }
142 |
143 | #### AlarmData
144 | - customerId: Customer ID belonging to this alarm
145 | - alarmId: unique identifier of the alarm
146 | - alarmGroups: list of alarm group elements (see AlarmGroup object)
147 | - alarmDate : time of alert
148 | - endDate: end of reply function window (if activated)
149 | - authorName: name of the alarm trigger that has triggered the alarm
150 | - alarmText: the alarm text
151 | - needsAcknowledgement: reply function active/inactive
152 | - usersAlertedCount: nubmer of participants alerted
153 | - geolocation: see GeoLocation object
154 | - recipients: list of participants - see AlarmRecipient object
155 | - audioUrl: Url of audio alarm, if applicable
156 | - indexNumber: index number of the alarm
157 |
158 |
159 | An example:
160 |
161 | {
162 | "customerId" : "100027",
163 | "alarmId" : "32849abcdef23343",
164 | "alarmGroups" : [ ], // list of AlarmGroup elements
165 | "alarmDate" : "2016-01-01T17:30:21.345Z", // UTC date
166 | "endDate" : "2016-01-01T17:30:21.345Z", // UTC date
167 | "authorName" : "John Doe",
168 | "alarmText" : "This is a test",
169 | "needsAcknowledgement" : true,
170 | "usersAlertedCount" : 10,
171 | "geolocation" : { }, // see GeoLocation object
172 | "recipients" : [ ], // list of AlarmRecipient elements
173 | "audioUrl" : null,
174 | "indexNumber": null
175 | }
176 |
177 | #### AlarmGroup
178 |
179 | {
180 | "groupId" : "G1",
181 | "groupName" : "whole team"
182 | }
183 |
184 | #### AlarmRecipient
185 |
186 | {
187 | "id" : "2342343242342abcde32423423",
188 | "name" : "Jeanny Doe",
189 | "msisdn" : "+4366412345678",
190 | "comment" : "Fire Brigade ABC" // optional
191 | "participation" : "yes", // yes | no | uknown | pending
192 | "participationMessage" : "Coming in 5 minutes",
193 | "functions": [ ], // list of AlarmFunction Elementen (functions / qualifications)
194 | }
195 |
196 | #### AlarmFunction
197 |
198 | {
199 | "functionId": "123123789"
200 | "name": "respiratory equipment carriers"
201 | "order": 2
202 | "shortForm": "REC"
203 | "backgroundHexColorCode": "#3164c2"
204 | "foregroundHexColorCode" "#ffffff"
205 | }
206 |
207 | #### GeoLocation
208 |
209 | {
210 | "coordinates" : {
211 | "lat" : 17.34334,
212 | "lon" : 23.32343
213 | },
214 | "positionSetByAuthor" : true, // if coordinates set by author
215 | "radius" : 10, // radius in m (may be null)
216 | "distance" : 10, // distance in m (may be null)
217 | "address" : "High Street 1, 1234 Metropolis" // textual address (may be null)
218 | }
219 |
220 | #### Return Codes
221 | - OK
222 | - MISSING_INPUT_DATA
223 | - MISSING_CUSTOMER_ID
224 | - MISSING_USERNAME
225 | - INVALID_CUSTOMER_ID
226 | - NOT_CONFIGURED_FOR_CUSTOMER
227 | - UNKNOWN_USER
228 | - NOT_AUTHORIZED
229 | - UNAUTHORIZED_SENDER_ID
230 | - DEACTIVATED
231 | - INVALID_GROUP
232 | - INVALID_TEMPLATE
233 | - NOT FOUND
234 | - UNKNOWN_ERROR
235 |
--------------------------------------------------------------------------------
/dashboard_api_v1.md:
--------------------------------------------------------------------------------
1 | # blaulichtSMS Dashboard API
2 |
3 | ## Version
4 | - V1.0: First version (2016-08-12)
5 | - V1.1: added integrations, adapted AlarmData element (2017-01-19)
6 |
7 | ## General
8 |
9 | ### Encoding
10 | Encoding shall be UTF-8.
11 |
12 | ### Base URL
13 | https://api.blaulichtsms.net/blaulicht
14 |
15 | ## Dashboard API
16 |
17 | The dashboard needed to use this API can be created on the web platform (start.blaulichtsms.net) under "Dashboard".
18 |
19 | ### Login
20 | _**/api/alarm/v1/dashboard/login**_
21 |
22 | To log in you need to send an HTTP POST request with header `Content-Type: application/json` to the above URL.
23 | The login data is the same as for [https://dashboard.blaulichtsms.net](https://dashboard.blaulichtsms.net/#/).
24 |
25 | {
26 | "username" : "myUser",
27 | "password" : "mySuperSecretPwd",
28 | "customerId" : "123456"
29 | }
30 |
31 | After a successful login you receive a session ID:
32 |
33 | {
34 | "success" : true,
35 | "sessionId" : "lafjdfajdslfja89324u983u2894u89jlassdfj",
36 | "error" : null
37 | }
38 |
39 | This session ID must be saved in a cookie / LocalStorage / SessionStorage gespeichert and will be used for all further requests.
40 |
41 | In case of an error you receive the following reply
42 |
43 | {
44 | "success" : false,
45 | "sessionId" : null,
46 | "error" : "MISSING_INPUT_DATA" // error codes see below
47 | }
48 |
49 | #### Error codes
50 | - MISSING_INPUT_DATA
51 | - MISSING_PASSWORD
52 | - MISSING_CUSTOMERID
53 | - MISSING_USERNAME
54 | - INVALID_CREDENTIALS
55 |
56 | Only one session at a time is possible.
57 |
58 | ### Dasboard information
59 | _**/api/alarm/v1/dashboard/{{sessionId}}**_
60 |
61 | In order to receive information from a dashboard you must send an HTTP GET request to the above URL.
62 |
63 | If the session has expired, you will receive the reply **HTTP 401 Unauthorized**.
64 |
65 | A valid session leads to the reply **HTTP 200 OK** as a **json** object with the following contents :
66 |
67 | {
68 | "customerId" : "123456",
69 | "customerName" : "FF Test",
70 | "username" : "dashboard",
71 | "integrations" : [ ], // list of integrations
72 | "alarms" : [ ], // list of AlarmData elements
73 | "infos" : [ ] // list of AlarmData elements
74 | }
75 |
76 | All active alarms within the last 24 hours will be returned, as well as the last one, regardless of its age.
77 |
78 | #### AlarmData
79 | - alarmId: the unique identifier of the alarm
80 | - alarmGroups: list of AlarmGroup elements (see AlarmGroup object)
81 | - alarmDate : time of alert
82 | - endDate: end of reply function time window (if activated)
83 | - authorName: name of the trigger
84 | - alarmText: the alarm text
85 | - needsAcknowledgement: true = the reply function is active
86 | - usersAlertedCount: number of alerted recipients
87 | - geolocation: see GeoLocation object
88 | - recipients: list of recipients - see AlarmRecipient object
89 | - audioUrl: Url of audio alarm, if used
90 |
91 |
92 | An example:
93 |
94 | {
95 | "alarmId" : "32849abcdef23343",
96 | "alarmGroups" : [ ], // list of AlarmGroup elements
97 | "alarmDate" : "2016-01-01T17:30:21.345Z", // UTC date
98 | "endDate" : "2016-01-01T17:30:21.345Z", // UTC date
99 | "authorName" : "John Doe",
100 | "alarmText" : "This is a test",
101 | "needsAcknowledgement" : true,
102 | "usersAlertedCount" : 10,
103 | "geolocation" : { }, // GeoLocation element
104 | "recipients" : [ ], // list of AlarmRecipient elementes
105 | "audioUrl" : null
106 | }
107 |
108 | #### AlarmGroup
109 |
110 | {
111 | "groupId" : "G1",
112 | "groupName" : "whole fire department"
113 | }
114 |
115 | #### AlarmRecipient
116 |
117 | {
118 | "id" : "2342343242342abcde32423423",
119 | "name" : "Jenny Jobber",
120 | "msisdn" : "+4366412345678"
121 | "participation" : "yes", // yes | no | uknown | pending
122 | "participationMessage" : "arriving in 5 minutes",
123 | "functions": [ ], // list of AlarmFunction elements (functions / qualifications)
124 | }
125 |
126 | #### AlarmFunction
127 |
128 | {
129 | "functionId": "123123789"
130 | "name": "Atemschutzgeräteträger"
131 | "order": 2
132 | "shortForm": "AGT"
133 | "backgroundHexColorCode": "#3164c2"
134 | "foregroundHexColorCode" "#ffffff"
135 | }
136 |
137 | #### GeoLocation
138 |
139 | {
140 | "coordinates" : {
141 | "lat" : 17.34334,
142 | "lon" : 23.32343
143 | },
144 | "positionSetByAuthor" : true, // true if set by trigger
145 | "radius" : 10, // radius in m (may be null)
146 | "distance" : 10, // distance in m (may be null)
147 | "address" : "High Street 99, 1234 Back-of-beyond" // address as test (may be null)
148 | }
149 |
150 |
151 | #### AlarmIntegration
152 |
153 | {
154 | "type" : "wasserkarte.info",
155 | "fields" : { // JSON Object with the following information
156 | "apiKey" : "23423ldjsakfjdsflj34343"
157 | }
158 | }
159 |
160 | # Dashboard automatic login
161 |
162 | The `sessionId` may also be used to create an automatic login to the dashboard. Therefore, the dashboard must be accessed using the following URL:
163 |
164 | _**https://dashboard.blaulichtsms.net/#/login?token={{sessionId}}**_
165 |
166 |
167 |
168 |
--------------------------------------------------------------------------------
/examples/alarm-api/php/alarm-api-example.php:
--------------------------------------------------------------------------------
1 | USERNAME,
15 | 'password' => PASSWORD,
16 | 'hideTriggerDetails' => false,
17 | 'customerId' => CUSTOMER_ID,
18 | 'alarmText' => TEXT,
19 | 'type' => 'alarm',
20 | 'needsAcknowledgement' => true,
21 | 'duration' => 60,
22 | 'template' => '',
23 | 'groupCodes' => GROUPS,
24 | 'additionalMsisdns' => ADDITIONAL_MSISDNS
25 | ];
26 |
27 | $ch = curl_init();
28 |
29 | curl_setopt($ch, CURLOPT_URL, TRIGGER_URL);
30 | curl_setopt($ch, CURLOPT_POST, 1);
31 | curl_setopt($ch, CURLOPT_RETURNTRANSFER, 1);
32 | curl_setopt($ch, CURLOPT_HTTPHEADER, [
33 | "Content-Type: application/json"
34 | ]);
35 |
36 | curl_setopt($ch, CURLOPT_POSTFIELDS, json_encode($request_body));
37 | $curlResponse = curl_exec($ch);
38 |
39 | curl_close($ch);
40 |
41 | print_r($curlResponse);
42 |
--------------------------------------------------------------------------------
/examples/dashboard-api/javascript/dashboard-api-example.html:
--------------------------------------------------------------------------------
1 |
--------------------------------------------------------------------------------
/examples/dashboard-api/php/dasboard-api-dasboard-example.php:
--------------------------------------------------------------------------------
1 | alarms as $alarm) {
22 | echo(" Alarm: $alarm->alarmText
");
23 |
24 | foreach ($alarm->recipients as $recipient) {
25 | echo("Name: $recipient->name
Status: $recipient->participation
Antwortnachricht: $recipient->participationMessage
");
26 | }
27 | echo("