RabbitMQ Integration

The RabbitMQ integration connects ThingsBoard to RabbitMQ message brokers. Use it to consume messages that producers — devices, IoT platforms, connectivity providers, or your own applications — publish to RabbitMQ queues and bring them into ThingsBoard as telemetry and attributes for monitoring and rule-based automation. The integration can also publish messages from ThingsBoard back to RabbitMQ through a downlink data converter.

For uplink, a producer publishes a message to a RabbitMQ exchange. RabbitMQ routes the message to a queue according to the exchange type, routing key, and queue bindings. The RabbitMQ Integration consumes messages from the configured queue, and the uplink converter transforms each message into the ThingsBoard data format. ThingsBoard then stores the telemetry and attributes and can automatically create the device on first contact.

For downlink, the Rule Engine sends a message to an Integration Downlink node associated with the RabbitMQ Integration. The downlink converter encodes the message, and the integration publishes it to a RabbitMQ exchange using the configured routing key. RabbitMQ then routes the message to the target queue, where an external application or service can consume it.

Before creating the integration, ensure:

• You have access to ThingsBoard PE or ThingsBoard Cloud with integration functionality enabled for your tenant.
• You have permissions to create integrations and data converters.
• You have a running RabbitMQ broker — either a local installation or a cloud-managed service such as CloudAMQP. If you do not have a broker yet, follow the Set Up RabbitMQ step below.
• A queue to consume from. The queue must exist on the broker before the integration is created.
• Credentials (username and password) with permission to read from the queue.

The steps below stand up a fully managed single-node broker on CloudAMQP with a free Little Lemur plan (100 queues, 1 million messages/month, 20 connections), which is enough to test the integration without installing anything locally. If you use a local installation or another managed provider (Amazon MQ, Aiven, or a self-hosted cluster), skip to Required Connection Details and obtain the values from your broker instead.

Create the RabbitMQ instance:

1. Sign in to CloudAMQP
2. On the Instances page, click + Create New Instance.
3. Step 1 of 4 — Plan: enter an instance name (e.g. ThingsBoard), keep the free Little Lemur plan selected, and click Select Region.
4. Step 2 of 4 — Region: choose a data center and a region close to your ThingsBoard deployment, then click Review. The wizard skips directly to the confirmation step — Configure applies only to paid, dedicated plans.
5. Step 4 of 4 — Confirm: review the summary and click Create instance.

For development and evaluation, a shared instance can be sufficient. For production workloads, choose a plan that meets your availability, throughput, and isolation requirements.

CloudAMQP Instances page — click + Create New Instance to start. Step 1 of 4 — Plan: name the instance and keep the free Little Lemur plan selected. Step 2 of 4 — Region: pick a data center and region close to your ThingsBoard deployment. Step 4 of 4 — Confirm: review the summary and click Create instance. The new instance appears in the Instances list once created.

After the instance is provisioned, open the instance and go to its Overview page.

CloudAMQP displays the connection information required by ThingsBoard. Copy these values — you will need them in the integration’s Connection step.

• Cluster (under General) — the DNS load-balanced hostname of the instance (e.g. hawk.rmq.cloudamqp.com). Use this as the integration Host — not the individual node listed under Hosts (hawk-01.rmq.cloudamqp.com);
• User & Vhost (under AMQP details) — default RabbitMQ username and virtual host — both are the same string;
• Password (under AMQP details) — click the eye icon to reveal it;
• URL (under AMQP details) — complete AMQP connection URI.

The full AMQP URL is shown for reference in the following form:

amqps://<username>:<password>@<host>/<vhost>

Create the queue from which ThingsBoard will consume messages.

1. On the CloudAMQP instance Overview page, click RabbitMQ Manager to open the RabbitMQ Management UI.
2. Go to Queues and Streams. In the Add a new queue panel, enter tb-uplink as the Name, keep Durability set to Durable, and click Add queue.
3. The tb-uplink queue appears in the list in the running state, ready to receive messages.

Instance Overview — click RabbitMQ Manager to open the Management UI. Queues and Streams — add queue tb-uplink with Durability set to Durable. Queue tb-uplink created and running — ready to receive messages.

Collect the values below before creating the ThingsBoard integration.

For the CloudAMQP setup used in this guide:

For CloudAMQP, the User & Vhost field represents both the default username and its virtual host.

RabbitMQ connections are scoped to a virtual host. The authenticated user must have permission to access the virtual host and the resources required by the integration.

CloudAMQP provides dedicated credentials for the instance, so use the User & Vhost and Password values from its Overview page.

For self-hosted RabbitMQ installations, do not use the default guest account for remote integration access. RabbitMQ restricts guest to loopback connections by default.

For connections over an untrusted network, use AMQP over TLS.

The conventional RabbitMQ ports are:

For the CloudAMQP setup in this guide, use the port specified by the provider for the AMQP endpoint.

To set up the RabbitMQ integration, first create an uplink data converter to process incoming messages, then create and configure the integration.

The uplink converter receives each consumed RabbitMQ message, decodes the message body, and returns a structured object that ThingsBoard uses to create or update a device and store its telemetry and attributes. For the full decoder function reference — all input parameters and output fields — see Uplink Data Converter.

