All Collections
User Guides
UbiFunctions: Publish data to your UbiFunction using MQTT
UbiFunctions: Publish data to your UbiFunction using MQTT

An MQTT+UbiFunction gateway acting as a middleware between MQTT devices and Ubidots

Written by Sergio M
Updated over a week ago

This article is based on UbiFunction's official documentation, which can be found in our Dev Center.


  • Ubidots account: trial or licensed

  • At least one UbiFunction already created (NOTE: if you don’t have one yet, follow this article first)

Table of Contents

1. Introduction

MQTT + UbiFunctions allows you to publish data through an UbiFunction created in your account and make possible to integrate devices that transmit over this protocol but send JSON payload whose format is not compatible with our native MQTT broker or HTTP Data Ingestion API, or simply if additional data processing is required prior to being sent to Ubidots.

As UbiFunctions acts as a middleware here, only the MQTT Publish method is accepted. Accordingly, all subscriptions messages will be rejected.

Following are the MQTT settings needed to invoke an UbiFunction over the MQTT protocol:

MQTT Settinigs



Also found in some MQTT clients as:



1883 for plain MQTT.
8883 for MQTT over TLS.




Your account username


Valid Token from your Ubidots account.


Any random string. Preferably longer than 15 characters



Note: Some MQTT clients offer the possibility to connect using websockets (shown as "ws://" or "wss://"), this is not supported.

2. Topic structure

To trigger an UbiFunction through MQTT, the publication topic must follow the structure:

/prv/<username>/<function-label>, where,

  • <username> : Your Ubidots account username.

  • <function-label> : Name of the UbiFunction but all lowercase and spaces replaced by dashes.

The base topic corresponds to the UbiFunction HTTPS Endpoint URL's path, as seen in the image below:

Advanced: topics support additional levels, separated by forward slash ("/"), beyond the ones used to identify the UbiFunction within the account. The structure is:
/prv/<username>/<function-label>/<level-1>/···/<level-N>, where

  • <level-N> is any additional UTF-8 encoded string that you want to add to the topic

Topics have the below limitations:

  • Length: 1500 characters

  • Levels: 10

3. UbiFunction arguments

When triggering an UbiFunction through the MQTT protocol, you'll receive a JSON object in the args variable of the main function. The JSON will have this structure:

"topic": "<topic>",
"payload": "<payload>",
"from_client_id": "<client_id>",

Where the keys correspond as follows:



Value description



The multilevel publication topic



The payload sent by the device in the publication message.



The client ID used in the MQTT connection.

4. TLS Certificates

Ubidots supports SSL V1.1, TLS V1.2 and V1.3. You can download our root certificates in different formats:

  • PEM file: Certificate chain with two root certificates from our certificate authorities (CAs).

  • DER file: Same as the PEM file, with an alternative encoding.

  • CRT file: Same as the PEM file, with a different extension. Often referred to as .crt, .cert or .cer.

5. Examples

  • Port 1883:

mosquitto_pub \
-p 1883 \
-h \
-t "/prv/<username>/<function-name>" \
-m '{"token": "TOKEN", "device": "device-label", "variable-label": value}' \
-u "<username>" \
-P "TOKEN" \
-q 1 -d
  • Port 8883:

mosquitto_pub \
-p 8883 \
-h \
-t "/prv/<username>/<function-name>" \
-m '{"token": "TOKEN", "device": "device-label", "variable-label": value}' \
-u "<username>" \
-P "TOKEN" \
-q 1 -d \
--cafile /Users/user/Documents/Ubidots/roots.pem

Other users also found helpful:

Did this answer your question?