Connection to the Data API is performed through WebSocket.
Please note that the Websocket protocol implements so called PING/PONG messages to keep Websockets alive (RFC6455), even behind proxies, firewalls and load-balancers. The network server sends a PONG message to the client every 25 seconds. This message does not require a response. Receipt of this message indicates that the connection is active. To check the connection, the client can send a PING message. In response, the NS sends a PONG message.
It is possible to specify the following parameters in the query string of the request:
access_token- this is a mandatory field that is used to authenticate a connection request. This token could be generated using the Management API or network server GUI in the tab Keys. This is the only mandatory field you need to specify to establish a connection.
lora=1- enables connection to receive not only application data, but also all MAC commands generated by network server. MAC commands will be included into
downlinkmessages. Default value is 0.
radio=1- forces the NS to include radio metadata into each
uplinkmessage. The default value is 0 (no radio metadata).
duplicate=1- forces the NS to stream all
uplinkmessage duplicates from all gateways that were capable of receiving a message. The default value is 0: no duplicates will be delivered to the AS.
last_messages=- retrieves up to
Nlast historical messages. The maximum value is 1000.
from_unixtime- retrieves historical messages from a specific moment in time. Unix timestamp format.
types- tells the NS to filter messages according to a provided list of message types. Accepts a comma separated list of message types. For example, if it is necessary to receive only
join_requestmessages, you should use:
types=uplink,join_request. The default value is:
types=uplink, downlink, downlink_request, join_request, status_response.
Read more about message types here.
gateways- tells the NS that you want to receive messages if they are received only by a closed list of gateways. Accepts a comma separated list of gateway identifiers. By default, this option is disabled (accepts data from any gateway).
applications- tells the NS that you want to receive messages if they are received only by a closed list of applications (APP_EUI_). _Accepts a comma separated list of APP_EUI identifiers. By default, this option is disabled (accepts data from any application).
devices- tells the NS that you want to receive messages if they are received only by a closed list of devices (dev_eui). Accepts a comma separated list of device identifiers. By default, this option is disabled (accepts data from any device).
tags- tells the NS that you want to receive messages if they are received only by a closed list of tags. Accepts a comma separated list of dtags. By default, this option is disabled (accepts data from device with any tag).
filter- tells the NS that you want to receive a message that was passed through a specific filter. Accepts a filter ID as a value. You can read more about filters here. You should create a filter prior to using this field. It is possible to do that through GUI or the Management API.
All described parameters are passed through the connection query string.
filter and parameters
types, gateways, applications, tags and devices are mutually exclusive. It means that you should specify or filter or any of the other parameters, but not together.
All filtering is performed on the NS side.
For your convenience, we store data for some amount of time.
downlink- 48 hours
other messages- 1 hour
Upon connection, you can retrieve old messages you may have missed.
To do that, you have to specify
All the retrieved messages will come with a flag
meta.history = true.
We do not want to disturb your current real-time traffic and communication, so all historical messages will come in an asynchronous manner.
You may receive current stream messages between historical ones. It helps keep latency-sensitive traffic up to date.
Example of reconnection with history retrieval
The best way to use the history feature is to store the
meta.time of the last received message and later use that unixtime on the reconnect in the
However, you have to keep in mind that it may request quite a lot messages. To limit the amount, use the
Connect to the Data API without any filtering:
Connect to the Data API and get messages only from a device with dev_eui=ef7bc2134bfa6ab0