> ## Documentation Index
> Fetch the complete documentation index at: https://api-docs.bienport.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Mobile App → Alarm Panel Commands

> This section describes how mobile applications can send commands to alarm panels over MQTT, and how responses are delivered back through subscribed topics.

<Note>
  This is a public API!
</Note>

<Danger>
  All command messages must be published to the queue `resource/commands` with a valid JWT token.<br />
  Responses are delivered on `secom/mobileapp/<app-unique-id>`. Use a unique `correlationId` to pair requests and responses.
</Danger>

<Info>
  **Transport:** MQTT (pub/sub). The alarm panel publishes commands to broker queues.
</Info>

## Message Envelope (Common Schema)

### Command Request (Envelope)

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "your-app-id",
  "brand": "EBS",
  "jwtToken": "jwt-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "<command-name>",
  "correlationId": "<unique-id>",
  "parameters": { /* command-specific */ }
}
```

* **Publish to:** `resource/commands`
* **Security:** `jwtToken` must be valid; sensitive fields (e.g., `pinCode`) must be **AES‑256 encrypted** inside `parameters`.

### Command Response (Envelope)

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "<same-as-request>",
  "result": "<success|failed|not send|send_no_ack|unauthorized>",
  "reason": "<human-readable reason - optional>",
  "data": {
    /* command-specific payload */ 
   }
}
```

* **Result codes**
  * `success` – command accepted and processed; see `data`.
  * `failed` – command delivered but panel or backend reported failure.
  * `not send` – validation/authz failed; command not sent to panel.
  * `send_no_ack` – published but no ACK from panel within timeout.
  * `unauthorized` – JWT invalid/expired or user lacks access.

### Error Response Templates (Examples)

**Missing User / Access Check Skipped**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "<id>",
  "result": "not send",
  "reason": "UserId is missing, could not check access authorization to resourceId!",
  "data": { 
    "command": "<command>", 
    "resourceId": 34 
  }
}
```

**Unauthorized**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "<id>",
  "result": "unauthorized",
  "reason": "User not authorized to access alarm panel!",
  "data": { 
    "command": "<command>", 
    "resourceId": 34 
  }
}
```

**Panel Disabled**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "not send",
  "reason": "Panel is disabled!",
  "data": {
    "command": "arm",
    "resourceId": 35,
    "userId": 20199
  }
}
```

**Panel Not Found**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "not send",
  "reason": "Panel not found!",
  "data": {
    "command": "arm",
    "resourceId": 35,
    "userId": 20199
  }
}
```

**Command Failed**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "failed",
  "reason": "Command not allowed",
  "data": {
    "command": "arm",
    "partition": 1,
    "resourceId": 34,
    "brand": "EBS",
    "model": "CPX-230NWB",
    "networkId": "654527"
  }
}

```

**Command Not Permitted**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "unauthorized",
  "reason": "Command not permitted",
  "data": {
    "command": "arm",
    "partition": 1,
    "resourceId": 34,
    "brand": "EBS",
    "model": "CPX-230NWB",
    "networkId": "654527"
  }
}

```

**Generic Error**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "unknown",
  "reason": "Exception-message-here",
  "data": {
    "command": "arm",
    "resourceId": 35,
    "userId": 20199
  }
}

```

**Command Not Found**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "3",
  "result": "failed",
  "reason": "Command not found!",
  "parameters": {
    "command": "panel-arm"
  }
}

```

**Transmission Failed**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "send_no_ack",
  "reason": "Command transmission failed, try again after a while"
}


```

**Partition Not Found**

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "partitionNotFound",
  "reason": "The partition you want to change its status is not available",
  "data": {
    "command": "arm",
    "partition": 5,
    "resourceId": 486,
    "brand": "EBS",
    "model": "CPX-230NWB",
    "networkId": "702716"
  }
}

```

**User Not Allowed**

```json theme={null}

{
    "messageType": "commandResponse",
    "correlationId": "1",
    "result": "notAuthorizedForPartition",
    "reason": "You do not have permission to perform operations in this partition.",
    "data": {
        "command": "arm",
        "partition": 1,
        "resourceId": 486,
        "brand": "EBS",
        "model": "CPX-230NWB",
        "networkId": "702716"
    }
}
```

