API Gateway can send messages directly to SQS queues without needing a Lambda function as an intermediary.
Here’s a live example of an API Gateway method sending a message to an SQS queue.
First, let’s set up a simple SQS queue.
aws sqs create-queue --queue-name my-api-gateway-queue
This will output something like:
{
"QueueUrl": "https://sqs.us-east-1.amazonaws.com/123456789012/my-api-gateway-queue"
}
Make a note of that QueueUrl.
Now, let’s create an IAM role that API Gateway can assume. This role needs permission to send messages to SQS.
{
"Version": "2012-07-01",
"Statement": [
{
"Effect": "Allow",
"Action": "sqs:SendMessage",
"Resource": "arn:aws:sqs:us-east-1:123456789012:my-api-gateway-queue"
}
]
}
Attach this policy to a new IAM role. When creating the role, select "AWS service" as the trusted entity and choose "API Gateway" as the use case. You’ll need the ARN of this role for the next step.
Next, we’ll configure an API Gateway REST API. If you don’t have one, create a new one via the AWS console.
In your API Gateway console, select your API, then "Resources". Choose the resource and HTTP method (e.g., POST /items) you want to trigger the SQS message.
Under "Method Execution", click "Integration Request".
- Integration type: Select
AWS Service. - AWS Region: Choose the region where your SQS queue resides (e.g.,
us-east-1). - AWS Service: Select
Simple Queue Service (SQS). - HTTP method: Select
POST. - Action type: Select
Use path parameters for action. - Path override: Enter the SQS
QueueName(e.g.,my-api-gateway-queue). - Execution role: Enter the ARN of the IAM role you created earlier.
Now, the crucial part: mapping the request body to the SQS MessageBody. Click "Integration Response", then expand the 200 response. Click "Body Mapping Templates".
- Click "Add mapping template".
- Content-Type: Enter
application/json. - Template: Paste the following Velocity Template Language (VTL) snippet:
{
"MessageBody": "$input.json('$.payload')"
}
This VTL maps the JSON body of your incoming API Gateway request, specifically the field named payload, to the MessageBody parameter of the SQS SendMessage action. So, if you send a POST request to /items with a body like {"payload": "This is my message"}, the string "This is my message" will be sent as the SQS message.
Finally, deploy your API.
Now, if you send a POST request to your deployed API endpoint (e.g., POST /items with body {"payload": "Hello from API Gateway!"}), the message will appear in your my-api-gateway-queue in SQS.
You can verify this by checking your SQS queue:
aws sqs receive-message --queue-url https://sqs.us-east-1.amazonaws.com/123456789012/my-api-gateway-queue --max-number-of-messages 1
You should see a message with "Hello from API Gateway!" in the Body.
This integration bypasses the need for a Lambda function for simple message queuing tasks, reducing latency and operational overhead. API Gateway directly invokes the SQS SendMessage API action. The Action type and Path override in the Integration Request tell API Gateway which SQS API action to call and which queue to target. The Body Mapping Template is where you sculpt the data from the incoming HTTP request into the exact parameters required by the SQS API action.
What most people don’t realize is that you can also pass SQS-specific attributes directly from API Gateway. Within the Integration Request, under "Mapping Templates," you can create a more complex JSON structure for the MessageBody parameter if you need to include MessageAttributes or MessageGroupId for FIFO queues. For example, to add a custom attribute named Source with a value API-GW, your VTL would look like:
{
"MessageBody": "$input.json('$.payload')",
"MessageAttributes": {
"Source": {
"DataType": "String",
"StringValue": "API-GW"
}
}
}
This allows for richer message context without changing your backend SQS consumers.
The next step you’ll likely encounter is handling responses from SQS back to the client, which involves configuring the Integration Response and Method Response in API Gateway.