Skip to main content
Version: 1.4

Inbound Integrations

Most devices connect to DeviceChain themselves, over MQTT or HTTP. Some never do: a LoRaWAN sensor talks to a gateway, and a network server such as ChirpStack or The Things Stack decodes what the gateway heard and forwards it over HTTPS. An inbound integration is the receiving end of that forward. It gives the sender a URL and a bearer token, finds the device each message is about, and stores the readings as ordinary measurements. From there on they behave like any other measurement: they have units, drive dashboards, trigger detection rules and raise alarms.

The same mechanism takes any other system that can send an HTTP POST, with JSON or a binary body, and you say where the device identifier is. This page covers ChirpStack v4, The Things Stack v3, generic JSON and generic binary, and then what is stored, how duplicates are handled, the limits, and what v1 does not do.

How it fits together​

An integration is a tenant resource with these settings:

SettingMeaning
TokenThe integration's name in the tenant. It is the last segment of the URL, and you choose it (chirpstack-eu868). It cannot change.
Sender typeCHIRPSTACK_V4, TTS_V3, GENERIC_JSON or GENERIC_BINARY. It fixes how the body is read, and it cannot change. The body is never guessed from its shape.
Device typesThe scope: only devices of these types are reached through the integration, whatever the sender claims. At least one, at most 50.
Device identifierHow the sender names a device: by DEV_EUI (the default), by DEVICE_ID (The Things Stack only), or, for a generic sender, by an alias scheme you name (ALIAS:custom.serial).
Generic settingsGeneric senders only: where the identifier is, where the array of uplinks is, and where the sender's own time is.
Store link metricsOff by default. Stores signal strength, signal-to-noise ratio and gateway count beside each uplink.
Accepting dataSwitch an integration off to refuse its traffic at once without deleting it.
Bearer tokenGenerated by the server (256 random bits), shown once when you create the integration or rotate its token, and stored only as a keyed digest.

Each message goes through the same steps:

  1. The platform checks the bearer token against the integration named in the URL, before it reads the body.
  2. It reads the body by the integration's sender type and takes out the device identifier.
  3. It looks up the device that carries that identifier as an alias. A device outside the integration's scope, or no device at all, means the message is not stored.
  4. It turns the decoded values into readings and stores them as measurements of that device.

How many integrations a tenant may hold is a tier setting, Integrations per tenant. The platform default is 5, a tier can set up to 100, and 0 means none. Creating one past the ceiling is refused.

The URL​

Every integration is reached at one public address:

POST https://<host>/api/integrations/{tenant}/{integration}[/{messageType}]
Authorization: Bearer <bearer-token>
  • <host> is the address of your instance, the same one you open the console on. Substitute it; the instance id is not part of the URL.
  • {tenant} is the tenant's token and {integration} is the integration's token.
  • {messageType} is optional. Only The Things Stack uses it, because it posts each kind of message to a path of its own.
  • Only POST is accepted. Any other method is answered 405.
  • The token goes in the Authorization header and nowhere else. A token in the URL would be written to access logs.

The console shows the URL, the header and the settings the sender needs when you create the integration, on the dialog that shows the token once, and again on the integration's page under Connect the sender.

A network server run by someone else must trust your certificate

A hosted network server will not trust an instance that serves a self-signed certificate. Give the host a certificate from a public CA (ingress.tls.clusterIssuer) before you connect a hosted one. A network server you run yourself can be given your CA instead.

If you operate the instance, event-sources must also be told which proxies in front of it to believe for a client's address (infrastructure.http.trustedProxies), or every sender shares one request allowance. dcctl sets it; see Client addresses and trusted proxies.

Before you connect a sender​

  1. Have a device type with a profile. Devices of this type are the ones the integration can reach. Declare a metric for each decoded value you want units or validation for, using the same key the decoded object produces. Keys you do not declare are still stored, without a unit.
  2. Create the integration. In the console, open Connect → Integrations in the sidebar and choose New integration. Pick the Sender type, the Device types it may reach and, for a network server, the Device identifier. Turn on Store link metrics if you want signal data. Choose Create integration, and copy the bearer token from the dialog. It is shown once; if you lose it, rotate it. The Integrations page needs the device:read permission to open and device:write to change.
  3. Add the devices with their aliases, as in the next section. You can do this before or after the sender starts: messages for a device that does not exist yet are listed so that you can create it from what was seen.

With GraphQL, createIntegration returns the integration and the token together:

mutation {
createIntegration(request: {
token: "chirpstack-eu868"
name: "ChirpStack EU868"
type: "CHIRPSTACK_V4"
enabled: true
deviceTypeTokens: ["lora-sensor"]
linkMetrics: true
}) {
integration { token type identity }
issuedToken
}
}

