Mastering SQS Configuration in Ballerina: Message-Level Parameters Explained

This article is written using Ballerina Swan Lake 2201.12.0.

In Part 1 of this guide, we explored how to configure Amazon SQS queues using the Ballerina AWS SQS connector. Now that you’re familiar with queue-level settings, it’s time to fine-tune the behavior of individual messages.

Message-level configuration gives you granular control over how each message is sent and received. You can override queue defaults, attach custom metadata, define message grouping for FIFO queues, and even enable distributed tracing.

In this article, we’ll walk through every parameter in the SendMessageConfig and ReceiveMessageConfig records in Ballerina.

Message Sending Configuration (SendMessageConfig)

1. delaySeconds: Per-Message Delivery Delay

Overrides the default queue delay for this specific message. Prioritize some messages for immediate delivery while delaying others.

sqs:SendMessageConfig delayConfig = {
    delaySeconds: 300  // Delay this message for 5 minutes
};
check sqsClient->sendMessage(queueUrl, "Delayed notification", delayConfig);

2. messageAttributes: Custom Metadata for Routing or Processing

Attach structured metadata to a message. These attributes help consumers make decisions without parsing the payload.

Supported Types:

• String
• Number (stored as a string)
• Binary (byte array)

sqs:SendMessageConfig attributedMessage = {
    messageAttributes: {
        "Type": {
            dataType: "String",
            stringValue: "OrderCreated"
        },
        "Priority": {
            dataType: "Number",
            stringValue: "5"
        }
    }
};
check sqsClient->sendMessage(queueUrl, "Order details", attributedMessage);

3. messageGroupId: Grouping for FIFO Ordering

FIFO queues require a messageGroupId. Messages with the same group ID are processed in strict order.

sqs:SendMessageConfig grouped = {
    messageGroupId: "user-123"
};

check sqsClient->sendMessage(fifoQueueUrl, "User login", grouped);
check sqsClient->sendMessage(fifoQueueUrl, "User logout", grouped);

Note: Messages with different group IDs can be processed in parallel.

4. messageDeduplicationId: Prevent Duplicate Deliveries

Required for FIFO queues when contentBasedDeduplication is disabled. Ensures that duplicate messages (within 5 minutes) are discarded.

sqs:SendMessageConfig dedup = {
    messageGroupId: "order-456",
    messageDeduplicationId: "txn-789"
};
check sqsClient->sendMessage(fifoQueueUrl, "Payment received", dedup);

5. awsTraceHeader: Distributed Tracing with AWS X-Ray

Enables tracing across distributed systems.

sqs:SendMessageConfig traceEnabled = {
    awsTraceHeader: "Root=1-67890-abcdef1234567890abcdef;Sampled=1"
};
check sqsClient->sendMessage(queueUrl, "Traced message", traceEnabled);

Message Receiving Configuration (ReceiveMessageConfig)

1. waitTimeSeconds: Long Polling for Individual Receive Calls

Overrides the queue’s default long polling setting for this specific call.

sqs:ReceiveMessageConfig longPoll = {
    waitTimeSeconds: 20
};
sqs:Message[] messages = check sqsClient->receiveMessage(queueUrl, longPoll);

2. maxNumberOfMessages: Batch Size per Call

Controls how many messages to retrieve in a single API call. Best practise is to use batching to reduce API calls and improve throughput.

sqs:ReceiveMessageConfig batch = {
    maxNumberOfMessages: 10
};
sqs:Message[] messages = check sqsClient->receiveMessage(queueUrl, batch);

3. [visibilityTimeout](https://docs.aws.amazon.com/AWSSimpleQueueService/latest/SQSDeveloperGuide/sqs-visibility-timeout.html): Per-Message Visibility Window

Temporarily hides a message from other consumers after it is retrieved.

sqs:ReceiveMessageConfig extendedTimeout = {
    visibilityTimeout: 900  // 15 minutes
};

4. messageAttributeNames: Include Custom Attributes in Response

Specify which custom attributes to return with the message.

sqs:ReceiveMessageConfig specificAttrs = {
    messageAttributeNames: ["Type", "Priority"]
};
sqs:Message[] messages = check sqsClient->receiveMessage(queueUrl, specificAttrs);

5. receiveRequestAttemptId: FIFO Receive Deduplication Token

Used only with FIFO queues, this ensures that repeated receiveMessage requests within a 5-minute window (with the same token) return the same set of messages. Useful for avoiding duplicate processing in distributed consumers.

sqs:ReceiveMessageConfig dedupReceive = {
    receiveRequestAttemptId: "attempt-001",
    maxNumberOfMessages: 5
};
sqs:Message[] messages = check sqsClient->receiveMessage(fifoQueueUrl, dedupReceive);

6. messageSystemAttributeNames: Request System Metadata

Request AWS-managed attributes such as timestamps, sender ID, or receive count.

sqs:ReceiveMessageConfig systemAttrs = {
    messageSystemAttributeNames: [SENDER_ID, SENT_TIMESTAMP]
};
sqs:Message[] messages = check sqsClient->receiveMessage(queueUrl, systemAttrs);

Summary Table: Message-Level Parameter Reference

Amazon SQS gives you remarkable control over message delivery behavior not only at the queue level, but also per message. With the Ballerina AWS SQS connector, you can use all of these options using a clean and concise syntax.

In upcoming articles, we’ll bring these concepts together through examples. Refer to the following for practical implementations.

👉 Amazon SQS Examples Using the Ballerina Language (Part 1) 👉 Amazon SQS Examples Using the Ballerina Language (Part 2)

Stay tuned, and happy queuing with Ballerina!