Creating an example messaging application - AWS SDK for JavaScript

The AWS SDK for JavaScript V3 API Reference Guide describes in detail all the API operations for the AWS SDK for JavaScript version 3 (V3).

Creating an example messaging application

You can create an AWS application that sends and retrieves messages by using the AWS SDK for JavaScript and Amazon Simple Queue Service (Amazon SQS). Messages are stored in a first in, first out (FIFO) queue that ensures that the order of the messages is consistent. For example, the first message that’s stored in the queue is the first message read from the queue.

Note

For more information about Amazon SQS, see What is Amazon Simple Queue Service?

In this tutorial, you create a Node.js application named AWS Messaging.

Cost to complete: The AWS services included in this document are included in the AWS Free Tier.

Note: Be sure to terminate all of the resources you create while going through this tutorial to ensure that you’re not charged.

Prerequisites

To set up and run this example, you must first complete these tasks:

  • Set up the project environment to run these Node TypeScript examples, and install the required AWS SDK for JavaScript and third-party modules. Follow the instructions on GitHub.

  • Create a shared configurations file with your user credentials. For more information about providing a shared credentials file, see Shared config and credentials files in the AWS SDKs and Tools Reference Guide.

Important

This example uses ECMAScript6 (ES6). This requires Node.js version 13.x or higher. To download and install the latest version of Node.js, see Node.js downloads..

However, if you prefer to use CommonJS syntax, please refer to JavaScript ES6/CommonJS syntax.

Create the AWS resources

This tutorial requires the following resources.

  • An unauthenticated IAM role with permissions for Amazon SQS.

  • A FIFO Amazon SQS Queue named Message.fifo - for information about creating a queue, see Creating an Amazon SQS queue.

You can create this resources manually, but we recommend provisioning these resources using the AWS CloudFormation (AWS CloudFormation) as described in this tutorial.

Note

The AWS CloudFormation is a software development framework that enables you to define cloud application resources. For more information, see the AWS CloudFormation User Guide.

Create the AWS resources using the AWS CloudFormation

AWS CloudFormation enables you to create and provision AWS infrastructure deployments predictably and repeatedly. For more information about AWS CloudFormation, see the AWS CloudFormation User Guide.

To create the AWS CloudFormation stack using the AWS CLI:

  1. Install and configure the AWS CLI following the instructions in the AWS CLI User Guide.

  2. Create a file named setup.yaml in the root directory of your project folder, and copy the content here on GitHub into it.

    Note

    The AWS CloudFormation template was generated using the AWS CDK available here on GitHub. For more information about the AWS CDK, see the AWS Cloud Development Kit (AWS CDK) Developer Guide.

  3. Run the following command from the command line, replacing STACK_NAME with a unique name for the stack.

    Important

    The stack name must be unique within an AWS Region and AWS account. You can specify up to 128 characters, and numbers and hyphens are allowed.

    aws cloudformation create-stack --stack-name STACK_NAME --template-body file://setup.yaml --capabilities CAPABILITY_IAM

    For more information on the create-stack command parameters, see the AWS CLI Command Reference guide, and the AWS CloudFormation User Guide.

    To view the resources created, open AWS CloudFormation in the AWS management console, choose the stack, and select the Resources tab.

Understand the AWS Messaging application

To send a message to a SQS queue, enter the message into the application and choose Send.

After the message is sent, the application displays the message.

You can choose Purge to purge the messages from the Amazon SQS queue. This results in an empty queue, and no messages are displayed in the application.

The following describes how the application handles a message:

  • The user selects their name and enters their message, and submits the message, which initiates the pushMessage function.

  • pushMessage retrieves the Amazon SQS Queue Url, and then sends a message with a unique message ID value (a GUID)the message text, and the user to the Amazon SQS Queue.

  • pushMessage retrieves the messages from the Amazon SQS Queue, extracts the user and message for each message, and displays the messages.

  • The user can purge the messages, which delete the messages from the Amazon SQS Queue and from the user interface.

Create the HTML page

Now you create the HTML files that are required for the application’s graphical user interface (GUI). Create a file named index.html. Copy and paste the code below in to index.html. This HTML references main.js. This is a bundled version of index.js, which includes the required AWS SDK for JavaScript modules.

