From 80b251229bb75977d990fb9a69a030ec85682011 Mon Sep 17 00:00:00 2001 From: Vaidehi Patel Date: Thu, 20 Aug 2026 14:56:49 -0500 Subject: [PATCH] added new pattern --- apigw-connect-push-notification/README.md | 157 ++++++++++++++++++ .../example-pattern.json | 68 ++++++++ apigw-connect-push-notification/template.yaml | 107 ++++++++++++ 3 files changed, 332 insertions(+) create mode 100644 apigw-connect-push-notification/README.md create mode 100644 apigw-connect-push-notification/example-pattern.json create mode 100644 apigw-connect-push-notification/template.yaml diff --git a/apigw-connect-push-notification/README.md b/apigw-connect-push-notification/README.md new file mode 100644 index 000000000..22dbeda2c --- /dev/null +++ b/apigw-connect-push-notification/README.md @@ -0,0 +1,157 @@ +# Amazon API Gateway integration with Amazon Connect Customer for Push Notification + +This pattern creates an Amazon API Gateway REST API that directly integrates with the Amazon Connect to invoke [CreateNotification](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateNotification.html) API. It uses API Gateway's native AWS service integration with VTL mapping templates to transform requests and responses. + +In-app notifications are on-screen alerts that appear in the Amazon Connect header. They provide a central way to communicate important information to users that are logged into Amazon Connect. + +Supported Use Cases +- System notifications such as availability impacts, failover events, policy changes, and critical feature updates. +- Custom organizational messages specified in API requests by your team for desired use cases, for example training reminders, schedule adherence alerts, and emergency notifications to your teams. + +Learn more about this pattern at Serverless Land Patterns: https://serverlessland.com/patterns/apigw-connect-notification + +Important: this application uses various AWS services and there are costs associated with these services after the Free Tier usage - please see the [AWS Pricing page](https://aws.amazon.com/pricing/) for details. You are responsible for any AWS costs incurred. No warranty is implied in this example. + +## Requirements + +- [Create an AWS account](https://portal.aws.amazon.com/gp/aws/developer/registration/index.html) if you do not already have one and log in. The IAM user that you use must have sufficient permissions to make necessary AWS service calls and manage AWS resources. +- [AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2.html) installed and configured +- [Git](https://git-scm.com/book/en/v2/Getting-Started-Installing-Git) installed +- [AWS Serverless Application Model](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-sam-cli-install.html) (AWS SAM) installed +- An [Amazon Connect instance](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-instances.html) already provisioned + +## Deployment Instructions + +1. Create a new directory, navigate to that directory in a terminal and clone the GitHub repository: + ``` + git clone https://github.com/aws-samples/serverless-patterns + ``` + +2. Change directory to the pattern directory: + ``` + cd apigw-connect-push-notification + ``` +3. From the command line, use AWS SAM to deploy the AWS resources for the pattern: + ``` + sam build + sam deploy --guided + ``` + +4. During the prompts: + - Enter a stack name + - Enter your preferred AWS Region + - Enter your Amazon Connect instance ID (found in the instance ARN: `arn:aws:connect:::instance/`) + - Allow SAM CLI to create IAM roles with the required permissions + +5. Note the outputs from the SAM deployment process. These contain the API endpoint URL needed for testing. + +## How it works + +``` +Client → API Gateway (REST) → Amazon Connect CreateNotification API → In-App Notification +``` + +1. A client sends a **POST** request to the API Gateway REST endpoint with a JSON body containing notification details. +2. API Gateway validates the request body against the OpenAPI schema. +3. A VTL **request mapping template** transforms the client payload into the format expected by the Connect `CreateNotification` API (which uses `PUT /notifications/{InstanceId}`). +4. API Gateway assumes an IAM role and directly calls the Connect API on the backend. +5. A VTL **response mapping template** transforms the Connect API response back to a clean client-facing JSON format. +6. Amazon Connect delivers the notification to the specified users' in-app notification panel. + + +## Testing + +### Using curl + +```bash +# Get the API endpoint from the stack outputs +API_ENDPOINT=$(aws cloudformation describe-stacks \ + --stack-name \ + --query 'Stacks[0].Outputs[?OutputKey==`NotificationApiEndpoint`].OutputValue' \ + --output text) + +# Send a HIGH priority notification to a specific agent +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "recipients": ["arn:aws:connect:::instance//agent/"], + "content": {"en_US": "Hello! This is a test notification from the serverless pattern."}, + "priority": "HIGH" + }' \ + "$API_ENDPOINT" +``` + +### Expected Response + +```json +{ + "message": "Notification created successfully", + "notificationId": "abc123-def456-...", + "notificationArn": "arn:aws:connect:::instance//notification/" +} +``` + +### Broadcast to All Users + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "recipients": ["arn:aws:connect:::instance/"], + "content": { + "en_US": "System maintenance scheduled for tonight at 11 PM EST.", + "es_ES": "Mantenimiento del sistema programado para esta noche a las 11 PM EST." + }, + "priority": "LOW" + }' \ + "$API_ENDPOINT" +``` + +### Full Payload Example (All Optional Fields) + +```bash +curl -X POST \ + -H "Content-Type: application/json" \ + -d '{ + "recipients": ["arn:aws:connect:us-east-1:123456789012:instance/abcd-1234/agent/agent-001"], + "content": { + "en_US": "Training session tomorrow at 2 PM. [Join here](https://example.com/training)", + "es_ES": "Sesión de capacitación mañana a las 2 PM. [Unirse aquí](https://example.com/training)" + }, + "priority": "HIGH", + "expiresAt": 1735689600, + "clientToken": "unique-idempotency-token-abc123", + "tags": {"team": "support", "category": "training"} + }' \ + "$API_ENDPOINT" +``` + +## Request Body Schema + +| Field | Type | Required | Description | +|-------|------|----------|-------------| +| `recipients` | string[] | Yes | User ARNs or instance ARN (max 200) | +| `content` | object | Yes | Map of locale → text (max 500 chars/locale) | +| `priority` | string | No | `HIGH` or `LOW` (default: LOW) | +| `expiresAt` | number | No | Unix timestamp for expiry (default: 1 week) | +| `clientToken` | string | No | Idempotency token (max 500 chars) | +| `tags` | object | No | Key-value tags for TBAC | + +## Cleanup + +```bash +sam delete --stack-name +``` + + +## Resources + +- [Amazon Connect Notifications - Admin Guide](https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-notifications.html) +- [CreateNotification API Reference](https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateNotification.html) +- [API Gateway AWS Service Integration](https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-aws-proxy.html) +- [VTL Mapping Template Reference](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html) + +---- +Copyright 2026 Amazon.com, Inc. or its affiliates. All Rights Reserved. + +SPDX-License-Identifier: MIT-0 diff --git a/apigw-connect-push-notification/example-pattern.json b/apigw-connect-push-notification/example-pattern.json new file mode 100644 index 000000000..a1faa4f0c --- /dev/null +++ b/apigw-connect-push-notification/example-pattern.json @@ -0,0 +1,68 @@ +{ + "title": "Amazon API Gateway REST API to Amazon Connect Push Notification", + "description": "Create an API Gateway REST API that sends in-app push notifications to Amazon Connect users via direct AWS service integration", + "language": "", + "level": "300", + "framework": "SAM", + "introBox": { + "headline": "How it works", + "text": [ + "This pattern creates an Amazon API Gateway REST API with a direct AWS service integration to Amazon Connect.", + "A POST request is transformed via VTL mapping templates and forwarded directly to the Connect CreateNotification API.", + "Using this Customers can send In-app notifications such as System notifications or custom organizational messages to Connnect Agents and Admins.", + "Notifications appear in the Amazon Connect workspace header for targeted users.", + "Supports localized content (11 locales), priority levels, TTL expiration, and tag-based access control." + ] + }, + "gitHub": { + "template": { + "repoURL": "https://github.com/aws-samples/serverless-patterns/tree/main/apigw-connect-notification", + "templateURL": "serverless-patterns/apigw-connect-notification", + "projectFolder": "apigw-connect-notification", + "templateFile": "template.yaml" + } + }, + "resources": { + "bullets": [ + { + "text": "Amazon Connect Notifications - Admin Guide", + "link": "https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-notifications.html" + }, + { + "text": "CreateNotification API Reference", + "link": "https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateNotification.html" + }, + { + "text": "API Gateway AWS Service Integration", + "link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/getting-started-aws-proxy.html" + }, + { + "text": "VTL Mapping Template Reference", + "link": "https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-mapping-template-reference.html" + } + ] + }, + "deploy": { + "text": [ + "sam build", + "sam deploy --guided" + ] + }, + "testing": { + "text": [ + "See the GitHub repo for detailed testing instructions." + ] + }, + "cleanup": { + "text": [ + "sam delete --stack-name " + ] + }, + "authors": [ + { + "name": "Vaidehi Patel", + "bio": "Solutions Architect at Amazon Web Services", + "linkedin": "https://www.linkedin.com/in/vaidehi-patel08/" + } + ] +} diff --git a/apigw-connect-push-notification/template.yaml b/apigw-connect-push-notification/template.yaml new file mode 100644 index 000000000..dd4cc2193 --- /dev/null +++ b/apigw-connect-push-notification/template.yaml @@ -0,0 +1,107 @@ +AWSTemplateFormatVersion: '2010-09-09' +Transform: AWS::Serverless-2016-10-31 +Description: An Amazon API Gateway REST API that integrates with Amazon Connect CreateNotification API. (tag:apigw-connect-notification) + +Parameters: + ConnectInstanceId: + Type: String + Description: The Amazon Connect instance ID (found in the instance ARN) + AllowedPattern: '[a-z0-9\-]+' + ConstraintDescription: Must be a valid Connect instance ID (lowercase alphanumeric and hyphens) + +Resources: + APIGatewayRole: + Type: 'AWS::IAM::Role' + Properties: + AssumeRolePolicyDocument: + Version: 2012-10-17 + Statement: + - Action: + - 'sts:AssumeRole' + Effect: Allow + Principal: + Service: + - apigateway.amazonaws.com + Policies: + - PolicyName: APIGatewayConnectPolicy + PolicyDocument: + Version: 2012-10-17 + Statement: + - Effect: Allow + Action: + - 'connect:CreateNotification' + Resource: + - !Sub 'arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}' + - !Sub 'arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}/*' + - !Sub 'arn:aws:connect:${AWS::Region}:${AWS::AccountId}:instance/${ConnectInstanceId}/notification/*' + + Api: + Type: 'AWS::ApiGateway::RestApi' + Properties: + Name: apigw-connect-notification + Description: Amazon Connect Notification integration REST API + + notifications: + Type: 'AWS::ApiGateway::Resource' + Properties: + RestApiId: !Ref Api + ParentId: !GetAtt Api.RootResourceId + PathPart: 'notifications' + + notificationsMethodPost: + Type: 'AWS::ApiGateway::Method' + Properties: + RestApiId: !Ref Api + ResourceId: !Ref notifications + HttpMethod: POST + ApiKeyRequired: false + AuthorizationType: NONE + Integration: + Type: AWS + Credentials: !GetAtt APIGatewayRole.Arn + IntegrationHttpMethod: PUT + # More info: https://docs.aws.amazon.com/connect/latest/APIReference/API_CreateNotification.html + Uri: !Sub 'arn:aws:apigateway:${AWS::Region}:connect:path/notifications/${ConnectInstanceId}' + PassthroughBehavior: WHEN_NO_TEMPLATES + RequestTemplates: + application/json: !Sub | + { + "Content": $input.json('$.content'), + "Recipients": $input.json('$.recipients') + #if($input.path('$.priority') != "") + ,"Priority": "$input.path('$.priority')" + #end + #if($input.path('$.expiresAt') != "") + ,"ExpiresAt": $input.path('$.expiresAt') + #end + #if($input.path('$.clientToken') != "") + ,"ClientToken": "$input.path('$.clientToken')" + #end + #if($input.path('$.tags') != "") + ,"Tags": $input.json('$.tags') + #end + } + IntegrationResponses: + - StatusCode: '200' + MethodResponses: + - StatusCode: '200' + + ApiDeployment: + Type: 'AWS::ApiGateway::Deployment' + DependsOn: + - notificationsMethodPost + Properties: + RestApiId: !Ref Api + StageName: 'prod' + +Outputs: + ApiRootUrl: + Description: Root Url of the API + Value: !Sub + - 'https://${ApiId}.execute-api.${AWS::Region}.${AWS::URLSuffix}/prod' + - ApiId: !Ref Api + NotificationEndpoint: + Description: POST endpoint for sending notifications + Value: !Sub + - 'https://${ApiId}.execute-api.${AWS::Region}.${AWS::URLSuffix}/prod/notifications' + - ApiId: !Ref Api