Publish data to a function

UbiFunctions can be invoked by publishing data over the MQTT protocol. This allows devices and gateways to send data to a Function even when:

Their JSON payload format cannot be modified,
Their payload is not compatible with Ubidots’ standard MQTT broker, or
They cannot perform HTTP requests.

When you publish to the Function’s MQTT topic, Ubidots automatically triggers your UbiFunction and forwards the incoming payload to it.

🚧
Important

The MQTT broker used by UbiFunctions only supports publish operations. Any MQTT subscriptions will be rejected.

For cases where you need both publish and subscribe, a private dedicated MQTT broker can be mapped to your Function. Contact the Ubidots Sales team for more information.

MQTT Connection Settings

Use the settings below to publish to a Function using MQTT:

Field	Value	Required
Host	`functions.ubidots.com`	Yes
Port	`1883` for MQTT without TL, `8883` for MQTT over TLS	Yes
Topic	`/prv/<username>/<function-label>`	Yes
Username	Your Ubidots account username	Yes
Password	Any valid Ubidots Token	Yes
Client ID	Any unique string (recommended: 15+ characters)	Yes
Quality of Service	0 or 1	Yes

Your UbiFunction’s method must be set to POST.

Topic Structure

To trigger a Function using MQTT, publish to:

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

Where:

<username> is your Ubidots account username.
<function-label> is the Function’s Name, converted to:
- lowercase,
- spaces replaced by hyphens.

For example, a Function named Process Report becomes:

/prv/acme-corp/process-report

This topic matches the path of the Function’s HTTPS endpoint.

Advanced Topic Levels

You may add additional topic levels if needed:

/prv/<username>/<function-label>/<level-1>/<level-2>/.../<level-N>

Each additional level can be any UTF-8 string, up to:

Limit	Value
Maximum topic length	1500 characters
Maximum levels	10

These additional levels do not affect Function execution and are optional.

Payload Handling Inside the Function

When the Function is triggered via MQTT, Ubidots passes a JSON object into the Function’s args parameter with the following structure:

{
  "topic": "<full-mqtt-topic>",
  "payload": "<raw-payload-string>",
  "from_client_id": "<mqtt-client-id>"
}

Where:

Key	Description
topic	The full topic string used for the publish.
payload	The raw payload sent by the device. This is not modified by Ubidots.
from_client_id	The ClientID used in the MQTT session.

Your Function code can parse and process args.payload as needed.

Certificates (TLS)

For secure TLS connections (port 8883), Ubidots accepts:

SSL 1.1
TLS 1.2
TLS 1.3

Available certificate formats:

PEM – Full chain with both CAs
DER – Same as PEM but alternate encoding
CRT – Same content, different extension (.crt, .cert, .cer)

These can be downloaded from the Ubidots Documentation.

Examples

Publish to a Function (Port 1883 – No TLS)

mosquitto_pub \
  -p 1883 \
  -h functions.ubidots.com \
  -t "/prv/<username>/<function-label>" \
  -m '{"temperature": 25, "status": "ok"}' \
  -u "<username>" \
  -P "YOUR_TOKEN" \
  -q 1

Publish to a Function (Port 8883 – TLS)

mosquitto_pub \
  -p 8883 \
  --tls-version tlsv1.2 \
  --cafile /path/to/ubidots-ca.pem \
  -h functions.ubidots.com \
  -t "/prv/<username>/<function-label>" \
  -m '{"humidity": 80, "message": "from-device"}' \
  -u "<username>" \
  -P "YOUR_TOKEN" \
  -q 1