AWS SQS Integration

AWS SQS Integration connects ThingsBoard to an Amazon SQS queue. ThingsBoard polls the queue, and an uplink data converter transforms each message into device or asset data, including telemetry and attributes. The integration is uplink-only.

Use AWS SQS Integration when:

• Devices, AWS IoT rules, AWS Lambda functions, or backend services already send data to an SQS queue.
• The queue must buffer data while ThingsBoard is unavailable: messages wait in the queue until the integration reads them.
• One queue carries data for many devices: the converter resolves each device from the message body.

1. Receive data. A producer sends a message to the queue. The integration requests up to 10 messages at a time.
2. Decode the payload. The uplink converter receives the message body, identifies the device or asset, and extracts attributes and telemetry.
3. Process the message. ThingsBoard processes the converted data through the Rule Engine. If Allow create devices or assets is enabled, ThingsBoard creates an entity that does not exist yet.
4. Delete the message. The integration deletes each message from the queue after processing it.

To send data from ThingsBoard to an SQS queue, use the aws sqs rule node (see Send Data to AWS SQS).

• Access to ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters.
• An AWS account with permission to create SQS queues, IAM users, and IAM policies.

Create a queue and an IAM user whose access key the integration uses.

The SQS console shows only the queues of the selected Region. Check the Region in the top-right corner of the console before you start.

1. Open the Amazon SQS console, select a Region, for example eu-north-1, and click Create queue.
2. Select the queue Type. You cannot change it after the queue is created.
   • Standard — nearly unlimited throughput, at-least-once delivery, best-effort ordering.
   • FIFO — first-in-first-out order and exactly-once processing. The name must end with .fifo.
3. Enter a Name, for example ThingsBoard.
4. Optional: in Configuration, set Receive message wait time to 20 seconds. The default 0 makes every poll of an empty queue return at once; with 20, the poll waits for messages, which reduces the number of requests.
5. In Encryption, keep Server-side encryption enabled with Amazon SQS key (SSE-SQS).
6. Leave Access policy, Redrive allow policy, Dead-letter queue, and Tags at their defaults, and click Create queue.
7. On the queue page, copy the URL, for example https://sqs.eu-north-1.amazonaws.com/378560561651/ThingsBoard, and the ARN for the IAM policy.

Click Create queue Select the queue type and enter the name Set Receive message wait time to 20 seconds and keep the SSE-SQS encryption Keep the remaining sections at their defaults and click Create queue Copy the queue URL and ARN

The integration needs two actions on the queue: sqs:ReceiveMessage and sqs:DeleteMessage.

1. Create the user. In the AWS console, open IAM ⇾ IAM users and click Create user.

   • Specify user details — enter a name, for example thingsboard-sqs. Leave Provide user access to the AWS Management Console off: the integration needs only an access key.
   • Set permissions — select no group and no policy. The user gets only the policy from step 3.
   • Review and create — click Create user.
   Search for IAM and open Users. Click Create user. Enter the user name and leave console access off. Select no group and no policy. The permissions summary is empty. Click Create user.

2. The page of the new user opens. On the Permissions tab, click Add permissions ⇾ Create inline policy.

   Click Add permissions, then Create inline policy.

3. In the Policy editor, switch to JSON and replace the content with the policy below. Replace the queue ARN with the one you copied. Click Next, enter a Policy name, for example thingsboard-sqs-policy, and click Create policy.

   {
     "Version": "2012-10-17",
     "Statement": [
       {
         "Sid": "AllowThingsBoardSqsAccess",
         "Effect": "Allow",
         "Action": [
           "sqs:ReceiveMessage",
           "sqs:DeleteMessage"
         ],
         "Resource": "arn:aws:sqs:eu-north-1:378560561651:ThingsBoard"
       }
     ]
   }

   Paste the policy. The editor reports no errors or warnings. Name the policy and check that it covers SQS on your queue. The policy is created. Next, open the Security credentials tab and click Create access key.

4. Open the Security credentials tab and click Create access key. Select Application running outside AWS and click Next. AWS recommends temporary credentials instead; the integration needs an access key, so continue.

   Select Application running outside AWS.

5. Optionally, enter a Description tag value, for example ThingsBoard AWS SQS integration, and click Create access key.

   Optionally, describe the key.

6. On Retrieve access keys, copy the Access key and the Secret access key, or click Download .csv file. AWS shows the secret only once. Then click Done.

   Copy both keys or download the .csv file.

Create the uplink converter, assign it to a new AWS SQS integration, and send a test message.

The uplink converter receives each message body as a byte array, resolves the target device, and returns its telemetry and attributes. AWS SQS Integration uses the Generic converter: you write the decoder in TBEL or JavaScript. For converter types and the full decoder reference, see Uplink data converter.

