Skip to main content

"publishMessagesToMq" (jsonAction)

Use the "publishMessagesToMq" action to publish messages to a topic from the specified client

This action publishes one or more messages to a topic. MQ API and MQTT clients can subscribe to a topic and receive these messages. The required "clientName" property identifies the MQ API session used to publish the messages. The FairCom server tracks session statistics so you can monitor the health of a client and its session, including the timestamp of the last published message, the publish rate, the topics the session publishes to, etc. 

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

Minimal

{
  "api":       "mq",
  "action":    "publishMessagesToMq",
  "params":    {
    "clientName": "client1",
    "topic":      "test/topic1",
    "messages":   [
      {
        "payload": "This is the message payload for the minimal example."
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Typical

{
  "api":       "mq",
  "action":    "publishMessagesToMq",
  "params":    {
    "clientName": "client1",
    "topic":      "test/topic1",
    "messages":   [
      {
        "payload":      "This is the first message payload for the typical example.",
        "binaryFormat": "utf8"
      },
      {
        "payload":      "This is the second message payload for the typical example.",
        "binaryFormat": "utf8"
      },
      {
        "payload":      "This is the third message payload for the typical example.",
        "binaryFormat": "utf8"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Maximal

{
  "apiVersion": "1.0",
  "api":        "mq",
  "action":     "publishMessagesToMq",
  "params":     {
    "clientName": "client1",
    "topic":      "test/topic1",
    "messages":   [
      {
        "payload":         "This is the message payload for the maximal example.",
        "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"
          }
        ]
      }
    ]
  },
  "authToken":  "replaceWithAuthTokenFromCreateSession",
  "requestId":  "optionalUniqueRequestIdFromTheClient",
  "debug":      "max"
}

Publish one message to topic1

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params":
  {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      { 
        "payload": "This is the message payload.",
        "binaryFormat": "utf8"       
      }
    ]
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

Publish one message to table mqtt_msg_test_topic1

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

Response example

{
  "result": {},
  "errorCode": 0,
  "errorMessage": "",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

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

publishMessagesToMqpublish messages to mqjsonActionMQ API

"params"

Table 1. Params property summaries

Property

Description

Default

Type

Limits (inclusive)

clientName

(optional) specifies the unique name that identifies the client to the FairCom MQ engine

""

string

0 to 65,550 bytes

messages

(optional) specifies the message to be published to MQ as well as information about the message

[]

array of objects

messages
.binaryFormat

(optional) specifies how the "payload" property is encoded

"json"

string

One of the following: "base64", "hex", or "byteArray".

messages
.contentType

(optional) specifies the IANA media or custom type

""

string

messages
.correlationData

(optional) can be used to set request-response messages

""

JSON

0 to 65,500 bytes

messages
.expirySeconds

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

null

integer

messages
.payload

specifies the action payload of the message

Required - No default value

string

messages
.responseTopic

(optional) specifies the topic name for the response

""

string

messages
.retain

(optional) tells the FairCom server to retain this message for automatically sending to new subscribers as the first message they receive

false

Boolean

true
false
messages
.userProperties

(optional) assigns key-value pairs to MQTT 5 messages

null

array

topic

(optional) specifies an MQTT topic

""

string



"binaryFormat"

Examples

"hex"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": "333231",
        "binaryFormat": "hex"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 321

"byteArray"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": [ 50, 51, 49 ],
        "binaryFormat": "byteArray"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 231

"base64"

Request

{
  "api": "mq",
  "action": "publishMessagesToMq",
  "params": {
    "clientName": "client1",
    "topic": "test/topic1",
    "messages": [
      {
        "payload": "MTIz",
        "binaryFormat": "base64"
      }
    ]
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

The MQTT payload will be 123

"clientName"

The "clientName" property is an optional string of up to 65,550 characters. It is the client identifier (or clientId) in the MQTT protocol. It uniquely identifies an MQ session, which contains information about a client's subscriptions, settings, and queue position of each topic to which the client is subscribed. The FairCom MQ engine stores this information and retrieves it when an MQTT or MQ API client connects.

Connection authorization is done using an account name with a password or a client certificate.

The "clientName" property does not authorize an MQTT or MQ API session. Another authentication technique authorizes the connection, such as an account name and password or a client certificate. Thus, any account may be used to authorize an MQ connection. Each account is assigned to roles that authorize access to specific topics, client names, actions, etc.

The MQ API allows multiple processes to simultaneously use the same client name to manage sessions, subscribe to topics, send messages to topics, and retrieve messages from topics. 

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 FairCom server disconnects the other client and vice-versa.

"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 "getMessagesFromMqApiSession" action includes expired messages in its results. The caller can filter out expired messages by setting "includeExpiredMessages" to false when using the "subscribeToMq" action.

"messages"

The "messages" property is a required array of objects that specifies the message to be published to MQ as well as information about the message.

"payload"

The "payload" property is required. It can be any JSON value, including binary values embedded in a JSON string or array. It contains the payload of the message.

"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 "publishMessagesToMq" action and defaults to false. When true, it tells the FairCom server 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.

"topic"

The "topic" property is a required, case-sensitive UTF-8 string containing the name of a topic. It must not contain MQTT wildcard characters, #, or +. It may contain multiple / characters, which segment a topic into a set of positional properties.

"userProperties"

The "userProperties" property is optional in the "publishMessagesToMq" 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"
  }
]
Would you like to provide feedback?