---
title: "Message Queue Listener"
slug: "message-queue-listener"
updated: 2026-03-04T05:30:06Z
published: 2026-03-04T05:30:06Z
canonical: "help.hyperscience.ai/message-queue-listener"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://help.hyperscience.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Message Queue Listener

With the Message Queue (MQ) Listener Input Block, you can configure connections to the following message queue types:

- ActiveMQ
- Amazon SQS
- IBM MQ
- RabbitMQ

To select the message queue type you want to use for a Message Queue Listener connection, click on its name in the **Message Queue Type** drop-down list at the top of the block’s settings.

If you would like to use a Message Queue Listener connection in a SaaS instance and your MQ service is not public, you should create a firewall pinhole for the connection. Contact your Hyperscience representative for more information.

## Sample use cases

- I send submission info from external systems to an Amazon SQS queue. I want to ingest this submission info into Hyperscience for processing.
- My customers will post relevant documents and metadata to my ActiveMQ queue. I want to then ingest these documents and metadata for processing into Hyperscience.

## Message format

A JSON object must be passed to the message queue in order for Hyperscience to read the appropriate input image files. It should have the same format as the request payload for the Submission Creation API endpoint, with one key difference: in the MQ message payload, the *files* element is an array of file URLs and does not contain individual *file_url* elements.

An example MQ message payload is shown below.

```json
{
  "flow_uuid": "a89d6440-a2c2-423b-8c95",
  "machine_only": "true",
  "files": [
    "s3://s3-bucket/input/demo-file.pdf",
    "https://example.com/files/demo-file.pdf",
    "ocs://2021",
    "gs://bucket/example.pdf",
    "abs://container-name/blob.pdf",
    "abs://container-name/blob.pdf?sas=secret-token"
  ]
}
```