SQS does not define a message format. This guide uses the sample message that the Test decoder function dialog provides by default:

{
    "deviceName": "Thermometer",
    "deviceType": "thermostat",
    "serialNumber": "SN-12345",
    "temperature": 25.5
}

1. Go to Integrations ⇾ Data converters and click + Add data converter ⇾ Create new converter.

2. Converter type — keep Uplink.

3. Integration type — select AWS SQS.

4. Name — enter a name, for example AWS SQS Uplink Converter.

5. Main decoding configuration — the editor opens with the default decoder below. Keep it for JSON messages: it takes the device name and type from deviceName and deviceType, stores serialNumber as an attribute, and stores the other fields as telemetry. The timestamp comes from ts (Unix milliseconds) or timestamp (ISO 8601); without them, the decoder uses the server time. The editor opens in TBEL; use the TBEL / JS toggle to switch to JavaScript.

   • TBEL (Recommended)
   • JavaScript

   // Decode an uplink message from a buffer
   // payload - array of bytes
   // metadata - key/value object
   
   /** Decoder **/
   
   // decode payload to JSON
   var data = decodeToJson(payload);
   
   // --- Device name and type ---
   var deviceName = data.deviceName != null ? data.deviceName : 'Unknown Device';
   var deviceType = data.deviceType != null ? data.deviceType : 'default';
   // var customerName = 'Customer C';
   // var groupName = 'thermostat devices';
   
   

   ▼Expand

   To adapt:

   • Device name in another field — replace data.deviceName, for example with data.id.
   • Other attributes — add keys to attributeKeyList, for example "firmwareVersion".
   • Assets instead of devices — uncomment assetName and assetType, and use them in the result instead of deviceName and deviceType.
   • Customer or group — uncomment customerName or groupName and add it to the result.

6. Click Test decoder function and check the result (see Test the Decoder).

7. Click Add. The converter appears in the list with type Uplink and integration type AWS SQS.

Decoder Inputs

The decoder signature is function decoder(payload, metadata): object | object[].

The message body must be JSON. A body that is a JSON-escaped string, for example "{\"temperature\":25.5}", is unescaped first. The integration parses the body before the decoder runs, so a body that is not JSON never reaches the decoder (see How the Integration Reads the Queue).

Built-in helpers:

For field renaming, nested values, and other scripting patterns, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. Payload content type is set to JSON, and the Payload already holds the sample message. Click Test. The Output panel shows:

{
  "deviceName": "Thermometer",
  "deviceType": "thermostat",
  "attributes": {
    "serialNumber": "SN-12345"
  },
  "telemetry": {
    "ts": 1792418627360,
    "values": {
      "temperature": 25.5
    }
  }
}

ts is the current time, because the payload has neither ts nor timestamp. Check that deviceName is set and telemetry.values holds the expected keys. If the output is empty or shows an error, fix the decoder and test again.

The wizard has no downlink step, because the integration only reads the queue.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select AWS SQS.
   • Name — keep the default AWS SQS integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first message.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose AWS SQS Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Connection:
   • SQS Queue URL — paste the queue URL.
   • Region — replace the default us-west-2 with the Region of the queue, for example eu-north-1.
   • AWS access key Id and AWS secret access key — paste the Access key and the Secret access key of the IAM user.
   • Leave Polling period in seconds at its default 5. See Connection Settings for details.
5. Click Add.

• Each poll requests up to 10 messages. While the queue returns messages, the integration polls again right away. After an empty response, it waits Polling period in seconds.
• A poll waits for messages as long as the queue’s Receive message wait time allows. With 0, it returns at once.
• The integration deletes every message it has received, even when the decoder fails. Failed messages are not retried and do not reach a dead-letter queue. The integration’s Events tab shows them with status ERROR.
• A body that is not JSON stops the processing of the current batch. The integration deletes that message and records an ERROR event with a JsonParseException; the messages after it in the batch are not processed and return to the queue after its Visibility timeout (30 seconds by default), then arrive with the next poll.

Send a message to the queue, then confirm that ThingsBoard decoded it and created the device.

Send this test message to the queue:

{
    "deviceName": "Thermometer",
    "deviceType": "thermostat",
    "serialNumber": "SN-12345",
    "temperature": 25.5
}

• SQS console
• AWS CLI

1. Open the queue in the Amazon SQS console and click Send and receive messages.
2. Paste the message into Message body.
3. Click Send message.

