Shift management using HAQM Pinpoint’s 2-way-SMS

Businesses with physical presence such as retail, restaurants and airlines need reliable solutions for shift management when demand fluctuates, employees call in sick, or other unforeseen circumstances arise. Their linear dependence on staff forces them to create overtime shifts as a way to cope with demand.

The overtime shift communication between the business and employees needs to be immediate and scalable. Employees in such industries might not have access to internet, which rules out communication channels like email and push notification. Furthermore once the employees receive the available shifts, they need an easy way to book them and if required request further support.

In these situations, businesses need communication methods that are accessible by any mobile device, available without internet connection, and allow for replies. SMS fills all of these requirements and more. This blog showcases how with HAQM Pinpoint SMS channel and other AWS services you can develop an application that communicates available shifts to employees who are interested while allowing them to book by replying.

The solution presented in this blog is for shift management but with small changes it can also communicate available appointments to customers / patients. An example of such use case can be found in health care, where there is a waiting list to see a doctor and patients might cancel the very last moment. The solution can communicate these available slots to all patients in the waiting list and allow them to book via SMS.

Architecture

The solution uses HAQM Pinpoint two way SMS, HAQM DynamoDB, AWS Lambda, HAQM Simple Notification Service (SNS) and HAQM Connect (optional). The next section dives deeper into the architecture diagram and logic flow.

shift_management_architecture

The operator adds an item to the Shift’s campaigns HAQM DynamoDB table. The item consists of a unique key that is used as the HAQM Pinpoint Campaign Id and an attribute Campaign Message, which is used as the SMS message text that the campaign recipients will receive. The Campaign Message needs to include all available shifts that the operator wants to notify the employees about.
1. Note: This can be done either from the AWS console or programmatically via API.
HAQM DynamoDB streams invokes an AWS Lambda function upon creation of a new HAQM DynamoDB item. The AWS Lambda function uses the HAQM DynamoDB data to create and execute an HAQM Pinpoint SMS Campaign based on an existing customer segment of employees who are interested in overtime shifts. The customer segment is a prerequisite and it includes SMS endpoints of the employees who are interested in receiving shift updates.
Employees who belong in that segment receive an SMS with the available shifts and they can reply to book the ones they are interested in.
Any inbound SMS is published on an HAQM SNS topic.
The 2 way SMS AWS Lambda function subscribes to the HAQM Simple Notification Service and processes all inbound SMS based on their message body.
The Shift’s status HAQM DynamoDB table stores the status of the shifts, which gets updated depending on the inbound SMS.
If the employee requires further assistance, they can trigger an HAQM Connect outbound call via SMS.

The diagram below illustrates the four possible messages an employee can send to the application. To safeguard the application from outsiders and bad actors, the 2 way SMS AWS Lambda function looks up if the senders mobile number is in an allow list. In this solution, the allow list is hardcoded as an AWS Lambda environment variable but it can be stored in a data base like HAQM DynamoDB.

shift management inbound-sms-business-logic

Solution implementation

Prerequisites

To deploy this solution, you must have the following:

An originating identity that supports 2 way SMS in the country you are planning to send SMS to – Supported countries and regions (SMS channel).
A mobile phone to send and receive SMS.
An AWS account.
An HAQM Pinpoint project – How to create an HAQM Pinpoint project.
An SMS customer segment – Download the example CSV, that contains one SMS endpoint. Replace the phone number (column C) with yours and import it to HAQM Pinpoint – How to import an HAQM Pinpoint segment.
Add your mobile number in the HAQM Pinpoint SMS sandbox – HAQM Pinpoint SMS sandbox.
An HAQM Connect instance, number & contact flow if you want your employees to be able to request an agent call back. Download the example Connect contact flow that you can import to your HAQM Connect instance.

Note: UK numbers with a +447 prefix are not allowed by default. Before you can dial these UK mobile numbers, you must submit a service quota increase request. For more information, see HAQM Connect Service Quotas in the HAQM Connect Administrator Guide.

Deploy the solution