rotateIntegrationToken(token) replaces the token and returns the new one once. The old token stops working at once, with no overlap, so update the sender straight after. updateIntegration changes everything except the token and the type. deleteIntegration removes the integration; the aliases on devices stay.

Identify devices with aliases​

A message names a device the way the sender knows it, not the way DeviceChain does. A device alias records that name on the device. An alias is a scheme and a value:

SchemeThe valueStored as
lorawan.deveuiThe LoRaWAN DevEUI: exactly 16 hexadecimal digits.Upper case. 70b3d57ed0012345 and 70B3D57ED0012345 are the same alias.
tts.device-idThe device id the device has in The Things Stack: 1 to 36 letters, digits and hyphens, not starting or ending with a hyphen.Lower case.
custom.<name>Any identifier of your own, for a generic sender: 1 to 128 characters with no control characters. The name starts with a lower-case letter or digit and continues with lower-case letters, digits, hyphens and underscores, up to 63 characters in all.As written. Case matters.

A device holds at most 8 aliases and one value per scheme, and a scheme and value can belong to only one device in the tenant. Writing a DevEUI in lower case, or with surrounding spaces, is fine: it is normalized when it is stored and when a message arrives. Anything that is not 16 hexadecimal digits is refused.

Set an alias:

  • in the console, in the Aliases field of the device form: choose Add alias, pick LoRaWAN DevEUI, Network server device id or Custom scheme, and type the value;
  • over GraphQL, with aliases: [{scheme: "lorawan.deveui", value: "70B3D57ED0012345"}] on createDevice or updateDevice. On an update, the list you send replaces the device's aliases, and an empty list removes them;
  • on importDevices, in the same aliases field.
mutation {
createDevice(request: {
token: "boiler-room-3"
deviceTypeToken: "lora-sensor"
aliases: [{ scheme: "lorawan.deveui", value: "70b3d57ed0012345" }]
}) { token aliases { scheme value } }
}

To find a device by alias, give devices a criteria alias: {scheme: "lorawan.deveui", value: "..."}.

The integration's Device identifier decides which scheme it looks up: DEV_EUI reads lorawan.deveui, DEVICE_ID reads tts.device-id, and ALIAS:custom.serial reads custom.serial. A device that carries only a different scheme is not found.

Changing or removing a device's identifier. Moving an identifier (a DevEUI, a device id) to another device, or removing it, takes effect within about five minutes. Until then the integration endpoint may still name the old device for that identifier, but the platform checks at the event that the device still holds the identifier, so those uplinks are refused and kept in the dead-letter store for inspection (reason IntegrationAliasMismatch, counted by devicechain_devicemanagement_resolve_integration_alias_mismatch_total). They are never stored on any device and cannot be replayed. Once the change has propagated, uplinks land on the device that holds the identifier now. A device you create for an identifier that was already arriving starts receiving within a minute.

ChirpStack v4​

ChirpStack sends uplinks through an HTTP integration on an application.

  1. In the console, create an integration of sender type ChirpStack v4, with the device types and, if you want them, link metrics. Copy the bearer token.

  2. In ChirpStack, open the application, add the HTTP integration and fill it in:

    ChirpStack fieldValue
    Payload encodingJSON. A Protobuf integration is refused with 415, and the message names this setting.
    Event endpoint URL(s)https://<host>/api/integrations/{tenant}/{integration}. ChirpStack adds ?event=up itself.
    HeadersName Authorization, value Bearer <bearer-token>.
  3. Set a codec on the ChirpStack device profile (a JavaScript payload codec). Without a profile decoder, the platform stores the values the network server decodes. If neither a network-server codec nor a profile decoder applies, the uplink is counted as undecoded instead of stored. Alternatively, give the device type a payload decoder, which reads the raw frame in DeviceChain.

  4. Add the devices in DeviceChain with their DevEUI as a lorawan.deveui alias.

Uplinks are stored as readings. ChirpStack also sends the events ack and txack to the same URL, which an installation with the LoRaWAN downlink switched on reads to settle confirmed downlinks; without it they are answered 204 and ignored unread, like the other events (join, status), whatever their bodies hold. The uplink's deduplicationId must be a UUID, which ChirpStack always sends; anything else is refused with 400. The message time is the time ChirpStack reports, or the time the platform received it when the field is absent.

The Things Stack v3​