***

# Command - Response Pairs

Below are **command-specific requests** and their **successful** responses. For failures, refer to the **Error Response Templates** above.

***

## 1. Arm

> Arms the alarm panel for a given partition.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "arm",
  "correlationId": "1",
  "parameters": {
    "resourceId": 34,
    "partition": 1,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "arm",
    "partition": 1,
    "resourceId": 34,
    "brand": "EBS",
    "model": "CPX-230NWB",
    "networkId": "654527"
  }
}
```

***

## 2. Stay Arm

> Arms the alarm panel in **Stay/Indoor** mode.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "armStay",
  "correlationId": "2",
  "parameters": {
    "resourceId": 35,
    "partition": 1,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "3",
  "result": "success",
  "data": {
    "command": "armStay",
    "partition": 1,
    "resourceId": 35,
    "brand": "EBS",
    "model": "CPX-300W",
    "networkId": "1065885"
  }
}
```

***

## 3. Sleep Arm

> Arms the alarm panel in **Sleep/Night** mode.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "armSleep",
  "correlationId": "1",
  "parameters": {
    "resourceId": 35,
    "partition": 1,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "success",
  "data": {
    "command": "armSleep",
    "partition": 1,
    "resourceId": 35,
    "brand": "EBS",
    "model": "CPX-300W",
    "networkId": "1065885"
  }
}
```

***

## 4. Disarm

> Disarms the alarm panel for a given partition.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "disarm",
  "correlationId": "1",
  "parameters": {
    "resourceId": 34,
    "partition": 1,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "disarm",
    "partition": 1,
    "resourceId": 34,
    "brand": "EBS",
    "model": "CPX-230NWB",
    "networkId": "654527"
  }
}
```

***

## 5. Arm Zone

> Arms a specific zone.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "organizationId": "123456",
  "command": "armZone",
  "correlationId": "5",
  "parameters": {
    "resourceId": 34,
    "partition": 1,
    "zone": 12,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "armZone",
    "zone": 12,
    "resourceId": 50,
    "brand": "EBS",
    "model": "CPX-300W",
    "networkId": "1065885"
  }
}
```

### Spesific Error Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "5",
  "result": "not send",
  "reason": "No sensors assigned to alarm panel",
  "data": {
    "resourceId": 34,
    "partition": 1,
    "zone": 12
  }
}
```

***

## 6. Disarm Zone

> Disarms a specific zone.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "EBS",
  "jwtToken": "replace-with-your-token",
  "userId": 20199,
  "command": "disarmZone",
  "organizationId": "123456",
  "correlationId": "2",
  "parameters": {
    "resourceId": 34,
    "partition": 1,
    "zone": 12,
    "pinCode": "AES-256 encrypted pin code"
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "3",
  "result": "success",
  "data": {
    "command": "disarmZone",
    "partition": 1,
    "resourceId": 50,
    "brand": "EBS",
    "model": "CPX-300W",
    "networkId": "1065885"
  }
}
```

### Spesific Error Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "2",
  "result": "not send",
  "reason": "No sensors assigned to alarm panel",
  "data": {
    "resourceId": 34,
    "partition": 1,
    "zone": 12
  }
}
```

***

## 7. Zone Bypass

> Bypasses (ignores) a zone.

### Request

```json theme={null}
{
     "messageType": "commandMessage",
     "appId": "replace-with-your-app’s-unique-id",
     "brand": "EBS",
     "jwtToken": "replace-with-your-token",
     "userId": 146011,
     "organizationId": "123456",
     "command": "zonesBypass",
     "correlationId": "1",
     "parameters": {
         "resourceId": 178,
         "zones": [10,11,12],
         "pinCode": "AES-256 encrypted pin code"
     }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "zonesBypass",
    "resourceId": 178,
    "zones": [10,11,12],
    "brand": "EBS",
    "model": "CPX230",
    "networkId": "1065885"
  }
}
```

***

## 8. Zone Unbypass

