Connection

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 uplink and downlink messages. Default value is 0.
• radio=1 - forces the NS to include radio metadata into each uplink message. The default value is 0 (no radio metadata).
• duplicate=1 - forces the NS to stream all uplink message 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 N last 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 uplink and join_request messages, 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.
The parameter 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.

History retrieval

This functionality is mainly designed to handle reconnections and not to lose data in between.

The storage period for data is 15 minutes.
If you need to access older messages please use HistoryAPI.

Upon connection, you can retrieve old messages you may have missed.
To do that, you have to specify from_unixtime and/or last_messages parameters.

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 from_unixtime parameter.

However, you have to keep in mind that it may request quite a lot messages. To limit the amount, use the last_messages parameter.

Examples

Connect to the Data API without any filtering:

wss://ns.us.everynet.io/api/v1.0/data?access_token=89058167bcf482071da1a88036ca9aaf

Connect to the Data API and get messages only from a device with dev_eui=ef7bc2134bfa6ab0

wss://ns.us.everynet.io/api/v1.0/data?access_token=89058167bcf482071da1a88036ca9aaf&devices=ef7bc2134bfa6ab0