The HTTP Integration allows you to send uplink data to an endpoint and receive downlink data over HTTP.
Getting started video #
Uplink #
You can configure the URL, the HTTP method (e.g. POST
) and optionally the HTTP Authorization header of your endpoint but also a custom HTTP header of your choice.
The integration will post data in the following format:
{
"app_id": "my-app-id", // Same as in the topic
"dev_id": "my-dev-id", // Same as in the topic
"hardware_serial": "0102030405060708", // In case of LoRaWAN: the DevEUI
"port": 1, // LoRaWAN FPort
"counter": 2, // LoRaWAN frame counter
"is_retry": false, // Is set to true if this message is a retry (you could also detect this from the counter)
"confirmed": false, // Is set to true if this message was a confirmed message
"payload_raw": "AQIDBA==", // Base64 encoded payload: [0x01, 0x02, 0x03, 0x04]
"payload_fields": {}, // Object containing the results from the payload functions - left out when empty
"metadata": {
"time": "1970-01-01T00:00:00Z", // Time when the server received the message
"frequency": 868.1, // Frequency at which the message was sent
"modulation": "LORA", // Modulation that was used - LORA or FSK
"data_rate": "SF7BW125", // Data rate that was used - if LORA modulation
"bit_rate": 50000, // Bit rate that was used - if FSK modulation
"coding_rate": "4/5", // Coding rate that was used
"gateways": [
{
"gtw_id": "ttn-herengracht-ams", // EUI of the gateway
"timestamp": 12345, // Timestamp when the gateway received the message
"time": "1970-01-01T00:00:00Z", // Time when the gateway received the message - left out when gateway does not have synchronized time
"channel": 0, // Channel where the gateway received the message
"rssi": -25, // Signal strength of the received message
"snr": 5, // Signal to noise ratio of the received message
"rf_chain": 0, // RF chain where the gateway received the message
"latitude": 52.1234, // Latitude of the gateway reported in its status updates
"longitude": 6.1234, // Longitude of the gateway
"altitude": 6 // Altitude of the gateway
},
//...more if received by more gateways...
],
"latitude": 52.2345, // Latitude of the device
"longitude": 6.2345, // Longitude of the device
"altitude": 2 // Altitude of the device
},
"downlink_url": "https://integrations.thethingsnetwork.org/ttn-eu/api/v2/down/my-app-id/my-process-id?key=ttn-account-v2.secret"
}
Note: Some values may be omitted if they are null
, false
, ""
or 0
.
Downlink #
Your application can schedule a downlink message to a URL for your application in a region, process name and app access key:
https://integrations.thethingsnetwork.org/ttn-eu/api/v2/down/my-app-id/my-process-id?key=ttn-account-v2.secret
This URL is also provided in each uplink message for convenience. However, you can call this URL any time to schedule a downlink. Note that ttn-eu
refers to the region; other valid regions are ttn-us-west
, ttn-brazil
and ttn-asia-se
.
Your application should POST
or PUT
a downlink message.
With raw payload #
You can schedule a message with raw payload using this format:
{
"dev_id": "my-dev-id", // The device ID
"port": 1, // LoRaWAN FPort
"confirmed": false, // Whether the downlink should be confirmed by the device
"payload_raw": "AQIDBA==" // Base64 encoded payload: [0x01, 0x02, 0x03, 0x04]
}
With payload fields #
You can also use payload fields if your application has an encoder payload function declared to encode JSON to binary:
{
"dev_id": "my-dev-id", // The device ID
"port": 1, // LoRaWAN FPort
"confirmed": false, // Whether the downlink should be confirmed by the device
"payload_fields": { // The JSON object to be encoded by your encoder payload function
"on": true,
"color": "blue"
}
}
Downlink scheduling #
By default, the downlink will replace the currently scheduled downlink, if any. It is also possible to schedule the downlink as the first or last item in the downlink queue.
{
"dev_id": "my-dev-id",
"port": 1,
"confirmed": false,
// payload_raw or payload_fields
"schedule": "replace" // Allowed values: "replace" (default), "first", "last"
}