The Things Stack sends uplinks through a webhook on an application.

  1. In the console, create an integration of sender type The Things Stack v3. Under Device identifier choose DevEUI, or Device id if you would rather match the device id from The Things Stack. Copy the bearer token.

  2. In The Things Stack, open the application, add a Custom webhook, set the format to JSON, and fill it in:

    The Things Stack fieldValue
    Base URLhttps://<host>/api/integrations/{tenant}/{integration}
    Additional headersName Authorization, value Bearer <bearer-token>.
    Enabled event typesUplink message, enabled, with the path /uplink-message. The platform also reads the paths /up, /uplink and /uplinks.
  3. Set a payload formatter on the application or on the device (the LoRaWAN Device Repository offers one for many sensors). The platform stores the formatter's output; it does not decode the raw frame. Without one, the uplink is counted as undecoded. Alternatively, give the device type a payload decoder, which reads the raw frame in DeviceChain.

  4. Add the devices in DeviceChain with their DevEUI as a lorawan.deveui alias, or their device id as a tts.device-id alias if you chose Device id.

A message posted to any other path (a join accept, a location solve) is answered 204 and ignored, as is a downlink event that does not belong to a downlink the platform sent (see The Things Stack downlink), so you can enable other message types without changing anything in DeviceChain, but there is no reason to. The message time is the uplink's received_at, which must be present and not older than 366 days. The deduplication key is the device, the frame counter and that time together, because the counter restarts when a device rejoins.

Generic JSON​

Use a generic JSON integration for any system that can post JSON: a gateway vendor's cloud, a middleware, a script. You tell the platform where to find the pieces. When you create the integration choose sender type Generic JSON, set Device identifier to the alias scheme the identifiers are in (ALIAS:custom.serial, for example), and fill in the settings. Over GraphQL they are the generic field, a JSON document in a string:

SettingMeaning
idFromRequired. Where the device identifier is: pointer:/device/id (a JSON pointer into each item), header:X-Device-Id (a request header) or query:device (a query parameter). A header or query identifier applies to every item of the request.
itemsPointerOptional. A pointer to an array in the body; each element is one uplink. Without it the body is one uplink, or a bare array of uplinks.
timePointerOptional. A pointer to the time the sender recorded, as an RFC 3339 string or an epoch number in seconds or milliseconds. Without it the time of receipt is used.
framePointer, frameEncodingOptional. Where an encoded raw frame is (HEX or BASE64). It is only sampled, to help you see what an undecoded uplink held.

Every key in an item except the identifier and the time is a candidate reading. For example, with idFrom set to pointer:/serial, itemsPointer set to /readings and timePointer set to /ts:

curl -X POST https://dc.example.com/api/integrations/acme/vendor-cloud \
-H "Authorization: Bearer $INTEGRATION_TOKEN" \
-H "Content-Type: application/json" \
-d '{"readings": [
{"serial": "A-100", "ts": "2026-10-27T09:00:00Z", "temperature": 21.4, "battery": {"voltage": 3.1}},
{"serial": "A-101", "ts": "2026-10-27T09:00:00Z", "temperature": 19.8, "door": false}
]}'

An array carries at most 100 items. A body that cannot be read, or an item with no identifier, is refused whole with 400 and nothing is stored. Items for devices the tenant does not have are skipped one by one and listed as unregistered; the rest are stored.

A retry from a generic sender is stored twice unless you give it a sender time

Without timePointer, the platform stamps an item with the time it received it, so the same item sent again looks like a new one. Set timePointer to a field the sender fills in once per reading, and a retry carries the same time and is stored once. See Duplicates and retries.

Generic binary​

A generic binary integration accepts a body of raw bytes, with the identifier in a header or a query parameter (idFrom is header: or query:; a binary body has no fields to point into). Without a payload decoder on the device's type, the platform cannot read the bytes, so every such uplink is accepted, counted as undecoded and its first 512 bytes kept as a sample on the integration. Use it to see what a sender sends before a decoder exists. With a decoder on the device's type, the bytes are decoded into readings.

What is stored​

The decoded object each message carries (ChirpStack's object, The Things Stack's decoded_payload, a generic item) is flattened into measurements of the device. One message becomes one event with these readings:

  • Every number is a reading, keyed by its dot-joined path: {"temperature": 21.4, "battery": {"voltage": 3.1}, "sensors": [{"value": 7}]} stores temperature, battery.voltage and sensors.0.value.
  • A boolean is stored as 1 for true and 0 for false.
  • A string or a null is skipped. So is any value nested deeper than 32 levels, and any path that is not a valid measurement key (letters, digits, _, . and -, at most 128 characters, not starting with . or -). Nothing is renamed to make it fit.
  • Declare a metric with the same key to give a reading its unit and validation. A reading with no declared metric is stored without a unit.
  • The message time is the sender's when it gives one, and the platform's receipt time otherwise.
  • A message that flattens to more than 256 readings is refused whole with 400, not truncated.

