Skip to main content
This is a public API!
A third‑party app sends control commands to field devices and receives both an immediate command acknowledgement and an eventual state‑change notification.

​
Transport & Topics

  • Publish commands to: resource/commands
    QoS: 2 (exactly‑once delivery negotiated by MQTT)
  • Subscribe for responses & notifications: application/third-party/appName/instanceId
Always include a unique correlationId in requests and verify the same value in responses/notifications. JWT must be valid; otherwise the gateway returns an error response.
Allways subscribe to topic application/third-party/appName/instanceId where appId value is appName.instanceIdin request payload!

​
Message Envelopes (Common)

​
Command Request

{
  "messageType": "commandMessage",
  "appId": "appName.instanceId",
  "brand": "Bimetri",
  "jwtToken": "replace-with-your-token",
  "userId": 12345,
  "organizationId": 23456,
  "command": "<command>",
  "correlationId": "<unique-id>",
  "parameters": { /* command-specific */ }
}

​
Command Response

{
  "messageType": "commandResponse",
  "correlationId": "<same-as-request>",
  "result": "<sent|not_send|failed|send_no_ack|unauthorized>",
  "reason": "<human-readable>",
  "data": { /* command-specific echo & device info */ }
}

​
Notification (Async)

{
  "messageType": "notification",
  "appId": "appName.instanceId",
  "correlationId": "<same-as-request-or-omitted>",
  "command": "<command>",
  "notificationType": "<event>",
  "userName": "<who-triggered>",
  "userId": 12345,
  "parameters": { /* event-specific payload */ }
}
Responses typically acknowledge queuing (e.g., result = “sent”), while notifications carry the final device state. Treat notifications as the source of truth for UI state.

​
1) setExtDO Command

Set an external digital output (relay/DO) to on/off.

​
Request

{
  "messageType": "commandMessage",
  "appId": "flexyWattApp.1",
  "brand": "Bimetri",
  "jwtToken": "replace-with-your-token",
  "userId": 12345,
  "organizationId": 23456,
  "command": "setExtDO",
  "correlationId": "100",
  "parameters": {
    "resourceId": 101,
    "output": 4,
    "status": 0
  }
}

​
Parameters

  • resourceId (number) – Target device identifier.
  • output (number) – Output index/port (1‑based unless otherwise provisioned).
  • status (number) – Desired state: 1 (on/closed), 0 (off/open).
Some deployments may validate output ranges per model; invalid ports will yield an error response.
For this example (due to "appId": "flexyWattApp.1"); subscribe to topic application/third-party/flexyWattApp/1 or application/third-party/flexyWattApp/# (for all instances) to receive responses and async notifications.

​
Immediate Response

{
  "messageType": "commandResponse",
  "correlationId": "100",
  "result": "sent",
  "reason": "Command Queued",
  "data": {
    "command": "setExtDO",
    "resourceId": 101,
    "brand": "Bimetri",
    "model": "BMM620",
    "networkId": "26:AA:E0:23:23:5E"
  }
}

​
Error Response (Example)

{
  "messageType": "commandResponse",
  "correlationId": "100",
  "result": "not_send",
  "reason": "The user does not have access rights to the resource!",
  "data": {
    "command": "setExtDO",
    "resourceId": 101,
    "userId": 12345
  }
}

​
State‑Change Notification

Emitted when the device confirms the output’s actual state. 
{
  "messageType": "notification",
  "appId": "flexyWattApp.1",
  "correlationId": "100",
  "command": "setExtDO",
  "notificationType": "extDOStateChanged",
  "userName": "Flexywatt User",
  "userId": 12345,
  "parameters": {
    "resourceId": 101,
    "brand": "Bimetri",
    "model": "BMM620",
    "networkId": "26:AA:E0:23:23:5E",
    "organizationId": 23456,
    "output": 4,
    "status": 1
  }
}
Use the pair (resourceId, output) plus correlationId to de‑duplicate and to reconcile UI state after reconnects.

​
Consumer Guidance

  • QoS & retries: Expect duplicate deliveries at QoS 1. Make handlers idempotent.
  • Timeouts: If no notification arrives, surface the queued state and allow users to retry.
  • Security: Store tokens securely; rotate when expired; never log full JWTs.
  • Tracing: Log correlationId on both publish and receive paths for observability.