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"
}