Connection to Data API is performed through WebSocket.
Please note that Websocket protocol implements so called PING/PONG messages to keep Websockets alive (https://tools.ietf.org/html/rfc6455#section-5.5.2\), even behind proxies, firewalls and load-balancers. Network server sends a PONG message to client every 25 seconds. This message does not require a response. Receiving of this message indicates that connection is active. To check connection client can send PING message, in response NS send a PONG message.
It is possible to specify the following parameters in query string of request:
access_token- this is a mandatory field that is used to authenticate connection request. This token could be generated using Management API or network server GUI in a 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 command generated by network server. MAC commands will be included into
downlinkmessages. Default value is 0.
radio=1- force NS to include radio metadata into each
uplinkmessage. Default value is 0 (no radio metadata).
duplicate=1- force NS to stream all
uplinkmessage duplicates from all gateways that was capable to receive a message. Default value is 0: no duplicates will be delivered to AS.
last_messages=- retrieve up to
Nlast historical messages. Maximum value is 1000.
from_unixtime- retrieve historical messages from a specific moment of time. Unix timestamp format.
types- tells NS to filter messages according to provide 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. Default value is:
types=uplink, downlink, downlink_request, join_request, status_response.
Read more about message types here.
gateways- tells NS that you want to receive messages if they receive only by 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 NS that you want to receive messages if they receive only by 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 NS that you want to receive messages if they receive only by 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 NS that you want to receive messages if they receive only by 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 NS that you want to receive 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 filter prior using this field. It is possible to do that through GUI or Management API.
All described parameters are passed through 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 performed on 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 the old messages, that you may miss.
To do that you have to specify
All the retrieved messages will come with flag
meta.history = true.
We don't want to disturb your current realtime traffic and communication, so all the historical messages will come in asynchronous manner.
You may receive current stream messages between the historical ones. It helps to keep latency-sensitive traffic up to date.
Example of reconnection with history retrieval
The best way to use the history feature is to store
meta.time of the last received message and later use that unixtime on the reconnect in the
But you have to keep in mind, that it may request quite a lot messages. To limit amount of them, use
Connect to Data API without any filtering:
Connect to Data API and getting message only from device with dev_eui=ef7bc2134bfa6ab0