Download the CloudFormation template and navigate to the AWS CloudFormation console in the AWS region you want to deploy the solution.
Select Create stack and With new resources. Choose Template is ready as Prerequisite – Prepare template and Upload a template file as Specify template. Upload the template downloaded in step 1.
Fill the AWS CloudFormation parameters as shown below:
1. ApprovedNumbers: The mobile numbers that are allowed to use this service. The format should be E164 and if there is more than one number separate them by comma e.g. +4457434243,+432434324.
2. OriginationNumber: The mobile number that you have in your HAQM Pinpoint account in E164 format e.g. +44384238975.
3. PinpointProjectId: The existing HAQM Pinpoint project Id.
4. SegmentId: The HAQM Pinpoint existing segment Id that you want to send the SMS notifications to.
5. ConnectEnable: Select YES if you already have an HAQM Connect instance with a Contact Flow and Queue. If you select NO ignore all the fields below, the solution will still be deployed but employees won’t be able to request a call back.
6. InstanceId: The HAQM Connect InstanceId. Follow this link to learn how to find your HAQM Connect InstanceId.
7. ContactFlowID: The HAQM Connect Contact Flow Id that you want this solution to use. Follow this link to learn how to find your HAQM Connect ContactFlow id.
8. QueueID: The HAQM Connect Queue Id. To obtain the HAQM Connect Queue Id navigate to your HAQM Connect instance > Routing > Queues and it should appear on the browser URL, see example: http://your-instance.awsapps.com/connect/queues/edit?id=0c7fed63-815b-4040-8dbc-255800fca6d7.
9. SourcePhoneNumber: The HAQM Connect number in E164 format that is connected to the Contact Flow provided in step 7.
Once the solution has been successfully deployed, navigate to the HAQM DynamoDB console and access the ShiftsStatus DynamoDB table. Each item created represents a shift and should have a unique shift_id that employees use to book the shifts, a column shift_status with value = available and a column shift_info where you can put additional information about the shift – see example below:
```
{
   "shift_id":{
      "S":"XYZ1234"
   },
   "shift_info":{
      "S":"15/08 5h nightshift"
   },
   "shift_status":{
      "S":"available"
   }
}
```
Navigate to HAQM Pinpoint console > SMS and voice > Phone numbers, select the phone number that you used as OriginationNumber for this solution and enable Two-way SMS. Under the Incoming messages destination section, select Choose an existing SNS topic and select the one containing the name TwoWaySMSSNSTopic.
Navigate to the HAQM DynamoDB console and access the ShiftsCampaignDynamoDB table. Each item you create represents an HAQM Pinpoint SMS campaign. Create an HAQM DynamoDB item and provide a unique campaign_id, which will be used as the HAQM Pinpoint Campaign name. Create a new attribute (string) with the name campaign_message and type all available shifts that you want to communicate via this campaign. It is important to include the shift id(s) for each of shifts you want your employees to be able to request – see example below.
- Note: By completing this step, you will trigger an HAQM Pinpoint SMS Campaign. You can access the campaign information and analytics from the HAQM Pinpoint console.

{
  "campaign_id": {
    "S": "campaign_id1"
  },
  "campaign_message": {
    "S": "15/08 5h nightshift XYZ123, 18/08 3h dayshift XYZ124"
  }
}

shift_campaign_dynamoDB

Testing the solution

Make sure you have created the shifts in the ShiftsStatusDynamoDB HAQM DynamoDB table.
To test the SMS Campaign, replicate step 6 under Deploy the solution section.
Reply to the SMS received with the options below:
1. Send a shift_id that doesn’t exist to receive an automatic response “This is not a valid shift code, please reply by typing REQUEST to view the available shifts”.
2. Send a valid & available shift_id to book the shift and then check the ShiftsStatusDynamoDB HAQM DynamoDB table, where the shift_status should change to taken and there should be a new column employee with the mobile number of the employee who has requested it.
3. Send REQUEST to receive all shifts with shift_status = available.
4. If you have deployed the solution along with HAQM Connect, send AGENT and await for the call.

Next steps

This solution can be extended to support SMS sending to multiple countries by acquiring the respective originating identities. Using HAQM Pinpoint phone number validate service API the application can identify the country for each recipient and choose the correct originating identity accordingly.

Depending your business requirements you might want to change the agent call back option to chat via SMS. You can extend this solution to connect the agent via SMS chat by following the steps in this blog.

Clean-up

To delete the solution, navigate to the AWS CloudFormation console and delete the stack deployed.

AWS Messaging & Targeting Blog