Real-Time WebSocket API

The Integration API delivers live telemetry over a WebSocket connection. Partners can subscribe to real-time updates for a resource (such as a device or job) and — with the stream:publish scope — push their own telemetry into the platform.

:::note No HTTP webhooks IDI Fly does not push events to partner-hosted HTTP callbacks. Real-time delivery is over this persistent WebSocket connection instead. :::

---

Connecting

Connect to the WebSocket endpoint with your JWT access token and a target resource ID in the query string.

URL format

wss://api.idi-fly.com/telemetry?token=<JWT_TOKEN>&resourceId=<RESOURCE_ID>

Production

wss://api.idi-fly.com/telemetry?token=<JWT_TOKEN>&resourceId=<RESOURCE_ID>

Query param	Required	Description
token	✅	JWT access token from POST /v3/auth/token
resourceId	✅	Resource to subscribe to (e.g. a device ID or job ID)

JavaScript

const token = 'eyJraWQiOi...';       // from /v3/auth/token
const resourceId = 'device-001';
const wsUrl = `wss://api.idi-fly.com/telemetry?token=${token}&resourceId=${resourceId}`;

const ws = new WebSocket(wsUrl);

ws.onopen = () => console.log('Connected to IDI Fly WebSocket');
ws.onmessage = (event) => console.log('Received:', JSON.parse(event.data));
ws.onerror = (error) => console.error('WebSocket error:', error);
ws.onclose = (event) => console.log('Disconnected:', event.code, event.reason);

wscat

npm install -g wscat
wscat -c "wss://api.idi-fly.com/telemetry?token=YOUR_TOKEN&resourceId=device-001"

---

Client actions

Send JSON messages with an action field.

Action	Purpose
subscribe	Start receiving updates for a resource
unsubscribe	Stop receiving updates
ping	Keep-alive — the server replies with a pong
publish	Push telemetry to subscribers (requires the stream:publish scope)

Subscribe

{ "action": "subscribe", "resourceId": "device-uuid-123" }

Keep-alive

{ "action": "ping", "timestamp": "2024-01-14T15:30:00Z" }

Publish (requires stream:publish)

{
  "action": "publish",
  "resourceId": "device-001",
  "data": {
    "type": "telemetry",
    "latitude": 51.5074,
    "longitude": -0.1278,
    "altitude": 120,
    "battery": 85
  }
}

---

Server messages

Inbound messages carry a type field.

Type	Meaning
telemetry	Live telemetry data for the subscribed resource
status	Resource status update
command_ack	Acknowledgement of a command
subscribed	Subscription confirmed
unsubscribed	Subscription ended
pong	Reply to a ping
error	Something went wrong (see message)

Example telemetry message

{
  "type": "telemetry",
  "resourceId": "device-uuid-123",
  "data": {
    "latitude": 51.5074,
    "longitude": -0.1278,
    "altitude": 120,
    "battery": 85
  },
  "timestamp": "2024-01-14T15:30:00Z"
}

---

Best practices

• Keep-alive — send a ping periodically (e.g. every 30 seconds) so the connection is not idle-timed-out.
• Reconnect with backoff — on disconnect, reconnect using exponential backoff and re-subscribe.
• Refresh tokens proactively — the token in the query string is validated on connect; reconnect with a fresh token before the old one expires (tokens last 1 hour).
• Publishing — to publish you need a Cognito App Client with the stream:publish scope. If you only consume telemetry you do not need it.

For a ready-made publishing integration, see the Node-RED nodes, which handle authentication, reconnection, keep-alive, and offline queuing for you.