Skip to main content

"publishMessagesToMqtt"

Use the "publishMessagesToMqtt" action to publish messages to an MQTT topic from the specified client

This action publishes one or more messages to an MQTT topic from an MQTT client identified by the required "clientName" property. It does not disconnect an MQTT client. 

When you set the "binaryFormat" property to "utf8" or "JSON", the server automatically assigns the MQTT 5 Payload Format Indicator property to 1 to indicate that the message payload contains UTF-8-encoded characters, such as JSON.

Request examples

Maximal request

{
  "api": "mq",
  "action": "publishMessagesToMqtt",
  "params":
  {
    "clientName": "a unique MQTT client identifier",
    "topic": "some/topic/name",
    "messages": [
      { 
        "payload": "This is the message payload.",
        "binaryFormat": "utf8",
       
        "contentType": "IanaMediaType or a CustomType",
        "correlationData": "any JSON value up to 65500 bytes",
        "expirySeconds": 60,
        "retain": true,
        "responseTopic": "topic/name/for/subscriber/to/respond/to",
        "userProperties": [
          { 
            "key": "some key", 
            "value": "some value" 
          }
        ]
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Publish one message to topic1

{
  "api": "mq",
  "action": "publishMessagesToMQTT",
  "params":
  {
    "messages": [
      { 
        "clientName": "a unique MQTT client identifier",
        "topic": "topic1",
        "payload": "This is the message payload.",
        "binaryFormat": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Publish one message to table mqtt_msg_topic1

{
  "api": "mq",
  "action": "publishMessagesToMQTT",
  "params":
  {
    "messages": [
      { 
        "clientName": "a unique MQTT client identifier",
        "databaseName": "faircom",
        "ownerName": "admin",
        "tableName": "mqtt_msg_topic1",
        "payload": "This is the message payload.",
        "binaryFormat": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Response example

{
  "requestId": "clientRequestId",
  "result": {},
  "errorCode": 0,
  "errorMessage": "",
  "debugInfo": {}
}

Use the "publishMessagesToMqtt" action to publish messages to an MQTT topic from the specified client

publishMessagesToMqttpublish messages to mqttjsonActionJSON MQ message API

Params

Table 1. Params property summaries

Property

Description

Default

Type

Limits (inclusive)

binaryFormat

specifies how the "payload" property is encoded

"json"

enum

"base64"
"hex"
"byteArray"
"utf8"
"json"

clientName

specifies the unique name that identifies the client to the FairCom MQTT engine

""

string

0 to 65,550 bytes

contentType

specifies the IANA media or custom type

""

string

correlationData

can be used to set request-response messages

""

JSON

0 to 65,500 bytes

expirySeconds

specifies the number of seconds the message remains active before the server stops delivering it to MQTT 5 subscribers

null

integer

responseTopic

specifies the topic name for the response

""

string

retain

tells the MQTT broker to retain this message for automatically sending to new subscribers as the first message they receive

false

Boolean

true
false

userProperties

assigns key-value pairs to MQTT 5 messages

null

array



"binaryFormat"

The "binaryFormat" property specifies how the "payload" property is encoded. It also applies to the format of all binary fields of messages included in a response. 

It defaults to "json". When the MQTT payload is not JSON, the API returns the following error message: "MQTT payload cannot be encoded as JSON. Set binaryFormat to base64 or hex to retrieve the payload's binary value." 

Note

In other FairCom APIs, the default value of "binaryFormat" is "base64". In this API, it defaults to "json" because JSON is the most common payload in MQTT messages.

You may set "binaryFormat" to one of the following values:

  • "base64" tells the server you set the payload to a string containing a base64 encoded value.

  • "hex" tells the server you set the payload to a string containing a hexadecimal encoded value.

  • "byteArray" tells the server you set the payload to an array of integers. Each integer must be between 0 and 255, representing one byte in the payload.

  • "utf8" tells the server you set the payload to a string. The server reads the UTF-8 encoded bytes in the string and directly stores them in the payload without conversion. 

    • The value stored in the payload does not include the double quotes before and after the string. 

    • For example, "payload": "I am a string", is stored in the payload as I am a string. Notice how the server does not store the double quotes.

  • "json" tells the server you set the payload to a JSON value. A JSON value may be one of the following:

    • A JSON object assigned to the payload, such as "payload": { "am": "an object" }, causes the server to store the UTF-8 characters { "am": "an object" } in the payload. 

      • The server must store the exact highlighted text, including the curly braces. 

      • The server may alter the object's whitespace, such as {"am":"an object"}.

    • A JSON array assigned to the payload, such as "payload": [ "am", "array" ], causes the server to store the UTF-8 characters [ "am", "array" ] in the payload. 

      • The server must store the exact highlighted text, including the straight braces.

      • The server may alter the object's whitespace, such as ["am","array"].

    • A JSON string assigned to the payload, such as "payload": "I am a JSON string", causes the server to store the UTF-8 characters "I am a JSON string" in the payload. 

      • The server must store the exact highlighted text, including the double quotes because a JSON string type includes the double-quote characters before and after the string's value.

    • A JSON number assigned to the payload, such as "payload": -12.34, causes the server to store the UTF-8 characters -12.34 in the payload.

    • A JSON true assigned to the payload, such as "payload": true, causes the server to store the UTF-8 characters true in the payload.

    • A JSON false assigned to the payload, such as "payload": false, causes the server to store the UTF-8 characters false in the payload.

    • A JSON null assigned to the payload, such as "payload": null, causes the server to store the UTF-8 characters null in the payload.

"clientName"

The "clientName" property is an optional string of up to 65550 characters containing a client name that uniquely identifies the client to the FairCom MQTT engine. 

The MQTT protocol allows only one connection per client identifier because each connection is stateful. If another client with the same "clientName" is already connected, the MQTT broker disconnects the other client and vice-versa. 

The JSON MQ Message API behaves differently because it is stateless; it allows multiple processes to simultaneously use the same client identifier to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics.

"contentType"

The "contentType" property is an optional string typically set to an IANA media type or a custom type you define. It is used by MQTT 5.

"correlationData"

The "correlationData" property is an optional JSON value with a byte length of up to 65500 bytes. Set it to a useful value when using MQTT for request-response messages. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include this "correlationData" value (if any) to connect the response to the published message.

"expirySeconds"

The "expirySeconds" property is an optional number of seconds the message remains active before the server stops delivering it to MQTT 5 subscribers. If you set it to null, the message does not expire. MQTT 3 messages do not expire. The server persists all messages, and the "getMessagesFromMqttSession" action includes expired messages in its results. The caller can filter out expired messages by setting "includeExpiredMessages" to false when using the "subscribeToMqtt" action.

"responseTopic"

The "responseTopic" property is an optional string containing a topic name. When a published message has a "responseTopic", an MQTT 5 subscriber can send a message response to that topic, and the message will include the "correlationData" value (if any) to connect the response to the published message.

"retain"

The "retain" property is optional in the "publishMessagesToMQTT" action and defaults to false. When true, it tells the MQTT broker to retain this message for automatically sending to new subscribers as the first message they receive. When an action returns the "retain" property, it indicates the publisher published the message as a retained message.

"userProperties"

The "userProperties" property is optional in the "publishMessagesToMQTT" action and defaults to null. When present, it is an array of key-value objects. A key-value object contains a "key" property and a "value" property with string values. You can assign multiple key-value pairs to an MQTT 5 message; the server includes them in the messages it delivers to subscribers. The server may process specific key-value pairs as instructions that modify its behavior.

"userProperties": [
  {
    "key": "some key",
    "value": "some value"
  }
]