> Removes bypass state from a zone.

### Request

```json theme={null}
{
     "messageType": "commandMessage",
     "appId": "replace-with-your-app’s-unique-id",
     "brand": "EBS",
     "jwtToken": "replace-with-your-token",
     "userId": 146011,
     "organizationId": "123456",
     "command": "zonesUnbypass",
     "correlationId": "1",
     "parameters": {
         "resourceId": 178,
         "zones": [10,11,12],
         "pinCode": "AES-256 encrypted pin code"
     }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "zonesUnbypass",
    "zones": [10,11,12],
"resourceId": 178,
    "brand": "EBS",
    "model": "CPX230",
    "networkId": "1065885"
  }
}
```

***

## 9. Set Output

> Controls panel outputs (e.g., relays, DOs).

### Request

```json theme={null}
{
     "messageType": "commandMessage",
     "appId": "replace-with-your-app’s-unique-id",
     "brand": "EBS",
     "jwtToken": "replace-with-your-token",
     "userId": 146011,
     "organizationId": "123456",
     "command": "setOutput",
     "correlationId": "1",
     "parameters": {
         "resourceId": 178,
         "output": 1,
         "status": 1,
         "duration": 5,
         "pinCode": "AES-256 encrypted pin code"
     }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "setOutput",
    "resourceId": 178,
    "brand": "EBS",
    "model": "CPX230",
    "networkId": "1065885"
  }
}
```

***

## 10. Get Status

> Retrieves the status of the alarm panel.

### Request

```json theme={null}
{
    "messageType": "commandMessage",
    "appId": "replace-with-your-app’s-unique-id",
    "brand": "EBS",
    "jwtToken": "replace-with-your-token",
    "userId": 146011,
    "organizationId": "123456",
    "command": "getStatus",
    "correlationId": "1",
    "parameters": {
        "resourceId": 178,
        "pinCode": "AES-256 encrypted pin code"
    }
}
```

### Success Response 1

All properties don’t have any true value

```json theme={null}
{
    "messageType": "commandResponse",
    "correlationId": "1",
    "result": "success",
    "data": {
      "command": "getStatus",
      "isReadyForArm": false,
      "currentPartitionAlarms": [],
      "zoneAlarmHistory": [],
      "remoteControllerAlarm": false,
      "tamperKeypad": [],
      "zoneTampers": [],
      "keypadTampers": [],
      "alarmingZones": [],
      "lockedZones": [],
      "armedPartitions": [],
      "alarmingOutputs": [],
      "batteryVoltage": 10.657,
      "powerSupplyVoltage": 17.028,
      "silentAlarmHistory": [],
      "zonesComFailures": [],
      "zonesPowerFailures": [],
      "partitionsStayAway": [],
      "partitionsNight": [],
      "resourceId": 178,
      "brand": "EBS",
      "model": "CPX230",
      "networkId": "1065885"
   }
}
```

### Success Response 2

