For developers

MQTT outbound

Export Nextriv measurements in real time to your organisation’s public MQTT broker. This guide covers connection requirements, the frozen v1 message contract and the rules for a reliable consumer.

The contract at a glance

This integration is a one-way measurement export. Nextriv connects to the customer’s broker; it does not accept MQTT commands or expose an internal broker.

Nextriv → your broker

An outbound connection from Nextriv to the organisation’s public broker FQDN.

MQTT 3.1.1 + TLS

TLS 1.2 or later with full certificate and hostname verification.

QoS 1

At-least-once delivery with retain=false; consumers deduplicate by event_id.

Measurements only

v1 publishes measurement events, not alarms, acknowledgements, commands or device status.

Step-by-step setup

An organisation administrator manages the configuration under Settings → Integrations → MQTT (Ustawienia → Integracje → MQTT); operations are blocked during remote-assistance sessions. The application panel is currently available in Polish, so the original Polish labels appear in parentheses at first mention. The broker password and complete custom CA PEM are write-only; the panel may show the broker username and CA metadata such as fingerprint, subject and expiry.

1
Confirm access
The organisation needs an active PRO plan, and its administrator performs the configuration.
2
Prepare the broker
Create a dedicated user with CONNECT and PUBLISH rights limited to this integration’s topics.
3
Add the configuration
Enter a name, FQDN, port, topic root (“Główny topic”), broker username (“Użytkownik brokera”), password and optional CA bundle. A new configuration remains disabled.
4
Run the test
Confirm the operation with your account password. Nextriv connects, publishes a test message and waits for PUBACK. The limit is 10 attempts within 600 seconds for a given integration and administrator.
5
Enable delivery
Delivery can only be enabled after a successful test of the exact current configuration.

Changing the host, port, credentials, CA mode or topic root invalidates the test. Test the new revision before enabling it again.

Broker and TLS requirements

Target validation is fail-closed. The broker must be Internet-reachable through a public IPv4 record and present a certificate matching its FQDN.

Broker and TLS requirements
Item	Requirement
Protocol	MQTT 3.1.1 over TLS 1.2 or later; no plaintext connections.
Host	A public FQDN with a public A record. IP literals, private addresses and IPv6-only hosts are rejected.
Port	1024–65535; 8883 is the usual value.
Authentication	A dedicated username up to 256 B and password up to 4 KiB. Anonymous access and mTLS are not supported in v1.
Authorisation	CONNECT and PUBLISH to the integration topics. Nextriv does not need SUBSCRIBE.
System CA	A public chain trusted by the system trust store.
Custom CA	A complete PEM bundle up to 64 KiB and 32 CA certificates; no private keys or expired certificates.

If the broker filters source addresses, allowlist Nextriv’s fixed outbound IPv4 address: 23.88.47.92. Any address change will be announced before cutover.

Outside the v1 scope

a broker on a private network, a VPN or a tunnel established by Nextriv
plaintext, skip-verify, an IP literal or an IPv6-only broker
mTLS client certificates, anonymous access and inbound commands
a bidirectional bridge or access to Nextriv’s internal MQTT infrastructure

Topics

Each integration receives an immutable stream_id. device_id is the same public identifier used by the External API.

Measurement events

<topic_root>/<stream_id>/v1/measurements/<device_id>

Test message

<topic_root>/<stream_id>/v1/test

Topic root rules

1 to 128 UTF-8 bytes; the final measurement topic is at most 221 bytes
ASCII segments containing A–Z, a–z, 0–9, dot, underscore and hyphen, separated by a single /
no leading or trailing /, empty segments, + or # wildcards, or . and .. segments
the first segment cannot be $SYS
stream_id does not change when the integration is edited; a new integration receives a new stream

v1 measurement payload

One message represents one measurement event and carries its complete values map. There is no separate PUBLISH for each metric.

Example JSON message

{
  "schema": "nextriv.measurement.v1",
  "event_id": "evt_AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "change_seq": 12001,
  "id": "measurement_BBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBBB",
  "device_id": "dev_0123456789abcdef0123456789abcdef",
  "measured_at": "2026-07-10T10:00:00Z",
  "received_at": "2026-07-10T10:00:02Z",
  "published_at": "2026-07-10T10:00:03Z",
  "source": "live",
  "values": {
    "temperature": {
      "value": 3.4,
      "unit": "°C"
    }
  }
}

Contract fields

Dates use RFC 3339/ISO 8601 in UTC. A metric value is numeric or boolean, and its unit comes from the public metrics catalogue.

Contract fields
Field	Meaning
schema	The constant nextriv.measurement.v1.
event_id	A stable event identifier and deduplication key.
change_seq	A number for diagnosing ordering and gaps; it is not a globally continuous counter.
id	The public measurement identifier.
device_id	The public device identifier shared with the External API.
measured_at	When the measurement was taken at the source.
received_at	When Nextriv accepted the measurement.
published_at	When this delivery attempt was published to the broker.
source	live, device_history, replay or virtual.
values	At least one metric as { value, unit }; the set depends on the device and source.

