RabbitMQ Integration

RabbitMQ Integration connects ThingsBoard to a RabbitMQ broker over AMQP 0-9-1. It reads messages from one or more queues, and an uplink data converter transforms each message into device or asset data, including telemetry and attributes. ThingsBoard can also publish downlink messages to a RabbitMQ exchange.

Use RabbitMQ Integration when:

• Devices, gateways, or backend services already publish data to RabbitMQ.
• One queue carries data for many devices: the converter sets the target device for each message.
• An application must receive ThingsBoard data or commands from a RabbitMQ queue.

1. Receive data. A producer publishes a message to an exchange, which routes it to a queue. The integration polls the queue and acknowledges each message as soon as it reads it.
2. Decode the payload. The uplink converter 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 can create an entity that does not exist yet.
4. Send downlink data (optional). The Rule Engine passes a message to the integration. The downlink converter encodes it, and the integration publishes it to an exchange with the Downlink topic as the routing key.

• Access to ThingsBoard or ThingsBoard Cloud with integrations enabled for your tenant.
• Permission to create integrations and data converters, and to edit rule chains for downlink.
• A RabbitMQ broker that ThingsBoard reaches on a plain AMQP port, 5672 by default. The integration does not support AMQP over TLS. ThingsBoard Cloud accepts only a public broker address.
• A broker user with configure, read, and write permissions on the queue’s virtual host.

This guide uses a free CloudAMQP instance. With your own broker, create the queue and collect the same values.

1. Sign in to CloudAMQP.
2. On the Instances page, click + Create New Instance.
3. Plan — enter a name, for example ThingsBoard, keep the free Little Lemur plan, and click Select Region.
4. Region — choose a data center and a region close to your ThingsBoard server, then click Review. The free plan skips the Configure step.
5. Confirm — check the summary and click Create instance.

On the Instances page, click + Create New Instance. Plan — name the instance and keep the free Little Lemur plan. Region — pick a data center and a region close to your ThingsBoard server. Confirm — check the summary and click Create instance. The new instance appears in the Instances list.

Open the instance. Its Overview page shows the connection values:

1. On the CloudAMQP instance Overview page, click RabbitMQ Manager in the upper-left corner. The RabbitMQ Management UI opens in a new tab.
2. Go to Queues and Streams. Under Add a new queue, enter tb-uplink as the Name, keep Durability set to Durable, and click Add queue.
3. Check that tb-uplink appears in the list in the running state.

Click RabbitMQ Manager to open the management UI. Add the durable queue tb-uplink. The tb-uplink queue is running.

The integration also declares its queues when it starts, so it can create a missing queue itself. Create the queue in advance when producers publish before the integration connects: RabbitMQ drops messages routed to a queue that does not exist.

Create the uplink converter, assign it to a new RabbitMQ integration, and publish a test message.

The uplink converter reads the message body and maps it to ThingsBoard entities and data. RabbitMQ Integration uses the Generic converter: the decoder is a TBEL or JavaScript script. For converter types and the full decoder reference, see Uplink data converter.

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

2. Converter type — keep Uplink.

3. Integration type — select RabbitMQ.

4. Name — enter a name, for example RabbitMQ 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.
   • Plain-text payload — read it with decodeToString(payload) and parse the text instead of calling decodeToJson.

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

7. Click Add.

Decoder Inputs

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

Built-in helpers:

For field renaming, nested values, and non-JSON payloads, see Common scripting patterns.

Test the Decoder

Click Test decoder function below the editor. The dialog opens with Payload content type set to JSON and this sample payload:

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

Click Test. The Output panel shows:

