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