Resolve the device name and location by device_id through the External API. MQTT intentionally excludes location, coordinates, signal quality, raw frames and internal identifiers. See the device endpoint in the External API.

Consumers should ignore unknown top-level fields. Removing a field or changing its type or meaning requires a new v2 schema and topic.

Test payload

The test uses a separate schema and topic, so it can be isolated from production measurement processing.

nextriv.test.v1 message

{
  "schema": "nextriv.test.v1",
  "test_id": "test_0123456789abcdef0123456789abcdef",
  "sent_at": "2026-07-10T10:40:00Z",
  "stream_id": "stream_0123456789abcdef0123456789abcdef"
}

A successful test proves only the connection, PUBLISH authorisation and receipt of PUBACK by Nextriv. It does not prove subscription or downstream processing in the customer system.

Delivery, duplicates and ordering

QoS 1 provides at-least-once semantics. Consumer design must account for retries, outages and independent device streams.

Deduplicate by event_id

A failure after PUBACK but before Nextriv records success can cause the same event to be published again.

Do not assume global ordering

There is no shared order across devices. change_seq is diagnostic and does not prove completeness for the entire organisation.

Tolerate retries

Transient failures are retried. A malformed message does not block later ones, and a delivery needing attention can be retried manually.

Treat published_at as attempt time

Event fields and the topic stay stable for a duplicate, but published_at can change.

Backlog scope

The export queue covers events accepted after the integration is first enabled.
A backlog can only be replayed within the 30-day retention window.
History from before the first enable is not published automatically.
Changing the target never silently redirects an old revision’s backlog to the new broker.

Configuration changes and safe operations

Panel operations require the administrator’s current password. The broker password and complete custom CA PEM are not returned to the browser afterwards; the broker username and safe CA metadata remain visible.

Editing invalidates the test

After changing the target, credentials, CA or topic root, run the test again before enabling delivery.

Backlog needs a decision

After a revision change, an administrator explicitly rebinds pending deliveries or discards them.

Losing the plan stops outbound

The configuration is preserved. After returning to PRO, an administrator selects Resume manually (“Wznów ręcznie”); a new test is only required if the configuration or previous test is no longer current.

Disable does not delete configuration

Manual Disable (“Wyłącz”) preserves the configuration but invalidates test authorisation — run a new test before selecting Enable (“Włącz”) again. Deletion explicitly discards the remaining backlog.

Key panel statuses

Key panel statuses
Status	Meaning
Active (“Aktywna”)	Measurements are being delivered to the configured broker.
Disabled (“Wyłączona”)	Configuration is preserved, but delivery remains disabled.
Test required (“Wymaga testu”)	Test the exact current configuration before enabling it.
Backlog (“Zaległości”)	At least some measurements are waiting for delivery.
Needs attention (“Wymaga uwagi”)	A delivery exhausted automatic attempts; an administrator can inspect the queue and retry the delivery manually.
Connection error (“Błąd połączenia”)	Delivery is temporarily paused after a series of broker failures.
Paused by plan (“Wstrzymana przez plan”)	Outbound stops immediately; configuration and queued deliveries are preserved.
Manual resume required (“Wymaga ręcznego wznowienia”)	After returning to PRO, select Resume manually. Repeat the test only if the panel marks it as no longer current.

Troubleshooting

The panel shows a safe error code and request identifier. Never attach credentials or a complete custom CA to a support request.

Troubleshooting
Code	Meaning and action
unsafe_target	Use a public FQDN; after resolution it cannot point to a private or reserved address.
dns_failed	Check the public A record, DNS delegation and any dependency on split DNS.
unsupported_address_family	The broker must be reachable over public IPv4; IPv6-only hosts are unsupported.
tcp_timeout / tcp_connect_failed	Check the port, firewall, routing and broker listener.
connack_timeout / connection_rejected	Check MQTT 3.1.1, connection limits and CONNECT policy.
tls_verify_failed	Check the complete certificate chain, validity and the complete custom CA bundle.
tls_hostname_mismatch	The certificate must contain a SAN matching the configured FQDN.
tls_certificate_expired	Renew the server certificate or an expired certificate in its chain.
auth_rejected	Check the dedicated username and current password; anonymous access is unsupported.
puback_timeout	Check broker health, PUBLISH rights to both integration topic patterns and whether QoS 1 completes with PUBACK.
rate_limit_exceeded	Wait and retry. The limit is 10 tests within 600 seconds for a given integration and administrator.
test_authorization_expired	Refresh the panel, confirm with your password and start a new test.

Consumer security rules

Use a separate broker user and least-privilege ACLs for each integration.
Treat payloads as organisation data and control access, retention and logging on your side.
Never put the password, custom CA or message identifiers in public logs.
Monitor duplicates by event_id and diagnostic gaps, but never treat MQTT as exactly-once delivery.

Ready to set up MQTT?

Tell us about the broker, TLS/ACL policy and expected volume. We will help you prepare a secure configuration and consumer.