Message Queue Listener

Published on May 6, 2026
6 minute(s) read

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.

{
  "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 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.

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.
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.
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.
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.

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.

IBM MQ

Name	Required?	Description
No Auth Credentials Required	Yes	Indicates whether the connection requires a username and password.
Username	Yes, if available	The username of a user that has access to the queue manager.
Password	Yes, if available	The password of a user that has access to the queue manager.
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.
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.

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.
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.
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

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

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

Setting up a DLQ

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 when a malformed message can’t be consumed. 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. If you’re setting up a DLQ, make sure to set the DISCARD_MALFORMED_RESOURCES in your environment variable file to false.