With Store link metrics on, three more readings are stored with each uplink from the network server's reception report: lorawan.rssi and lorawan.snr for the strongest reception, and lorawan.gateways, the number of gateways that heard the uplink. These names belong to the platform; a decoded value with the same key is skipped.

Uplinks with nothing to store​

Without an applicable profile payload decoder, an uplink that carries no decoded object, or one with no numeric or boolean value in it, is acknowledged but stores nothing. The integration counts it as undecoded, and its page shows the count, when the last one arrived and a sample of the raw frame in hex. The usual cause is a device profile with no codec in the network server. When a profile decoder applies, it can decode the raw frame instead; a decode that fails stores nothing and is reported as DECODE_FAILED, rather than counted as an undecoded network-server payload. See Decoder refusals. The IntegrationUndecodedHigh alert tells an operator when most traffic is like this; see Observability.

Duplicates and retries​

A network server that does not get an answer in time sends a message again, and a gateway can deliver one uplink twice. Each message carries a key the platform stores with the event, and an event whose key is already stored for that device and time is not stored again.

SenderThe key
ChirpStack v4The deduplicationId.
The Things Stack v3The device's DevEUI (its device id, when the integration identifies devices by DEVICE_ID and the message carries no DevEUI), the frame counter and received_at.
Generic, with timePointerA digest of the device and the item, plus the sender's time. A retry carries the same item and time, so it is stored once.
Generic, without timePointerA digest of the device and the item, plus the time of receipt. A retry is a new key, so it is stored twice.

The platform also drops a repeat that carries the same key within ten minutes of the first, before it is processed; a generic sender without timePointer gets a new key on every send, so this does not cover it. A key is at most 192 bytes; a longer one is refused with 400. Neither rule merges two different uplinks that happen to hold the same values.

Unregistered devices​

When a message names an identifier that no device in the integration's scope carries, the platform does not store it. It records the identifier on the integration instead, so you can see which devices are talking to you that you have not added. Open the integration in the console and look under Unregistered devices seen: each row shows the scheme, the identifier, how many times it was seen and when. Create a device with this alias opens the device form with the alias filled in, and the type too when the integration is scoped to exactly one device type. Over GraphQL, the list is unregisteredIntegrationDevices(criteria).

  • The list holds at most 1,000 identifiers per integration. Past that, new ones are counted and not listed.
  • A sighting is recorded at most once a minute for each identifier on each event-sources replica, so the count is a measure of activity and not an exact message count.
  • An identifier that a device outside the integration's scope already carries is not listed, so the list never shows a value a device already holds.
  • Clear list (clearUnregisteredIntegrationDevices(integration)) empties it. It is a list of observations, so an identifier the sender is still sending is listed again.

What the sender is told​

A network server sees only the status code, and some suspend a webhook that is refused too often. The route is built around that.

AnswerMeaning
202Accepted. Includes messages for devices that are not registered, which are skipped, and messages shed because the tenant is over its ingest allowance.
204An ignored message type, such as join or status, or a downlink report when the downlink adapter is disabled. Supported downlink reports are processed when the adapter is enabled and answered 202; see Confirmed downlinks.
400The body is not what the integration's sender type expects: invalid JSON, a missing or malformed identifier, a deduplicationId that is not a UUID, a time older than 366 days, more than 100 items, or more than 256 readings. Nothing in the request is stored.
401The token is missing, wrong, or belongs to a different integration. A wrong token and an integration that does not exist are indistinguishable on purpose.
403The integration is switched off. This is not counted as a failed login.
405The method is not POST.
413The body is over 256 KiB.
415ChirpStack is sending Protobuf. Change its payload encoding to JSON.
429Too many failed logins for this integration, too many requests from one address whose token the platform has not just verified, or, on one replica, too many requests for integrations it has never verified. Retry after the Retry-After interval.
503The platform cannot check the token or take the message right now, or is applying backpressure. Retry. A Retry-After header means the platform is applying backpressure: a single uplink was not stored, but in a generic array the items before the refusal may have been, so give a generic sender a timePointer to make the retry safe.

A change to an integration is quick but not instant at the endpoint, which remembers what it learned about an integration for up to a minute (up to 15 minutes while device-management is unreachable). After you rotate a token or switch an integration off, it can keep answering 202 for up to a minute to a sender that is still using the old one, but nothing sent in that minute is stored. After you switch an integration back on, it can keep answering 403 for up to a minute.