Click Send and receive messages. Paste the sample message and click Send message. The message is in the queue. The integration picks it up on the next poll.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. With Event type set to Debug, the message appears as an event of type Uplink with status OK. Click ⋅⋅⋅ in the Message column to see the message body.
• Converter events — open AWS SQS Uplink Converter in Integrations ⇾ Data converters and click the Events tab. Click ⋅⋅⋅ in a column to open it: In shows the message body, Out shows the decoded result with the serialNumber attribute and the temperature telemetry, and Metadata holds only integrationName, for example AWS SQS integration.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermometer with the thermostat profile. Open it and confirm serialNumber = SN-12345 on the Attributes tab (Client attributes scope) and temperature = 25.5 on the Latest telemetry tab.
• Queue — in the SQS console, Messages available returns to 0.

AWS SQS Integration has no downlink. To send data from ThingsBoard to SQS, add an aws sqs rule node to a rule chain. The node sends the message data as the SQS message body. On success, it adds messageId, requestId, messageBodyMd5, and, when the message has attributes, messageAttributesMd5 to the message metadata. On failure, it adds error. For all parameters, see the aws sqs node reference.

This section sends shared attribute updates of the device to a separate queue, ThingsBoard-downlink.

1. In the Amazon SQS console, create a Standard queue named ThingsBoard-downlink with the default settings, as in Create a Queue.
2. Copy its URL and ARN.
   Copy the URL and ARN of the queue.
3. Allow the IAM user to send to the queue. In IAM ⇾ IAM users, open thingsboard-sqs, select thingsboard-sqs-policy on the Permissions tab, click Edit, and add a second statement with your queue ARN:

   {
     "Sid": "AllowThingsBoardSqsPublish",
     "Effect": "Allow",
     "Action": "sqs:SendMessage",
     "Resource": "arn:aws:sqs:eu-north-1:378560561651:ThingsBoard-downlink"
   }

   Click Next, then Save changes.
   Add the sqs:SendMessage statement for the downlink queue. Check the permissions and click Save changes.

The rule chain sends each shared attribute update to the queue. An originator fields node adds the device name to the message metadata, and an aws sqs node sends the message data as the SQS message body with the device name as a message attribute.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Enrichment section, drag an originator fields node onto the canvas. Set:
   • Name — Add Device Name.
   • Originator fields mapping — Source field Name, Target key deviceName.
   • Add mapped originator fields to — Metadata.
   • Click Add.
3. From the External section, drag an aws sqs node onto the canvas. Set:
   • Name — Publish to SQS.
   • Queue type — Standard.
   • Queue URL pattern — the URL of ThingsBoard-downlink. The pattern also accepts ${metadataKey} and $[messageKey] placeholders.
   • Delay (seconds) — keep 0.
   • Message attributes — click Add mapping and set Name to deviceName and Value to ${deviceName}.
   • AWS Access Key ID and AWS Secret Access Key — the access key of thingsboard-sqs.
   • AWS Region — replace the default us-east-1 with the Region of the queue, for example eu-north-1.
   • Click Add.
4. Connect the nodes:
   • message type switch ⇾ Add Device Name with the Attributes Updated relation.
   • Add Device Name ⇾ Publish to SQS with the Success relation.
5. Click Apply changes.

Map the device name to the deviceName metadata key. Enter the URL of the downlink queue. Add the deviceName message attribute and enter the access key and Region. Attribute updates go through Add Device Name to Publish to SQS.

Message attribute names and values accept the same placeholders and are sent as attributes of type String. A placeholder whose key is not in the message is sent as written: without the originator fields node, the attribute value would be the text ${deviceName}.

1. Go to Devices & assets ⇾ Devices, select Thermometer, and open the Attributes tab.
2. Select Shared attributes and click +.
3. Set Key to temperatureUploadFrequency, Type to Integer, Value to 60, and click Add.

1. Open ThingsBoard-downlink in the Amazon SQS console and click Send and receive messages.
2. Under Receive messages, click Poll for messages. The sent message appears in the Messages list.
3. Click the message ID to open it:

   • Body — the data of the Rule Engine message:

     {"temperatureUploadFrequency":60}

   • Attributes — deviceName of type String with the value Thermometer.

   • Details — the Message ID. It matches messageId in the metadata that the aws sqs node adds on success.

4. Click Done.

Click Send and receive messages. Click Poll for messages. The message sent by ThingsBoard appears in the list. The body is the data of the Rule Engine message. The deviceName attribute holds the device name. The Details tab shows the message ID.

To read debug events, open the integration or converter, click Events, and select an event: In is the received data, Out is the converter result, and Error holds the error text.

• Integrations overview — how integrations, converters, uplinks, and downlinks fit together.
• Uplink data converter — decoder inputs, output format, and scripting patterns.
• aws sqs node — send Rule Engine messages to an SQS queue.
• originator fields node — add fields of the message originator, such as the device name, to the message or its metadata.
• message type switch node — route messages by type, for example attribute updates.
• AWS Kinesis Integration — read records from a Kinesis data stream.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• Short and long polling — how Receive message wait time affects polling.