Downlink — clear send queue

Withdraws all frames of a device that are waiting in the queue to be sent. Withdrawn frames are not deleted: they stay in the history with status 6 (Canceled).

Request and response: downlink_purge_req → downlink_purge_resp.
Access: high access level token only. With a low access level token the server responds with error 1.

Tip

cancel_downlink_req is better suited for withdrawing frames. It works with a token of any level, also withdraws frames with realTime, intercepts a frame the server is already preparing for transmission, and reports why a frame could not be withdrawn.

Request

Fields not marked as required may be omitted.

Field	Type	Description
cmd	string	downlink_purge_req
operation_id	string	Any string; the server returns it in the response to match the request and the response
devEui	string	devEui or devAddr is required. Device DevEUI, 16 hex characters
devAddr	string	devEui or devAddr is required. Device DevAddr, 8 hex characters

{
    "cmd": "downlink_purge_req",
    "operation_id": "xyz",
    "devEui": "6F1E570FFE14DBFC"
}

Response

Field	Type	Description
cmd	string	downlink_purge_resp
operation_id	string	Value from the request
status	uint8	1 — success, 2 — error
devEui, devAddr	string	The device whose queue was cleared
dataInQueuePurge	uint32	Number of withdrawn frames
error_code, error_text	uint8, string	Only on error, see below

{
    "cmd": "downlink_purge_resp",
    "operation_id": "xyz",
    "status": 1,
    "devEui": "6F1E570FFE14DBFC",
    "devAddr": "78130AE1",
    "dataInQueuePurge": 2
}

Errors

error_code	error_text	What happened
1	Unauthorized access	The request came with a low access level token
3	Data is filled in with an error	devEui or devAddr has an invalid format
7	Downlink queue empty	There are no waiting frames in the queue
8	Device does not exists	The device is not found
0	—	Internal server error — retry later

Good to know

• Only frames with status 0 (Scheduled) from the last month are withdrawn. Frames with realTime (status 4, Realtime Scheduled) stay in the queue.
• Clearing the queue may not stop a frame that the server has already picked up for transmission after the device's uplink. To stop such a frame too, use cancel_downlink_req.

See also

• Sending data to a device — how downlink works and in which order to call the commands.