Messaging API specification (3.1.1)

Download OpenAPI specification:Download

The messaging service implements all functions for message-management in GroupAlarm

Authentication

API_Token

To use this API, you need an API-Token from the RBAC settings of your GroupAlarm organization. Place the token inside the HTTP-Header API-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security Scheme Type API Key
Header parameter name: API-TOKEN

Personal-Access-Token

To use this API, you need a Personal Access Token from your profile settings. Place the token inside the HTTP-Header Personal-Access-Token for every request, otherwise the API will return an "401 Unauthorized" error for your request.

Security Scheme Type API Key
Header parameter name: Personal-Access-Token

user

SetUserEscalation

Creates or updates an existing escalation configuration for the passed user

Request Body schema: application/json

new escalation configuration

escalations
required
Array of objects (Escalation)

configured escalations

organizationID
integer <int64>

organization id for editing escalation as an organization administrator

userID
integer <int64>

assigned user for this escalation configuration for organization administrator editing

Responses

200

user was successfully removed from organization

400

parameters missing or in the wrong format

403

the last organization admin can not leave the organization

500

unexpected error

post /escalation
https://app.groupalarm.com/api/v1/escalation

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "escalations":
    [
    ],
  • "organizationID": 0,
  • "userID": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "message": "escalation saved"
}

GetUserEscalation

Returns the escalation configuration for the passed user

path Parameters
userID
required
int64

user id for the requested escalation

query Parameters
organization_id
int64

has to be set if you want to edit a user as admin of an organization

Responses

200

requested escalation configuration for the passed userID

400

userID missing or in the wrong format

500

unexpected error

get /escalation/{userID}
https://app.groupalarm.com/api/v1/escalation/{userID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "escalations":
    [
    ],
  • "organizationID": 0,
  • "userID": 0
}

escalation

SetOrganizationEscalation

Sets the escalation configuration for the given organization

Request Body schema: application/json

new escalation configuration

escalations
required
Array of objects (Escalation)

configured escalations

organizationID
integer <int64>

organization id for editing escalation as an organization administrator

userID
integer <int64>

assigned user for this escalation configuration for organization administrator editing

Responses

200

successfully saved escalation configuration

400

missing or invalid organizationID

500

unexpected error

post /escalation-organization
https://app.groupalarm.com/api/v1/escalation-organization

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "escalations":
    [
    ],
  • "organizationID": 0,
  • "userID": 0
}

GetOrganizationEscalation

Returns the escalation configuration for the given organization

path Parameters
organizationID
required
int64

organizationID for the requested escalation

Responses

200

requested escalation configuration

400

missing or invalid organizationID

404

no escalation configuration found

500

unexpected error

get /escalation-organization/{organizationID}
https://app.groupalarm.com/api/v1/escalation-organization/{organizationID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "escalations":
    [
    ],
  • "organizationID": 0,
  • "userID": 0
}

RemoveOrganizationEscalation

Removes the escalation configuration for the given organization

path Parameters
organizationID
required
int64

organizationID for the requested escalation

Responses

200

successfully deleted escalation configuration

400

missing or invalid organizationID

500

unexpected error

delete /escalation-organization/{organizationID}
https://app.groupalarm.com/api/v1/escalation-organization/{organizationID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "escalations":
    [
    ],
  • "organizationID": 0,
  • "userID": 0
}

alarm

GetAlarmMessageStatus

Returns the current alarm message status for the user in the given alarm

path Parameters
alarm_id
required
int64

alarmID this request is about

query Parameters
organization_id
required
int64

associated organization requesting the information (used for rbac-check)

user_id
required
int64

requested user status

Responses

200

requested alarm message status for the user in the given alarm

400

alarmID / userID / unitID / labelID missing or in wrong format

500

unexpected error

get /messagestatus/{alarm_id}
https://app.groupalarm.com/api/v1/messagestatus/{alarm_id}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "devices":
    [
    ],
  • "messageId": "string"
}

feedback

Sets the user feedback for a specific alarm or organization using the api.

You can use a JWT Token or Personal Access Token to update a specific user's feedback in an alarm or organization. You can also use an organization api token to update any user's feedback in an alarm or your organization.

Request Body schema: application/json

the users feedback

alarmID
integer <int64>

AlarmID associated to the feedback

organizationID
integer <int64>

OrganizationID associated to the feedback

response
required
boolean

Response should be true if the user gave positive feedback and false if not

userID
required
integer <int64>

UserID of the user that is sending this feedback

Responses

200

feedback was successfully set

400

organizationID nor alarmID set

403

userID not matching requesting user when using jwt token or personal access token

500

unexpected error

post /messaging/feedback
https://app.groupalarm.com/api/v1/messaging/feedback

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "alarmID": 0,
  • "organizationID": 0,
  • "response": true,
  • "userID": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "success": true
}

organization

GetTimeout

Returns the timeout of an message in the organization

path Parameters
organizationID
required
int64

organization id for the requested timeout

Responses

200

requested timeout configured for the passed organizationID

400

organizationID missing or in the wrong format

500

unexpected error

get /messaging/timeout/{organizationID}
https://app.groupalarm.com/api/v1/messaging/timeout/{organizationID}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timeout": 0
}

SetTimeout

Sets the timeout of an message in the organization

path Parameters
organizationID
required
int64

organization id for the requested timeout

Request Body schema: application/json

organization timeout configuration

timeout
required
integer <int64>

Timeout of any message for the given organization

Responses

200

requested timeout configured for the passed organizationID

400

organizationID missing or in the wrong format

500

unexpected error

post /messaging/timeout/{organizationID}
https://app.groupalarm.com/api/v1/messaging/timeout/{organizationID}

Request samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timeout": 0
}

Response samples

Content type
application/json
Copy
Expand all Collapse all
{
  • "timeout": 0
}