For more information about the Submission Creation payload, see the [Submission Creation](https://docs.hyperscience.ai/v5/#submission-creation) section of our API documentation.

## Block settings table

In addition to the settings outlined below, you can also configure the settings described in [Universal Integration Block Settings](/v42/docs/universal-integration-block-settings).

### ActiveMQ

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| **Username** | Yes | The username of a user that has access to the message queue. |
| **Password** | Yes | The password of a user that has access to the message queue. To edit the password, click **Edit value**, modify the password, and then click **Done**. |
| **Queue Name** | Yes | The name of the message queue in ActiveMQ. |
| **Host Name** | Yes | The hostname of the system where the message queue is being run. |

### Amazon SQS

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| **AWS Region** | Yes | The AWS region of the source data. |
| **Access Key ID** | Yes, if **Use AWS EC2 Instance IAM Role Credentials** is not selected | The access key ID allows access to the message queue. This setting is only available if **Use AWS EC2 Instance IAM Role Credentials** is not selected. |
| **Secret Access Key** | Yes, if **Use AWS EC2 Instance IAM Role Credentials** is not selected | The secret access key allows access to the message queue. To edit the key, click **Edit value**, modify the key, and then click **Done**. This setting is only available if **Use AWS EC2 Instance IAM Role Credentials** is not selected. |
| **Queue URL** | Yes | The queue URL for sending messages. |
| **Use AWS EC2 Instance IAM Role Credentials** | Yes | If selected, credentials are obtained from the EC2 instance directly, and **Access Key ID** and **Secret Access Key** are not present. This option applies only to the following deployment types: - On-premise deployments - SaaS deployments where an IAM role has already been configured. For more information, see [IAM Roles for Input Blocks and Output Blocks](https://help.hyperscience.ai/deployment/docs/iam-roles-for-input-blocks-and-output-blocks). Selected by default. |

#### Additional configurations in AWS

These configurations need to be made via in the AWS interface.

**Permissions**

The following permissions should be granted:

- *sqs:ReceiveMessage*
- *sqs:GetQueueUrl*
- *sqs:DeleteMessage*
- *sqs:ChangeMessageVisibility*

**Visibility timeout**

To avoid duplicate processing, configure the queue's visibility timeout to at least 60 seconds. Doing so ensures that the timeout window is longer than the maximum 30-second response time from StrongDM (SDM) HTTP requests. Making the timeout window longer minimizes the possibility of duplicate processing due to a failure to acknowledge messages during the window.

For more information, see AWS's [Amazon SQS visibility timeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html).

#### Message size

Note that Amazon imposes certain limitations on the size of messages sent to Amazon SQS message queues as documented in their [Developer Guide](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html). At the time of writing this article, the maximum message size allowed is 256KB. Depending on the specifics of your use case, this limit may prevent you from using the Amazon SQS connection effectively.

### IBM MQ

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| **No Auth Credentials Required** | Yes | Indicates whether the connection requires a username and password. If selected, **Username** and **Password** are not present. |
| **Username** | Yes, if available | The username of a user that has access to the queue manager. This field is only available if **No Auth Credentials Required** is not selected. |
| **Password** | Yes, if available | The password of a user that has access to the queue manager. To edit the password, click **Edit value**, modify the password, and then click **Done**. This field is only available if **No Auth Credentials Required** is not selected. |
| **Queue Name** | Yes | The name of the message queue in IBM MQ. |
| **Host Name** | Yes | The hostname of the system where the message queue is being run. |
| **Port Number** | Yes | The port number the connection should use to access the queue manager. Defaults to 1414. |
| **Queue Manager** | Yes | The name of the message queue's queue manager in IBM MQ. |
| **Channel** | Yes | The queue manager's channel in IBM MQ. |
| **SSL Cipher Suite** | Yes, if you want to use an SSL connection | The CipherSuite connection should use to communicate with the queue manager. If you are not using an SSL connection to connect to the queue manager, select **None** in this field. |

### RabbitMQ

| **Name** | **Required?** | **Description** |
| --- | --- | --- |
| **Username** | Yes | The username of a user that has access to the message queue. |
| **Password** | Yes | The password of a user that has access to the message queue. To edit the password, click **Edit value**, modify the password, and then click **Done**. |
| **Queue Name** | Yes | The name of the message queue in RabbitMQ. |
| **Host Name** | Yes | The hostname of the system where the message queue is being run. |
| **Port Number** | Yes | The port number the connection should use to access the message queue. Defaults to 5672. |
| **Virtual Host** | No | The name of the virtual host where the message queue is being run. |
| **Connection Type** | Yes | Specify whether the connection is a TCP or SSL connection. |

## Setting up Message Queue Listener

All Message Queue Listener connections can be set up in Hyperscience, but Amazon SQS connections require additional configuration steps in AWS.

### Setting up a Message Queue Listener in Hyperscience

To set up any of the Message Queue Listener Input Blocks, follow these steps.

1. Log in to your Hyperscience instance.
2. Go to **Flows** and choose any flow.
3. Scroll to the start of the flow in the Flow Studio and click **Inputs**.
4. Click **Add** and select Message Queue Listener from the list.
5. Click the **Add Connection** button.
6. From the **Message Queue Type** drop-down menu, select your Message Queue Type and enter the Block settings described above.

If you are setting up an ActiveMQ, IBM MQ, or RabbitMQ connection, you do not need to complete any additional steps.

If you are setting up an Amazon SQS connection, you also need to complete the steps outlined in [Setting up an Amazon SQS connection in AWS](/v42/docs/message-queue-mq-listener#setting-up-an-amazon-sqs-connection-in-aws).

### Setting up an Amazon SQS connection in AWS

1. Navigate to your **Amazon Simple Queue Service**.
2. Choose or create the relevant input queue. The Amazon SQS connection supports Standard and FIFO Queues.
3. Grant the following permissions via the AWS Interface:
  - *sqs:ReceiveMessage*
  - *sqs:GetQueueUrl*
  - *sqs:DeleteMessage*
  - *sqs:ChangeMessageVisibility*

#### Message size

Note that Amazon imposes certain limitations on the size of messages sent to Amazon SQS message queues as documented in Amazon’s [Amazon SQS quotas](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-quotas.html). Depending on the specifics of your use case, this limit may prevent you from using the Amazon SQS connection effectively.

## Dead-letter queues

A dead-letter queue (DLQ) is a specialized message queue designed to temporarily hold messages that encounter processing errors within a software system. DLQs allow producer-consumer systems to operate without interruptions in cases when a malformed message can’t be consumed. The message is isolated into a different queue and is processed by a different system, reviewed manually, or both. In this way, setting up a DLQ prevents issues with blocked submission pipelines.

Hyperscience recommends setting the maximum number of retry attempts for a message to be between 3 and 5. When a message goes above this number of retry attempts, it should be redirected to the DLQ.

> [!NOTE]
> Use automated monitoring and altering on new items that enter the DLQ. If you’re not alerted, you won’t be aware of the issues related to messages that cannot be consumed, which may prevent submissions from entering the pipeline.

### Setting up DLQs

To set up a DLQ, see the instructions for the MQ listener you’re currently using:

- **SQS** — Amazon's [Configuring a dead-letter queue redrive](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-configure-dead-letter-queue-redrive.html)
- **IBM MQ** — IBM's [Dead-letter queues](https://www.ibm.com/docs/en/ibm-mq/7.5?topic=queue-defining-dead-letter)
- **ActiveMQ** — ActiveMQ's [Message Redelivery and DLQ Handling](https://activemq.apache.org/message-redelivery-and-dlq-handling)
- **RabbitMQ** — RabbitMQ's [Dead Letter Exchanges](https://www.rabbitmq.com/dlx.html)

If you’re setting up a DLQ, make sure to set the *DISCARD_MALFORMED_RESOURCES* “.env” file variable to *false.*