# AmazonSQS native integration

<!-- Version variant: sqs_5; default: [/transports/sqs/native-integration.md](/transports/sqs/native-integration.md) -->


This document describes how to consume messages from non-NServiceBus endpoints via Amazon SQS in integration scenarios.

> [!NOTE]
> To send messages to non-NServiceBus endpoints, configure the sender endpoint so that it does not wrap outgoing messages in a transport envelope. For more information refer to the [transport configuration options](configuration-options.md#do-not-wrap-message-payload-in-a-transport-envelope).

### Accessing the native Amazon SQS message

It is sometimes useful to access the native Amazon SQS message from behaviors and handlers. When a message is received, the transport adds the native message, an instance of [`Amazon.SQS.Model.Message`](https://docs.aws.amazon.com/sdkfornet/v3/apidocs/items/SQS/TMessage.html), to the message processing context. For example, the native message may be accessed from a [pipeline behavior](/nservicebus/pipeline/manipulate-with-behaviors.md):

<!-- snippet: sqs-access-to-native-message -->

```cs
class AccessToAmazonSqsNativeMessage : Behavior<IIncomingContext>
{
    public override Task Invoke(IIncomingContext context, Func<Task> next)
    {
        // get the native Amazon SQS message
        var message = context.Extensions.Get<Message>();

        //do something useful

        return next();
    }
}
```

<!-- endsnippet -->

### Message type detection

NServiceBus requires the [message type](/nservicebus/messaging/message-type-detection.md) to be available as part of the message metadata to process a message successfully

During message processing, the SQS transport inspects the native message attributes for an attribute with the name `NServiceBus.AmazonSQS.Headers`. This attribute's value should be a serialized `Dictionary<string, string>`. If the attribute is present, the message is treated as a native message, and the body is deserialized into the target type [inferred from the payload](/nservicebus/messaging/message-type-detection.md).

> [!NOTE]
> To represent an empty `NServiceBus.AmazonSQS.Headers` message attribute, the value should be `"{}"`

The native message body is loaded from the configured [S3 bucket](/transports/sqs/configuration-options.md#offload-large-messages-to-s3) when the `NServiceBus.AmazonSQS.Headers` attribute contains an entry with the key `S3BodyKey` and the value representing an S3 object key, including the [necessary prefix](/transports/sqs/configuration-options.md#offload-large-messages-to-s3-key-prefix) as configured by the receiving endpoint.

Whenever the native message needs to be copied for [moving messages to the error queue](/nservicebus/recoverability/index.md), [auditing](/nservicebus/operations/auditing.md) or [delayed retries](/nservicebus/recoverability/configure-delayed-retries.md) purposes, the native message is converted into the transport's internal structure. The collection from `NServiceBus.AmazonSQS.Headers` is moved from the native message attribute into the [headers collection](/nservicebus/messaging/headers.md). All other available message attributes from the original native message are copied over into the newly formed native message.


### Retrying failed messages

Native messages that failed processing can be retried using ServicePulse and ServiceControl but the native message attributes that might have been present in the original message are lost when the message is retried.