--- title: "MQTT Integrations" canonical: "https://help.scopious.co.nz/space/KB/258506757/MQTT%20Integrations" format: markdown --- Scopious provides an MQTT server to allow streaming device data. This section explains how to connect an MQTT client to our MQTT server and subscribe to uplinks. > Macro (toc) ## Who is it for? [MQTT](https://mqtt.org/) can be used to build integrations between Scopious and a platform of your choice by streaming received data packets using MQTT protocol. ## How does it work? All uplink packets are published to our MQTT server (broker). You must run a MQTT client that connects to this server and listens for published events on specific topics. For example, whenever an uplink is received, it is published to our MQTT server, allowing your MQTT client to process, store, and visualise the data on an external platform. ## Important Information > ℹ️ The MQTT server supports [MQTT Standard Version 3.1.1](https://docs.oasis-open.org/mqtt/mqtt/v3.1.1/os/mqtt-v3.1.1-os.pdf) only. > ℹ️ The MQTT server supports **QoS level 0** only (fire and forget). ## Create a MQTT Integration Creating a [MQTT](https://mqtt.org/) integration requires you to have an MQTT client available to connect to the MQTT server. To create a MQTT integration, follow the initial steps in [Create an integration](https://scopious.atlassian.net/wiki/spaces/KB/pages/75146635/Create+an+integration#Create-an-Integration), then do the following: 1. Select **MQTT** integration type. 2. Click **Create Device Pool Integration**. 3. You will be presented with the MQTT integration details below. Take a copy of the API Key as you will need to use it to configure your MQTT client to connect and subscribe to the MQTT server. 4. Once you have copied the API key, click the **I have copied the key** button. > ⚠️ Ensure you copy the API Key as it will not be visible again after you close this window. ![Create MQTT integration.gif](media://ba8be0e1-0b4b-47da-96f2-d6fa1a23b15d) ![image-20250221-024932.png](media://0187cabd-254d-4720-9696-6fca356706fa) ## Configure Your MQTT Client There are many available MQTT clients you can use to connect to our MQTT Server. As each client has varying configuration methods, configuring individual clients is out of scope of this guide. However, the following sections will help you regardless of whichever client you use. ### Security Considerations 1. Use the **Public TLS Address (port 8883)** instead of the non-TLS Public Address (port 8881). To use TLS, use the TTI Network Server Root CA file [here](https://scopious.atlassian.net/wiki/spaces/KB/pages/267878403/Files#TTI-Root-Certificate-File). > ⚠️ We strongly recommend using **TLS** to safeguard your information while in transit to your endpoint. Data packets are sent unencrypted, so TLS is needed to ensure secure transmission by encrypting the data while in transit, preventing interception and inspection by unauthorized parties. 2. Use the **Username** and **API Key** as the MQTT username and password. > ⚠️ Do not divulge the **API Key** to anyone as this secret is used to ensure only you can access your data on the MQTT server. > ⚠️ > ⚠️ If you suspect your API Key has been leaked, delete your existing MQTT integration and create a new one. > ℹ️ If you lose your **API Key** you will need to create a new MQTT integration to get a new API Key. If you do this, delete your old MQTT integration to prevent it from being used. ### Performance Considerations 1. The MQTT server supports **QoS level 0** only to provide best performance. > ℹ️ QoS level 0 means: > ℹ️ > ℹ️ - The message is sent only **once** without confirmation. > ℹ️ - There are no retries or acknowledgments (ACKs). ### MQTT Topics In order to subscribe to events from our MQTT server, you will need to decide which topics you want to subscribe to. In the examples below replace `` with the full **Username** displayed when the MQTT integration was created. The simplest (but most verbose) way is to subscribe to all topics. To receive all events from all devices: ``` v3//devices/# ``` You can subscribe to specific topics if you want to receive certain events only: | **Event** | **Topic** | | --- | --- | | Uplink | ``` v3//devices/+/up ``` | | Downlink Queued | ``` v3//devices/+/down/queued ``` | | Downlink Sent | ``` v3//devices/+/down/sent ``` | | Downlink Acknowledgement | ``` v3//devices/+/down/ack ``` | | Downlink Negative Acknowledgement | ``` v3//devices/+/down/nack ``` | | Downlink Failed | ``` v3//devices/+/down/failed ``` | | Join Requests | ``` v3//devices/+/join ``` | | Location Solved | ``` v3//devices/+/location/solved ``` | | Service Data | ``` v3//devices/+/service/data ``` | ## Data Packet Format Refer to [this guide](https://scopious.atlassian.net/wiki/spaces/KB/pages/263847944) for an example of a JSON data packet you can expect to receive.