<!doctype html> <html xmlns:th="http://www.thymeleaf.org" xmlns:sec="http://www.thymeleaf.org/thymeleaf-extras-springsecurity3" > <head> <meta charset="utf-8" /> <meta http-equiv="X-UA-Compatible" content="IE=edge" /> <meta name="viewport" content="width=device-width, initial-scale=1" /> <link rel="icon" href="./images/favicon.ico" /> <link rel="stylesheet" href="https://maxcdn.bootstrapcdn.com/bootstrap/3.3.7/css/bootstrap.min.css" /> <link rel="stylesheet" href="./css/styles.css" /> <script src="https://code.jquery.com/jquery-1.12.4.min.js"></script> <script src="https://code.jquery.com/ui/1.11.4/jquery-ui.min.js"></script> <script src="./js/main.js"></script> <style> .messageelement { margin: auto; border: 2px solid #dedede; background-color: #d7d1d0; border-radius: 5px; max-width: 800px; padding: 10px; margin: 10px 0; } .messageelement::after { content: ""; clear: both; display: table; } .messageelement img { float: left; max-width: 60px; width: 100%; margin-right: 20px; border-radius: 50%; } .messageelement img.right { float: right; margin-left: 20px; margin-right: 0; } </style> </head> <body> <div class="container"> <h2>AWS Sample Messaging Application</h2> <div id="messages"></div> <div class="input-group mb-3"> <div class="input-group-prepend"> <span class="input-group-text" id="basic-addon1">Sender:</span> </div> <select name="cars" id="username"> <option value="Scott">Brian</option> <option value="Tricia">Tricia</option> </select> </div> <div class="input-group"> <div class="input-group-prepend"> <span class="input-group-text">Message:</span> </div> <textarea class="form-control" id="textarea" aria-label="With textarea" ></textarea> <button type="button" onclick="pushMessage()" id="send" class="btn btn-success" > Send </button> <button type="button" onclick="purge()" id="refresh" class="btn btn-success" > Purge </button> </div> <!-- All of these child items are hidden and only displayed in a FancyBox ------------------------------------------------------> <div id="hide" style="display: none"> <div id="base" class="messageelement"> <img src="../public/images/av2.png" alt="Avatar" class="right" style="width: 100%" /> <p id="text">Excellent! So, what do you want to do today?</p> <span class="time-right">11:02</span> </div> </div> </div> </body> </html>

This code is also available here on GitHub.

Creating the browser script

In this topic, you create a the browser script for the app. When you have created the browser script, you bundle it into a file called main.js as described in Bundling the JavaScript.

Create a file named index.js. Copy and paste the code from here on GitHub into it.

This code is explained in the following sections:

Configuration

First, create a libs directory create the required Amazon SQS client object by creating a files named sqsClient.js. Replace REGION and IDENTITY_POOL_ID in each.

Note

Use the ID of the Amazon Cognito identity pool you created in Create the AWS resources .

import { CognitoIdentityClient } from "@aws-sdk/client-cognito-identity"; import { fromCognitoIdentityPool } from "@aws-sdk/credential-providers"; import {SQSClient} from "@aws-sdk/client-sqs"; const REGION = "REGION"; //e.g. "us-east-1" const IdentityPoolId = "IDENTITY_POOL_ID"; const sqsClient = new SQSClient({ region: REGION, credentials: fromCognitoIdentityPool({ client: new CognitoIdentityClient({ region: REGION }), identityPoolId: IdentityPoolId }), });

In the index.js, import the required AWS SDK for JavaScript modules and commands. Replace SQS_QUEUE_NAME with the name of the Amazon SQS Queue you created in the Create the AWS resources .

import { GetQueueUrlCommand, SendMessageCommand, ReceiveMessageCommand, PurgeQueueCommand, } from "@aws-sdk/client-sqs"; import { sqsClient } from "./libs/sqsClient.js"; const QueueName = "SQS_QUEUE_NAME"; // The Amazon SQS queue name, which must end in .fifo for this example.

populateChat

The populateChat function onload automatically retrieves the URL for the Amazon SQS Queue, and retrieves all messages in the queue, and displays them.

$(function () { populateChat(); }); const populateChat = async () => { try { // Set the Amazon SQS Queue parameters. const queueParams = { QueueName: QueueName, Attributes: { DelaySeconds: "60", MessageRetentionPeriod: "86400", }, }; // Get the Amazon SQS Queue URL. const data = await sqsClient.send(new GetQueueUrlCommand(queueParams)); console.log("Success. The URL of the SQS Queue is: ", data.QueueUrl); // Set the parameters for retrieving the messages in the Amazon SQS Queue. var getMessageParams = { QueueUrl: data.QueueUrl, MaxNumberOfMessages: 10, MessageAttributeNames: ["All"], VisibilityTimeout: 20, WaitTimeSeconds: 20, }; try { // Retrieve the messages from the Amazon SQS Queue. const data = await sqsClient.send( new ReceiveMessageCommand(getMessageParams) ); console.log("Successfully retrieved messages", data.Messages); // Loop through messages for user and message body. var i; for (i = 0; i < data.Messages.length; i++) { const name = data.Messages[i].MessageAttributes.Name.StringValue; const body = data.Messages[i].Body; // Create the HTML for the message. var userText = body + "<br><br><b>" + name; var myTextNode = $("#base").clone(); myTextNode.text(userText); var image_url; var n = name.localeCompare("Scott"); if (n == 0) image_url = "./images/av1.png"; else image_url = "./images/av2.png"; var images_div = '<img src="' + image_url + '" alt="Avatar" class="right" style=""width:100%;"">'; myTextNode.html(userText); myTextNode.append(images_div); // Add the message to the GUI. $("#messages").append(myTextNode); } } catch (err) { console.log("Error loading messages: ", err); } } catch (err) { console.log("Error retrieving SQS queue URL: ", err); } };

Push messages

The user selects their name and enters their message, and submits the message, which initiates the pushMessage function. pushMessage retrieves the Amazon SQS Queue Url, and then sends a message with a unique message ID value (a GUID) the message text, and the user to the Amazon SQS Queue. It then retrieves all the messages from the Amazon SQS Queue and displays them.

const pushMessage = async () => { // Get and convert user and message input. var user = $("#username").val(); var message = $("#textarea").val(); // Create random deduplication ID. var dt = new Date().getTime(); var uuid = "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, function ( c ) { var r = (dt + Math.random() * 16) % 16 | 0; dt = Math.floor(dt / 16); return (c == "x" ? r : (r & 0x3) | 0x8).toString(16); }); try { // Set the Amazon SQS Queue parameters. const queueParams = { QueueName: QueueName, Attributes: { DelaySeconds: "60", MessageRetentionPeriod: "86400", }, }; const data = await sqsClient.send(new GetQueueUrlCommand(queueParams)); console.log("Success. The URL of the SQS Queue is: ", data.QueueUrl); // Set the parameters for the message. var messageParams = { MessageAttributes: { Name: { DataType: "String", StringValue: user, }, }, MessageBody: message, MessageDeduplicationId: uuid, MessageGroupId: "GroupA", QueueUrl: data.QueueUrl, }; const result = await sqsClient.send(new SendMessageCommand(messageParams)); console.log("Success", result.MessageId); // Set the parameters for retrieving all messages in the SQS queue. var getMessageParams = { QueueUrl: data.QueueUrl, MaxNumberOfMessages: 10, MessageAttributeNames: ["All"], VisibilityTimeout: 20, WaitTimeSeconds: 20, }; // Retrieve messages from SQS Queue. const final = await sqsClient.send( new ReceiveMessageCommand(getMessageParams) ); console.log("Successfully retrieved", final.Messages); $("#messages").empty(); // Loop through messages for user and message body. var i; for (i = 0; i < final.Messages.length; i++) { const name = final.Messages[i].MessageAttributes.Name.StringValue; const body = final.Messages[i].Body; // Create the HTML for the message. var userText = body + "<br><br><b>" + name; var myTextNode = $("#base").clone(); myTextNode.text(userText); var image_url; var n = name.localeCompare("Scott"); if (n == 0) image_url = "./images/av1.png"; else image_url = "./images/av2.png"; var images_div = '<img src="' + image_url + '" alt="Avatar" class="right" style=""width:100%;"">'; myTextNode.html(userText); myTextNode.append(images_div); // Add the HTML to the GUI. $("#messages").append(myTextNode); } } catch (err) { console.log("Error", err); } }; // Make the function available to the browser window. window.pushMessage = pushMessage;

Purge messages

purge deletes the messages from the Amazon SQS Queue and from the user interface.

// Delete the message from the Amazon SQS queue. const purge = async () => { try { // Set the Amazon SQS Queue parameters. const queueParams = { QueueName: QueueName, Attributes: { DelaySeconds: "60", MessageRetentionPeriod: "86400", }, }; // Get the Amazon SQS Queue URL. const data = await sqsClient.send(new GetQueueUrlCommand(queueParams)); console.log("Success", data.QueueUrl); // Delete all the messages in the Amazon SQS Queue. const result = await sqsClient.send( new PurgeQueueCommand({ QueueUrl: data.QueueUrl }) ); // Delete all the messages from the GUI. $("#messages").empty(); console.log("Success. All messages deleted.", data); } catch (err) { console.log("Error", err); } }; // Make the function available to the browser window. window.purge = purge;

Bundling the JavaScript

This comlete browser script code is available here on GitHub..

Now use webpack to bundle the index.js and AWS SDK for JavaScript modules into a single file, main.js.

  1. If you haven't already, follow the Prerequisites for this example to install webpack.

    Note

    For information aboutwebpack, see Bundle applications with webpack.

  2. Run the the following in the command line to bundle the JavaScript for this example into a file called <index.js> :

    webpack index.js --mode development --target web --devtool false -o main.js

Next steps

Congratulations! You have created and deployed the AWS Messaging application that uses Amazon SQS. As stated at the beginning of this tutorial, be sure to terminate all of the resources you create while going through this tutorial to ensure that you’re no longer charged for them. You can do this by deleting the AWS CloudFormation stack you created in the Create the AWS resources topic of this tutorial, as follows:

  1. Open the AWS CloudFormation in the AWS management console.

  2. Open the Stacks page, and select the stack.

  3. Choose Delete.