The "getMessagesFromMqApiSession" action retrieves undelivered messages from topics to which an MQ API client has subscribed. This action only applies to sessions created using the "createMqApiSession", and this is why the phrase "MqApi" is in the name of the action.

The MQ client is identified by the required "clientName" property. An MQ API session with that client identifier must already exist; otherwise, it returns an error. It also returns an error when the "clientName" is used by an MQTT connection.

Each time you call this action with the same "clientName", the server starts where it left off and delivers the next set of messages published to that client. It retrieves undelivered messages up to the number specified by "maxMessages". The message payload is encoded according to the "binaryFormat" property.

If you subscribe to multiple topics, the server returns messages from all of them. You can use the "topic" property to retrieve messages from only one of your subscribed topics. 

The typical pattern for using this action is to first call the "createMqApiSession" action to create a new session. Then, use the "subscribeToMq" action to subscribe to topics. You can then repeatedly call the "getMessagesFromMqApiSession" action to retrieve messages as clients publish them. 

An application can retrieve messages sent to a shared topic, which is a topic starting with $share/. A shared topic works differently from a normal topic because the server distributes each message to a different subscriber rather than sending each message to each subscriber. Each time a subscriber uses the "getMessagesFromMqApiSession" action to retrieve a message, the server removes the message from the queue and prevents that message from being sent to another subscriber. If the application encounters an error processing a message, it must publish the message back to the topic so it can be processed by another subscriber. 

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params": {
    "topic": "test/topic1",
    "clientName": "client1",
    "maxMessages": 100,
    "binaryFormat": "hex",
    "includeMessageMetadata": true,
    "includeMqttProperties": true,
    "includeTransformFields": true
  },
  "responseOptions": {
    "dataFormat": "arrays", 
    "numberFormat": "number",
    "binaryFormat": "base64",
    "variantFormat": "json"
  },
  "apiVersion": "1.0",
  "debug": "max",
  "requestId": "optionalUniqueRequestIdFromTheClient",
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier",
    "maxMessages": 100
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier"
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "api": "mq",
  "action": "getMessagesFromMqApiSession",
  "params":
  {
    "clientName": "required unique MQ API client identifier",
    "topicFilter": "topic#",
    "maxMessages": 100,
    "binaryFormat": "json",

    "includeMessageMetadata": true,
    "includeMqttProperties": true,
    "includeTransformFields": true
  },
  "authToken": "replaceWithAuthTokenFromCreateSession"
}

{
  "authToken": "gOS2OeL4HgtpLUSVqPwAvtDwWEqSfZIkcEKOie6DP0zgiOWZd8IOBLbQgv2fiRHm",
  "result": {
    "messages": []
  },
  "requestId": "00000004",
}