All properties have at least one true value

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "data": {
    "command": "getStatus",
    "isReadyForArm": true,
    "currentPartitionAlarms": [
      {
        "partition": 2,
        "value": true
      }
    ],
    "zoneAlarmHistory": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "remoteControllerAlarm": false,
    "tamperKeypad": [
      {
        "keypad": 1,
        "value": true
      }
    ],
    "zoneTampers": [
      {
        "zoneTamper": 1,
        "value": true
      }
    ],
    "keypadTampers": [
      {
        "keypadTamper": 1,
        "value": true
      }
    ],
    "alarmingZones": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "lockedZones": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "armedPartitions": [
      {
        "partition": 2,
        "value": true
      }
    ],
    "alarmingOutputs": [
      {
        "output": 1,
        "value": true
      }
    ],
    "batteryVoltage": 13.889,
    "powerSupplyVoltage": 20.747,
    "silentAlarmHistory": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "zonesComFailures": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "zonesPowerFailures": [
      {
        "zone": 1,
        "value": true
      }
    ],
    "partitionsStayAway": [
      {
        "partition": 2,
        "value": true
      }
    ],
    "partitionsNight": [
      {
        "partition": 2,
        "value": true
      }
    ],
    "resourceId": 178,
    "brand": "EBS",
    "model": "CPX230",
    "networkId": "1065885"
  }
}
```

***

## 11. Get Failures

> Retrieves active failures reported by the panel.

### Request

```json theme={null}
{
    "messageType": "commandMessage",
    "appId": "replace-with-your-app’s-unique-id",
    "brand": "EBS",
    "jwtToken": "replace-with-your-token",
    "userId": 146011,
    "organizationId": "123456",
    "command": "getFailures",
    "correlationId": "1",
    "parameters": {
        "resourceId": 178,
        "pinCode": "AES-256 encrypted pin code"
    }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "reason": "send",
  "data": {
    "command": "getFailures",
    "outFailures": [
      {
        "outNumber": 2,
        "value": true
      }
    ],
    "powerOutFailures": [
      {
        "powerOut": 1,
        "outName": "KPOUT",
        "value": true
      },
      {
        "powerOut": 2,
        "outName": "AUX1",
        "value": true
      },
      {
        "powerOut": 3,
        "outName": "AUX2",
        "value": true
      }
    ],
    "powerInFailures": [
      {
        "powerIn": 1,
        "inName": "MAINS",
        "value": true
      },
      {
        "powerIn": 2,
        "inName": "BATTERY",
        "value": true
      }
    ],
    "keypadCommFailures": [
      {
        "keypadNo": 1,
        "value": true
      },
      {
        "keypadNo": 2,
        "value": true
      }
    ],
    "keypadPowerFailures": [
      {
        "keypadNo": 1,
        "value": true
      },
      {
        "keypadNo": 2,
        "value": true
      }
    ],
    "otherFailures": [
      {
        "type": 1,
        "name": "CLOCK_NOT_SYNC",
        "value": true
      },
      {
        "type": 2,
        "name": "CONF_MEM_FAIL",
        "value": true
      }
    ],
    "resourceId": 638,
    "brand": "EBS",
    "model": "CPX-300W",
    "networkId": "1065885"
  }
}
```

***

## 12. Initiate Connection

> Instructs the panel to initiate a fresh connection.

### Request

```json theme={null}
{
     "messageType": "commandMessage",
     "appId": "replace-with-your-app’s-unique-id",
     "brand": "DSC",
     "jwtToken": "replace-with-your-token",
     "userId": 146011,
     "organizationId": "123456",
     "command": "initiateConnection",
     "correlationId": "1",
     "parameters": {
         "resourceId": 178
     }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "reason": "Kick-start SMS sent to alarm panel",
  "data": {
      "command": "initiateConnection",
      "resourceId": 178,
      "brand": "DSC",
      "model": "NEO-2032",
      "networkId": "123456"
  }
}
```

### Spesific Error Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "not sent",
  "reason": "No GSM line number (MSISDN) defined for alarm panel",
  "data": {
      "command": "initiateConnection",
      "resourceId": 178,
      "userId": 20199
  }
}
```

***

## 13. Set Pin Code

> Updates the pin code for future operations.

### Request

```json theme={null}
{
  "messageType": "commandMessage",
  "appId": "replace-with-your-app’s-unique-id",
  "brand": "DSC",
  "jwtToken": "",
  "userId": 50678,
  "organizationId": "50164",
  "command": "setPinCode",
  "correlationId": "1",
  "parameters": {
    "resourceId": 786,
    "partition": 0,
    "userType": "master/installer/regular",
    "userIndex": 1,
    "currentPinCode": "83T47L2ueJdAs0Rl80pdUQ==",
    "newPinCode": "83T47L2ueJdAs0Rl80pdUQ=="
  }
}
```

### Success Response

```json theme={null}
{
  "messageType": "commandResponse",
  "correlationId": "1",
  "result": "success",
  "reason": "send",
  "data": {
    "command": "setPinCode",
    "resourceId": 786,
    "partitionNo": 0,
    "userType": "master/installer/regular"
  }
}
```

<Tip>
  Keep error handling DRY: implement a shared mapper from `result` + `reason` to user‑facing messages.
</Tip>