{
  "deviceName": "Thermometer",
  "deviceType": "thermostat",
  "attributes": {
    "serialNumber": "SN-12345"
  },
  "telemetry": {
    "ts": 1791807972006,
    "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.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Integration type — select RabbitMQ.
   • Name — keep the default RabbitMQ integration or enter your own.
   • Enable integration and Allow create devices or assets — keep both on, so the device is created on its first uplink.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose RabbitMQ Uplink Converter.
   • Alternatively, click Create new to write a decoder here.
   • Click Next.
4. Downlink data converter:
   • Click Skip. Add a downlink converter later if you need to publish data to RabbitMQ.
5. Connection:
   • Host — enter the CloudAMQP Cluster hostname, for example hawk.rmq.cloudamqp.com.
   • Port — keep 5672.
   • Queue — set Name to tb-uplink. Turn Durable on, and turn Exclusive and Auto delete off, to match the queue you created.
   • Advanced settings — expand it and enter the Username, Password, and Virtual host from the instance Overview page (see Create a CloudAMQP Instance).
   • Leave the other parameters at their defaults. See Connection Settings for details.
6. Optionally, click Check connection. ThingsBoard connects to the broker and shows the result. The check covers the host, port, credentials, and virtual host, not the queue.
7. Click Add.

Advanced settings

After a network failure, the integration reconnects to the broker automatically.

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

• Management UI
• HTTP API

1. In the RabbitMQ management UI, go to Queues and Streams and click the tb-uplink queue.

2. Expand Publish message and paste the payload into Payload. Leave the other fields at their defaults.

   {
     "deviceName": "Thermometer-01",
     "deviceType": "thermostat",
     "temperature": 23.5,
     "humidity": 60
   }

3. Click Publish message. The page shows Message published.

Click the tb-uplink queue. Paste the payload and click Publish message. The broker confirms that the message was published.

• Integration events — go to Integrations ⇾ Integrations, open the integration, and click the Events tab. The uplink appears with status OK. Click ⋅⋅⋅ in the Message column to see the message body.
• Converter events — open RabbitMQ Uplink Converter in Integrations ⇾ Data converters and click the Events tab. In shows the message body, Out shows the decoded result, and Metadata shows the integration name.
• Device — go to Devices & assets ⇾ Devices. The integration has created Thermometer-01 with the thermostat profile. Open it and check temperature and humidity on the Latest telemetry tab.

ThingsBoard publishes a downlink when the Rule Engine routes a message to the integration — for example, after a shared attribute update. The integration publishes the encoder’s data to the Exchange name exchange with the Downlink topic as the routing key. With an empty Exchange name, the default exchange delivers the message to the queue whose name equals the Downlink topic.

The message carries no properties: no headers, no content type, and transient delivery. The integration ignores the encoder’s metadata.

The downlink converter turns a Rule Engine message into the published payload. For the full encoder reference, see Downlink data converter.

1. On the CloudAMQP instance Overview page, click RabbitMQ Manager in the upper-left corner. The RabbitMQ Management UI opens in a new tab.
2. Go to Queues and Streams and expand Add a new queue.
3. Enter tb-downlink as the Name, keep Durability set to Durable, and click Add queue.

Click RabbitMQ Manager to open the RabbitMQ Management UI. Add the durable queue tb-downlink. tb-uplink receives uplinks, and tb-downlink receives downlinks.

Add a downlink converter to the integration and set the Downlink topic, the queue that receives downlinks.

1. Open the integration in Integrations ⇾ Integrations and click Toggle edit mode (pencil icon).
2. In the Downlink data converter field, click Create new. The Downlink converter type and RabbitMQ integration type are preselected.
3. Enter a name, for example RabbitMQ Downlink Converter.
4. In Main encoding configuration, replace the default encoder with the encoder below.
5. To record downlink events, click the debug icon next to the name, select All messages, and click Apply.
6. Click Add.
7. Advanced settings — expand it and set the downlink queue:
   • Downlink topic — enter tb-downlink. The field is empty by default, and with an empty value RabbitMQ drops every downlink without an error.
   • Exchange name — leave empty.
8. Click Apply changes.

Encoder used in this guide (TBEL and JavaScript):

/** Encoder **/

// Publish the message data as is.
var result = {
    // Payload content type: JSON, TEXT, or BINARY (Base64).
    contentType: "JSON",
    data: JSON.stringify(msg),
    // The integration does not use the downlink metadata.
    metadata: {}
};

return result;

To adapt:

• Selected fields — build data from the fields you need, for example JSON.stringify({ interval: msg.temperatureUploadFrequency }).
• Binary payload — set contentType to BINARY and return the bytes in data as a Base64 string.
• Other message types — branch on msgType, for example RPC_CALL_FROM_SERVER_TO_DEVICE. See Rule Engine message types.

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain.
2. From the Action section, drag an integration downlink node onto the canvas.
3. Enter a Name (for example, Downlink to RabbitMQ), select your RabbitMQ integration, and click Add.
4. Connect the message type switch node to the integration downlink node with the Attributes Updated relation.
5. Click Apply changes.

1. Go to Devices & assets ⇾ Devices, select Thermometer-01, 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. ThingsBoard publishes the downlink.

• RabbitMQ — in the management UI, open the tb-downlink queue and expand Get messages. Set Ack Mode to Nack message requeue true, so the message stays in the queue, and click Get Message(s). The result shows Exchange (AMQP default), Routing Key tb-downlink, and Payload {"temperatureUploadFrequency":60}.
• Converter events — open the downlink converter’s Events tab. In shows the Rule Engine message, and Out shows the encoded payload.

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.
• Downlink data converter — encoder reference.
• RabbitMQ node — publish messages from the Rule Engine without an integration.
• Remote Integration — run the integration outside the ThingsBoard cluster.
• TBEL — built-in functions and syntax for converter scripts.
• RabbitMQ queues — queue properties, durability, and exclusivity.