Basics

Rules common to all WebSocket API commands. Command pages do not repeat them.

Messages

The client and the server exchange WebSocket text messages, each one a JSON object. The cmd field specifies the command. Command names usually end with _req in requests and with _resp in responses. There are exceptions: for example, connections_list and connection_kill have no suffix, and the server responds to set_alive_timeout with alive_timeout_resp. The exact names are on the command pages.

Besides responses, the server sends messages on its own:

• connected — right after connecting, see Connection;
• realtime_data — device data, if the connection is subscribed, see consume_req;
• downlink_status — statuses of sent frames, see Sending data to a device.
• consume_resp — right after connected, if auto-subscription is enabled in the application settings.

If the server cannot parse a request, it sends a service message — see Server service messages.

Tokens and access levels

You connect to the WebSocket API with an application identifier (APP_ID) and one of the application's tokens. Each token has its own access level: low or high. The application's tokens are listed on its page in the ONS web interface.

	Low level	High level
Visible devices	Devices of its application and of applications that granted it access to their data	All devices of the application owner
Managing applications, devices, multicast groups	No	Yes
Device data, sending downlinks, history	Yes	Yes

Some commands follow a different rule — it is stated in the "Access" line on the command page. For example, downlink_data_req and set_device_coordinates_req work, with a token of any level, with the devices of its application and of applications that granted it access.

These commands work only with a high access level token:

• applications: get_applications_req, create_application_req, delete_application_req;
• devices: create_device_req, update_device_req, delete_device_req;
• multicast groups: viewing, creating, updating, deleting and group membership;
• downlink_purge_req.

With a low access level token, these commands return status: 2 and error_code: 1. The realtime_data stream does not depend on the token level: data of its own application and of applications that granted it access arrives.

operation_id

An optional request field: any string, which the server returns unchanged in the response. It is used to match a response with its request — responses do not necessarily arrive in request order. If the field is omitted, the response contains an empty string.

• Pass a string. In some commands, for example downlink_data_req, a number instead of a string causes error 3.
• There is no operation_id in messages the server sends on its own (connected, realtime_data, downlink_status), in the responses to ping_req and set_alive_timeout, or in the service messages json_parse_error and invalid_req.

status, error_code, error_text

Field	Value
status	1 — success, 2 — error
error_code	Error code, only with status: 2. Numbering is specific to each command — see the "Errors" table on its page
error_text	Error text in English. Not every code has one

The same code may mean different things in different commands, so always check its meaning on the command page. The most common ones are:

• 0 — internal server error, or a value rejected by the database;
• 1 — no access: the command needs a high access level token;
• 3 — invalid data in the request: wrong field format, invalid value.

Exceptions:

• get_data_req and get_downlink_data_req respond with two messages: status: 1 — request accepted, status: 3 — data;
• a successful downlink_ack_req response has no status field;
• there is no status field in the response to ping_req, in service messages, or in messages the server sends on its own, except connected.

Field formats

Field	Format
devEui, application_eui, multicast_eui	16 hex characters, e.g. 6F1E570FFE14DBFC
devAddr, multicast_addr	8 hex characters
data	Payload — a hex string
Keys (app_key, nwks_key, apps_key)	32 hex characters
Dates in requests	YYYY-MM-DD HH:MM:SS+HHMM — always specify the time zone
Dates in responses	UTC: in database responses — YYYY-MM-DD HH:MM:SS+0000, in realtime_data and statuses — ISO 8601

Pass hex values in upper case: some commands compare them case-sensitively. Region codes (frequency plans) are on the create_device_req page.

See also

• Quick start — connect and get the first data.
• Connection — address, token check, keeping the connection alive.