Limits​

LimitValue
Request body256 KiB
Decoded object, or one generic item64 KiB, nested at most 32 levels
Items in a generic array100
Readings in one uplink256
Age of a time the sender reports366 days
Integrations per tenant5 by default, set by the tier, at most 100
Aliases on a device8, one value per scheme
Unregistered identifiers listed per integration1,000

The tenant's ingest allowance. Integration traffic is metered in an allowance of its own at the tenant's ingest ceiling, counted in readings like every other transport, apart from the allowances MQTT and HTTP ingest spend. The allowances are separate, so a tenant that sends over several paths at once can be admitted above one ceiling in total, on each event-sources replica; see When ingest can admit a tenant above its ceiling. A request carrying an array of N uplinks is charged N times, so a big array does not buy a cheaper rate.

Over the allowance, the answer is 202, not 429. A refusal would lose the message anyway, and some network servers suspend a webhook that is refused, which would then drop traffic that was within the allowance. The consequence is that the sender believes the data arrived and it did not. The IntegrationShedAccepted alert tells an operator when this is happening; raise the tenant's ceiling or reduce what the integration sends.

Bounds on unauthenticated traffic. Someone who knows an integration's URL cannot use it to spend the tenant's allowance or an integration's good traffic: wrong tokens are limited per integration (a burst of 30, then 1 a second), requests whose token the platform has not verified in the last minute are limited per source address (a burst of 60, then 5 a second) and, for integration names it has never verified, per replica (a burst of 100, then 20 a second). The ingress-nginx front end also limits each address to 200 requests a second and answers 503 beyond that; it limits per client only when the controller is told to trust the load balancer's forwarded address, and the Gateway API front end has no such limit. A network server's steady traffic with a valid token costs its address about one request a minute against the platform's own limits. The IntegrationAuthFailuresSustained alert fires when failures keep up for ten minutes, which is what a sender still using a rotated token looks like.

Commands to integration devices​

A device that reports through an integration has no connection to DeviceChain to send a command down. Unless the LoRaWAN downlink is switched on for your installation, a command to such a device is accepted when you issue it, and then fails at the next delivery sweep with COMMAND_TRANSPORT_UNSUPPORTED, because the platform recognizes the transport and has no way to deliver on it. It does not wait in the queue until it expires.

Two cases are worth knowing:

  • A device that also connects over MQTT is judged by the last transport it reported on. While it last reported through the integration its commands fail; after it reports over MQTT they are delivered.
  • A device that has never reported has no recorded transport, so its commands are dispatched as usual, and expire unanswered, until it first reports.

For a device that must be commanded and is not behind a ChirpStack v4 network server, give it an MQTT connection as well. See the transport matrix.

An installation that runs the outbound connectors with the downlink switched on (functionalAreas.outbound-connectors.config.lpwanDownlink.enabled: true; the Helm chart then makes command delivery dispatch these commands, and refuses a hand-set copy of that flag) sends a command to a device behind a ChirpStack v4 network server by queueing a downlink on that server. Nothing changes for an installation that leaves it off.

1. Link the integration to its network server. Create and publish a connector of type lorawan_downlink:

{
"networkServer": "chirpstack_v4",
"baseUrl": "https://chirpstack.example.com",
"integration": "my-integration-token"
}

integration is the token of the inbound integration whose devices this server serves. The connector's secret is a ChirpStack API key allowed to enqueue downlinks (the REST API of ChirpStack v4, served by its chirpstack-rest-api component); it is stored encrypted and never shown again. Exactly one published connector may name an integration: with none, or with two, a command is refused rather than sent. Like every connector, the call to baseUrl goes through the platform's egress policy, so a server on a private address needs an operator allowance.

2. Define the command. Without an encoder, give the device type's profile a command with these raw payload parameters. To send typed values instead, configure an encoder:

ParameterMeaning
fPortThe LoRaWAN application port, 1 to 223. Required.
hex or base64The application payload, as hexadecimal or standard padded base64. Give exactly one. At most 242 bytes.
confirmedOptional, default false. true asks the device to acknowledge the frame and holds the command until it does (see Confirmed downlinks).

Any other parameter name is refused.

3. Send it. The device must carry a lorawan.deveui alias: the DevEUI is read from the device, never from the command. The command goes through the integration the device last reported through.

What the outcome means. For an unconfirmed downlink, SUCCEEDED means the network server queued the downlink (the result carries {"stage":"queued","queueItemId":...}). It does not mean the device has received it: a class A device hears downlinks only after it next transmits, and an unconfirmed downlink gets no acknowledgement. For a confirmed downlink, SUCCEEDED means the device acknowledged it. The other outcomes:

What happenedOutcome
A parameter is invalid, the device has no DevEUI, the integration has no (or two) links, the command expired, or the tenant is over its outbound call ceilingFAILED, not delivered. Safe to send again.
The network server refused it (a 4xx: wrong API key, unknown device, payload too large for the device's current data rate) or could not be reached before anything was sentFAILED, not delivered. The reason names the server's answer.
The request was sent and the server failed or did not answer (a 5xx, a timeout)The outcome is unknown: the downlink may be queued, and sending again may send it twice.

Check the lpwan_downlinks_total metric by result to see where commands stop.

Confirmed downlinks​

Set "confirmed": true in the command and the network server asks the device to acknowledge the frame. The command is not answered when the downlink is queued: it stays SENT until the network server reports what happened, and then settles from that evidence:

What the network server reportsCommand
The device acknowledged the frame (ack, acknowledged)SUCCEEDED. The result carries {"stage":"acknowledged",...}.
The network server gave up waiting for the acknowledgement (ack, not acknowledged)TIMEOUT, outcome unknown. The device may have heard the frame and its acknowledgement been lost, so sending again may act twice.
A gateway accepted the frame for transmission (txack)Recorded, and the command keeps waiting. A gateway sending a frame is not the device receiving it.
Nothing by the deadlineTIMEOUT, outcome unknown. The deadline is the command's own expiry, or 24 hours when it has none.

ChirpStack reports an acknowledgement only if the HTTP integration of the application is set to send the ack event, and the same integration must be the one you registered in DeviceChain (the URL and token above): the report is read through the integration's own token, so it can only settle commands sent through that integration, to devices registered under it. Enable the txack event as well if you want the transmission to be recorded; it is optional.

A report that matches no waiting downlink is never matched by guess. It is dropped, logged, and counted in lpwan_ack_reports_total (unmatched when nothing waits for that queue item, mismatch when it names another integration or device); both are worth an alert. Every downlink produces a txack, confirmed or not, so one for a downlink that is not waiting is counted as tx_untracked and is normal. During a rolling upgrade, a pod of the previous version still refuses a confirmed command as not delivered, which is safe to send again.

Check lpwan_ack_reports_total by result: acknowledged, timed_out, transmitted and deadline are the outcomes above. One unmatched now and then is not a fault: if a report is answered but the broker's acknowledgement of the message is lost, the report arrives again and finds nothing waiting (a replica that settled it moments ago counts it redelivered instead). Alert on a sustained rate of unmatched or on any mismatch.

A txack for a downlink that carried only MAC commands has no queue item and is answered 204 and counted (integration_downlink_reports_total, result untracked); an ack with no queue item is refused with 400. Reports have a limit of their own, separate from telemetry: a burst of 100 per tenant and 20 a second sustained. The limit is kept per event-sources replica, so a tenant's effective ceiling is that rate times the number of replicas. Beyond it the request is answered 202 and counted (result rate_limited), and the command it would have settled settles at its deadline, so one tenant's flood cannot crowd out another's acknowledgements.

Upgrading. Confirmed downlinks need the new version of both the outbound connectors and the event sources. While the outbound connectors are new and the event sources still old, the network server's reports are answered 204 and dropped by the old pods, so a confirmed downlink sent in that window settles TIMEOUT, outcome unknown, at its deadline. The chart rolls them in the same upgrade; to avoid the window, hold confirmed commands for its length.

A link to The Things Stack is a lorawan_downlink connector with "networkServer": "tts_v3" and the application the devices belong to:

{
"networkServer": "tts_v3",
"baseUrl": "https://eu1.cloud.thethings.network",
"integration": "my-integration-token",
"applicationId": "my-application"
}

The connector's secret is an API key with the right to write downlink traffic of that application. The device must carry a tts.device-id alias, which is what The Things Stack addresses it by, instead of a DevEUI; it is read from the device, never from the command. The command's parameters are the same as for ChirpStack, and the downlink joins the end of the device's queue.

For an unconfirmed downlink, SUCCEEDED again means the network server accepted it. For a confirmed one, the platform gives each downlink an identifier of its own (The Things Stack returns none), sent as a correlation id that starts with dc:, and settles the command from the events The Things Stack posts for that downlink. In the application's webhook, enable the downlink events and give each its own path under the integration URL, with a path that starts with downlink: for example /downlink-ack, /downlink-nack, /downlink-sent and /downlink-failed.

What The Things Stack reportsCommand
downlink_ack: the device acknowledged the frameSUCCEEDED.
downlink_nack: the device did not acknowledge itTIMEOUT, outcome unknown. The device may have heard the frame and its acknowledgement been lost, so sending again may act twice. See the note on retries below.
downlink_sent: a gateway transmitted the frameRecorded, and the command keeps waiting.
downlink_failed, and the network server itself names a drop before transmission (a confirmed downlink queued for a multicast device), with no retry and no transmission reported before itFAILED, not delivered. Safe to send again.
Any other downlink_failedTIMEOUT, outcome unknown. The frame may have been transmitted: see below.
Nothing by the deadlineTIMEOUT, outcome unknown.

Retries after a nack. After a downlink_nack, The Things Stack re-queues a confirmed downlink itself (up to 8 more times by default), and each retry is a fresh downlink the device may act on. DeviceChain closes the command at the first nack, so the device can still execute it afterwards, and the acknowledgement of a retry arrives after the command is closed and is dropped as unmatched. To keep that window small the platform sets confirmed_retry.max_attempts to 1 on every confirmed downlink it pushes (the lowest value The Things Stack accepts), so there is at most one retry.

Why only some downlink_failed events are "not delivered". The network server emits downlink_failed when it drops a queued downlink it never scheduled (the cases named in the table) and when a gateway reports it could not transmit. The Application Server emits it too, when it gives up retrying a confirmed downlink that was transmitted (the retries are exhausted, or re-queuing the retry failed). Because the event does not otherwise say which, DeviceChain answers FAILED only for the network server's own pre-transmission errors, and never for a downlink that was reported transmitted or retried; every other downlink_failed is TIMEOUT. That includes an unknown session, a payload that is too long, an expired downlink, a gateway scheduling failure (invalid absolute time or fixed paths) and a gateway's own transmission error: if a scheduling call to a gateway fails ambiguously the network server re-queues the item with no retry counted and no transmission reported, so a later drop for any of these reasons cannot be told apart from a drop of an item that was never tried. Only the multicast case, a static property of the device, is certain.

A report is matched to its command only by the dc: correlation id the platform set, and only when it names the application and device the downlink was sent to (and the device DeviceChain itself resolved agrees), through the integration it was sent through; the network server's own trace identifiers are never used. A downlink queued by hand in The Things Stack console carries no such id, and its events are ignored. Mismatches and unmatched reports are counted and dropped as described above. A webhook posted to the bare base URL, with no path, names no message type, so its reports are treated like telemetry and can be shed when the tenant is over its message ceiling; give each type its own path.

Switching it on in a running installation. The downlink is enabled by one Helm upgrade, and while the pods roll, command delivery pods that have not yet restarted still fail a command to an integration device on sight, as they did before the downlink existed, with COMMAND_TRANSPORT_UNSUPPORTED. Nothing is sent for such a command and it is safe to issue again once the upgrade has finished. To avoid the window, pause commands to integration devices for the length of the upgrade. A command issued in the minutes before the adapter first starts is still picked up when it does.

Encoding commands from typed parameters​

A command definition can carry an optional encoder JSON string. Publish the device profile to activate it. Both ChirpStack v4 and The Things Stack v3 use the same encoder. The encoder in force when a command is dispatched applies; republishing applies to commands dispatched after the publish, including commands already queued. The published definition is read afresh for every dispatch, with no encoder cache across a publish. If the definition lookup fails or returns an incomplete response, it is retried: the command stays pending and nothing is sent. A definitive definition problem (an invalid encoder, duplicate command definitions, or a command absent from a constrained published vocabulary) refuses the command as not sent. For example, this document combines constant bytes, a scaled number, a boolean and packed bits:

{
"fPort": 10,
"confirmed": false,
"fields": [
{"const": "01ff"},
{"param": "level", "type": "u16be", "scale": 0.1, "offset": 0},
{"param": "enabled", "type": "bool"},
{"bits": {"type": "u8", "fields": [
{"param": "mode", "shift": 0, "width": 3},
{"param": "armed", "shift": 3, "width": 1}
]}}
]
}

fPort is required, from 1 through 223. confirmed defaults to false and keeps the acknowledgement-feed requirement above. There must be 1–32 ordered fields, producing 1–242 bytes in total. Constants are even-length hex. Numeric types are u8, i8, u16be, u16le, i16be, i16le, u32be, u32le, i32be and i32le. bool emits 00 or 01. Packed bits use an integer type; their ranges must fit without overlap, and unspecified bits remain zero.

For a thermostat, declare setpoint as DOUBLE and mode as INT in parameterSchema, then set the definition's encoder to:

{
"fPort": 12,
"fields": [
{"param": "setpoint", "type": "i16be", "scale": 0.1},
{"bits": {"type": "u8", "fields": [
{"param": "mode", "shift": 0, "width": 3}
]}}
]
}

The command payload {"setpoint":21.5,"mode":3} becomes hex 00d703, or base64 ANcD, on port 12. Numeric encoding inverts the decoder arithmetic: raw = (value - offset) / scale. Scale defaults to 1; its magnitude must be between 1e-9 and 1e9. Offset defaults to 0 and its magnitude must be at most 1e9. Both must be finite. Scale/offset combinations that leave too little float64 precision for the 1e-6 raw-integer tolerance are refused when you save the definition, even if both values meet those individual bounds. Increase the scale magnitude or reduce the offset magnitude to resolve this. The raw value is checked against its type range before rounding, allowing 1e-6 at the boundaries for floating-point error. Identity mappings (scale 1, offset 0) require an exact integer input; other mappings allow a 1e-6 integer tolerance. Input magnitude must be at most 1e15, and input and raw magnitudes must be below 2^53. Nothing is silently rounded or truncated: 215.4 with scale 1 is refused. NaN, infinity, out-of-range values, wrong JSON types and missing encoder parameters refuse the command as not sent, before any network call. Defaults in the parameter schema are authoring hints and are never injected.

Each encoder parameter must be unique and declared with a compatible scalar type: numbers use INT or DOUBLE, booleans use BOOLEAN, and bit values use integers within their width (a width of 1 also accepts BOOLEAN). Payload keys unused by the encoder, duplicate JSON keys and unknown encoder keys are refused. An encoder requires a non-empty parameter schema. With an encoder, the parameter schema cannot declare fPort, hex, base64 or confirmed; the encoder controls the port and confirmation. Clearing encoder restores the raw contract. A definition without an encoder keeps the existing fPort plus hex or base64 contract unchanged.

What an integration token can do​

Treat the bearer token like a password for a whole fleet. An integration token speaks for every device of its scoped types that carries an alias for it. The platform checks that the token belongs to the integration and that the device's type is in the integration's scope, and it does so again when the event is processed, but it cannot tell whether the sender is honest about which device a message came from. Anyone who holds the token can submit readings as any aliased device in scope.

So:

  • Scope an integration to the device types it needs, and use one integration per network server or per fleet rather than one for everything.
  • Rotate the token if it may have been exposed, and when someone who knew it leaves.
  • The token is stored only as a keyed digest and is never shown again, by the console or by GraphQL. An administrator cannot read it back either.
  • Integration events are marked with the integration they came through, which a device cannot imitate: a device cannot send an event over MQTT or HTTP that claims to have come through an integration.
  • The Integrations page shows when a request last failed authentication, and flags a rejected token.

See the security model.

Not in v1​

  • Downlink to generic senders. The LoRaWAN downlink covers ChirpStack v4 and The Things Stack v3, with raw payloads or encoded typed parameters. Commands to any other integration device fail as described in Commands to integration devices.
  • Signed payloads. There is no HMAC or signature check on a request. The bearer token is the only credential, and the transport must be TLS.
  • Join, status and location messages. They are acknowledged and ignored.
  • Automatic device creation. An unknown identifier is listed, not created. You add the device yourself, from the list.
  • Decoding a generic binary body without a decoder. It is accepted and counted, not decoded, unless the device's type has a payload decoder.

Troubleshooting​

What you seeLikely cause
The sender reports 401The token is wrong or was rotated; the integration token in the URL does not match the integration the bearer token belongs to; or the tenant segment is wrong. The integration shows Rejected token.
The sender reports 403The integration is switched off (Accepting data).
The sender reports 415ChirpStack's payload encoding is Protobuf. Change it to JSON.
The sender reports 400Read the response body; it names the field. Common causes are a DevEUI that is not 16 hex digits, a deduplicationId that is not a UUID and a time more than 366 days old.
The sender reports 202 but nothing is storedThe device has no matching alias, or its type is outside the integration's scope: look under Unregistered devices seen. Or the uplink had nothing to store: look at the undecoded count. Or the tenant is over its allowance: see IntegrationShedAccepted.
Uplinks with nothing to read keeps growingThe device profile in the network server has no codec or payload formatter, or its output has only strings.
Values are stored with no unitNo metric is declared for that key on the device's profile. The key is the dot-joined path (battery.voltage).
A hosted network server cannot connectThe instance serves a self-signed certificate. Use a certificate from a public CA.
Every sender shares one rate limitThe proxies in front of event-sources are not trusted. See Client addresses and trusted proxies.