RabbitMQ uses a generic uplink converter. These converters decode a JSON message received from a RabbitMQ queue and transform it into the ThingsBoard integration data format.

1. Go to Integrations ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.

In the Add data converter dialog:

3. Converter type — leave Uplink (selected by default).
4. Integration type — in the search field, enter RabbitMQ and select RabbitMQ from the list.
5. Name — enter a converter name, for example RabbitMQ Uplink Converter.
6. Main decoding configuration — a code editor with the function signature function decoder(payload, metadata) {. Paste the decoder function shown below. By default the editor opens in TBEL; use the TBEL / JS toggle (upper right) to switch languages.
7. Click Add.

// 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';

// 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';

Converter Input

ThingsBoard passes two variables to the decoder function:

JSON Payload Example

RabbitMQ does not impose an application-level schema on a message body. The body is stored as bytes and may contain JSON, plain text, binary data, or any other format selected by the producer. In this example, a device or intermediate service publishes a JSON telemetry message to a queue. Because field names, message structure, naming conventions, nesting, and serialization formats may vary between producers, update the decoder function to match the exact message format used by your system.

In this example, the device Sensor A1 publishes the following JSON message to the tb-uplink queue:

{
  "deviceName": "Sensor A1",
  "deviceType": "thermostat",
  "temperature": 23.5,
  "humidity": 60
}

The converter returns:

{
  "deviceName": "Sensor A1",
  "deviceType": "thermostat",
  "telemetry": {
    "ts": 1638876127000,
    "values": {
      "temperature": 23.5,
      "humidity": 60
    }
  }
}

In short:

• deviceName: the value of the deviceName field (falls back to Unknown Device if absent);
• deviceType: the value of the deviceType field (falls back to default);
• attributes: static device attributes plus the integrationName injected by the integration;
• telemetry: every remaining field mapped as a timestamped telemetry value. The timestamp comes from a ts (Unix ms) or timestamp (ISO 8601) field if present, otherwise the server receive time is used.

1. Go to Integrations ⇾ Integrations and click + Add integration.
2. Basic settings:
   • Set Integration type to RabbitMQ.
   • Enter a Name, or keep the default RabbitMQ integration.
   • Leave Enable integration and Allow create devices or assets on so the device can be created automatically on the first valid message.
   • Click Next.
3. Uplink data converter:
   • Click Select existing and choose the RabbitMQ Uplink Converter created in the previous step.
   • Alternatively, click Create new to define the decoder inline.
   • Click Next.
4. Downlink data converter:
   • Click Skip for now. Downlink can be configured later in this guide.
5. Connection:
   • Host — hostname of your RabbitMQ broker. On CloudAMQP use the Cluster value (e.g. hawk.rmq.cloudamqp.com), not an individual node from Hosts.
   • Port — 5672 for plain AMQP, 5671 for AMQP over TLS.
   • In the Queues section, set:
     • Name — the queue to consume from (e.g. tb-uplink). The integration consumes from this single queue.
     • Durable / Exclusive / Auto delete — match how the queue was declared. For the tb-uplink queue created above, set Durable on, Exclusive off, and Auto delete off.
   • Expand Advanced settings and fill in Username, Password, and Virtual host — see Required Connection Details for the values to use.
   Read more about each parameter in connection settings.
6. Check connection (optional): click Check connection to move to the final wizard step and verify the broker is reachable — a green Connected status confirms success.
7. Click Add.

Publish a test message to the queue the integration consumes from, then confirm it lands in ThingsBoard.

Publish the test message to the tb-uplink queue using any of the following methods.

• Management UI
• CloudAMQP HTTP API
• CLI (rabbitmqadmin)

1. Open the Management UI, go to Queues and Streams, and click the tb-uplink queue.
2. In the queue’s Publish message panel, paste the JSON payload into the Payload field. Leave Delivery mode, Headers, Properties, and Payload encoding at their defaults.
3. Click Publish message. A Message published. confirmation appears above the form.

{
  "deviceName": "Sensor A1",
  "deviceType": "thermostat",
  "temperature": 23.5,
  "humidity": 60
}

Queues and Streams — click the tb-uplink queue. Publish message — paste the JSON payload and click Publish message. A "Message published." banner confirms the message was delivered to the queue.

Go to Integrations ⇾ Integrations, open the RabbitMQ integration, and check the Events tab. Click … in the Message column to inspect the raw payload consumed from the queue.

Go to Integrations ⇾ Data converters, click the RabbitMQ Uplink Converter, and open its Events tab. Click … in the respective column to inspect each field:

• In — the raw payload passed to the converter.
• Out — the decoded result: deviceName, deviceType, and telemetry (temperature, humidity). If the decoder script also sets attributes (e.g. model, serialNumber), they appear here too.
• Metadata — integrationName injected by the integration.

Go to Devices & assets ⇾ Devices. The device Sensor A1 is automatically provisioned on the first message. Open it and check the Latest telemetry tab — temperature and humidity should reflect the published values.

To publish messages from ThingsBoard back to RabbitMQ, the integration uses its downlink converter together with an Integration Downlink node in the Rule Engine. The node forwards a message to the RabbitMQ Integration, the downlink converter encodes it, and the integration publishes it to the configured exchange with the Downlink topic as the routing key.

The steps below test downlink on the CloudAMQP setup: create a separate downlink queue, point the integration at it, wire an Integration Downlink node into the Root Rule Chain, then trigger it by updating a shared attribute on device Sensor A1 and confirm the message with the Management UI.

In the CloudAMQP Management UI, create a dedicated queue for outgoing messages:

1. Go to Queues and Streams and expand Add a new queue.
2. Keep Type as Default for virtual host and Durability as Durable.
3. Enter tb-downlink as the Name and click Add queue.

Add a new queue — enter tb-downlink as the Name, keep Durability set to Durable, and click Add queue. Both queues are now listed and running: tb-uplink for incoming messages and tb-downlink for outgoing commands.

The downlink converter encodes Rule Engine messages into AMQP payloads. Skip this step if the integration doesn’t need to publish downlink messages.

The output object must include:

• contentType — TEXT, JSON, or BINARY
• data — the message body to publish
• metadata — optional AMQP message headers as key-value pairs

1. Go to Integrations ⇾ Data converters.
2. Click + Add data converter ⇾ Create new converter.
3. Set Converter type to Downlink.
4. Select integration type from the dropdown — RabbitMQ.
5. Enter a converter name: RabbitMQ Downlink Converter.
6. Paste the encoder function from the tab below.
7. Click Add.

var result = {
  contentType: 'JSON',
  data: JSON.stringify(msg),
  metadata: {
    deviceName: metadata.deviceName
  }
};

return result;

var result = {
  contentType: 'JSON',
  data: JSON.stringify(msg),
  metadata: {
    deviceName: metadata.deviceName
  }
};

return result;

To adapt this converter:

• Specific fields only — replace JSON.stringify(msg) with a selective object to send only the relevant command fields.
• Binary payload — set contentType to BINARY and encode data accordingly.

1. Open the RabbitMQ integration and click the edit icon (pencil).
2. Attach RabbitMQ Downlink Converter as the downlink data converter.
3. Expand Advanced settings and set:
   • Downlink topic — tb-downlink (used as the routing key when publishing downlink messages).
   • Exchange name — leave empty to use the default exchange.
4. Click Apply changes.

Add and Configure the Integration Downlink node:

1. Go to Data processing ⇾ Rule chains and open the Root Rule Chain (the chain that processes your device’s messages).

2. In the node palette on the left, search for downlink, then drag the integration downlink node (under Action) onto the canvas. In the Add rule node dialog, set:

   Field	Value for this setup
   Name	To RabbitMQ Integration
   Integration	RabbitMQ integration

3. Click Add.
4. Connect the Message Type Switch node to the new node via the Attributes Updated relation.
5. Click Apply changes.

Trigger a downlink by adding a shared attribute to device Sensor A1:

1. Go to Devices & assets ⇾ Devices and open Sensor A1.
2. Navigate to the Attributes tab, switch to Shared attributes, and click +.
3. Enter key powerState and value on, then click Add.

Adding the attribute fires the rule chain, which forwards the message through the Integration Downlink node to the RabbitMQ integration. The downlink converter encodes the message and ThingsBoard publishes it to the tb-downlink queue via the default exchange.

In the Management UI at https://hawk.rmq.cloudamqp.com/, go to Queues and Streams and open the tb-downlink queue. Scroll to Get messages, set Ack mode to Nack message requeue true (peek without consuming), and click Get Message(s).

The result shows:

• Exchange — (AMQP default)
• Routing Key — tb-downlink
• Payload — the downlink converter output, e.g. {"powerState":"on"}

This section covers the most common problems encountered when setting up and running the RabbitMQ integration. Each entry describes the symptom, the most likely cause, and the steps to resolve it.

Integration Status Is Not Active

Messages Are Not Consumed

Message Consumed but Device Not Created

Downlink Not Published

How to Read Debug Events

1. Go to Integrations ⇾ Integrations, open RabbitMQ integration, and click the Events tab.
2. Click an event row to inspect:

• In — the raw payload received from RabbitMQ before processing.
• Out — what the converter returned: device name, attributes, and telemetry values passed to ThingsBoard.
• Error — error text and stack trace, if processing failed. Debug mode is active automatically for the first 15 minutes after an integration is created; afterwards only error events are retained. Re-enable it from the integration details page whenever you need to inspect raw input/output, and disable it once the issue is identified.

• Integrations Overview — how ThingsBoard connects to external platforms and how uplink/downlink flow works
• Uplink Data Converter — full decoder function reference: input parameters, output fields, and scripting patterns
• Downlink Data Converter — encoder function reference for publishing messages back to RabbitMQ
• RabbitMQ Rule Node — publish messages from the Rule Engine directly to a RabbitMQ exchange
• Remote Integration — run the integration outside the ThingsBoard server to reach a broker on a private network
• TBEL scripting reference — built-in functions and operators for writing converter scripts
• Rule Engine — how the rule chain routes messages to the Integration Downlink node