How to programmatically access Amazon Connect Rules using APIs

Many businesses today use Amazon Connect Rules, a feature of Contact Lens for Amazon Connect, through Amazon Connect console for creating and managing rules. This restricts businesses who want to manage the automation of rules creation and management from any home-grown or third-party solution outside of the Amazon Connect console. Amazon Connect Rules now launched APIs that enable businesses to programmatically manage rules for Contact Lens and third-party applications in an Amazon Connect instance. Using the rules APIs, you can now create new rules, search for specific rules, and update or delete an existing rule from any home-grown or third-party solution without requiring to use the Amazon Connect console. For example, you can now use the CreateRule API to configure new rules for Contact Lens that can automatically alert supervisors about customer issues (e.g. “alert supervisor of an agent when customer sentiment turned negative”). Additionally, rules APIs now also comes with support for AWS CloudFormation.

With Amazon Connect Rules, contact center managers, supervisors, and quality analysts can automatically categorize contacts, send email notifications or dashboard alerts about customer escalations, prompt tips in agent desktop, and assign tasks for different roles in a contact center. These actions are automated based on conditions that businesses can define such as keywords used on a contact, sentiment trend of a contact, frequent interruptions by agent, agents being silent for long-periods, filtering specific contact attributes or queues, and many more. Rules also provides third-party integrations with leading CRM vendors such as Salesforce and Zendesk that allows you to trigger a task whenever a new case or ticket is created in Salesforce’s CRM or Zendesk’s ticket management system. You can automatically assign these tasks to agents or supervisors based on the case or ticket created and alert them to take necessary action. To learn more about these use-cases, you can also visit Amazon Connect Rules here.

In this blog post, you will learn how to programmatically access Amazon Connect rules using APIs via AWS CLI.

Prerequisites:

For this blog post, you should have the following prerequisites:

An AWS account with both management console and programmatic administrator access
An existing Amazon Connect instance with Contact Lens enabled and configured within an appropriate contact flow
Upgrade AWS CLI with the latest version from this link based on the Operating System that you are using.

Walkthrough
These instructions assume a working knowledge of Amazon Connect and AWS CLI. For details on how to perform basic administration tasks with these services, see the following:

Step 1 : Setup the AWS CLI with your programmatic access user info

1. Please use the below command to configure your CLI

aws configure

1. Provide the inputs for AWS Access Key ID, AWS Secret Access Key, Default region name and Default output format to complete the setup as per the below snapshot

Step 2 : Obtain the Connect Instance Id

1. Sign in to your AWS Management Console and navigate go to Amazon Connect.
2. On the instances page, choose the instance alias. The instance alias is also your instance name, which appears in your Amazon Connect URL.

1. On the Account overview page, in the Distribution settings section, you can see the full instance ARN. The information after “instance/” is the instance ID. (Please save this in a handy place to use later)

Step 3 : Create a new Rule using APIs via AWS CLI

1. Login to your Amazon Connect admin console with administrator privileges
2. Navigate to the rules section using the left-hand navigation bar

1. View the number of rules defined in the instance prior to running the CLI command for creating the rules on your connect instance.

1. Download the CreateRule template json file and SampleCreateRule API import json file
2. CreateRule Template json file will provide the structure required to build the input json for rules API execution (Please review file to understand all parameters)
3. Update the following parameters in the SampleCreateRule API import json file
  - InstanceId -> Connect instance should be updated for this key value
  - Name -> Valid Unique Rule Name
  - EventBridgeAction -> Name
  - SendNotificationAction -> Content -> Connect Access URL -> Replace “CONNECTACCESSURL“ with your instance url
  - SendNotificationAction -> Recipient -> UserIds -> Replace with the Amazon Connect USER ID (This information can be obtained by using the API)
4. Save the updated json file and run the below CLI command

aws connect create-rule --instance-id <REPLACE_WITH_YOUR_CONNECT_INSTANCE_ID> --region <REPLACE_WITH_YOUR_CONNECT_REGION> --cli-input-json file://"REPLACE_WITH_YOUR_FILE_PATH/Sample_Create_Rule_API_Import.json"

1. Response will contain the new rule ARN and ID

{
    "RuleArn": "arn:aws:connect:us-west-2:xxxxxxxxxxxx:instance/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/rule/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx",
    "RuleId": "xxxxxxxx-xxxx-xxxx-986e-47a4628666f3"
}

1. Copy the Rule Id from the output result and save for later requests
2. Navigate to the Rules UI in your browser to verify the newly created rule using API with new category, event bridge action and email notification to a specific user.

Step 4 : List and Describe Rules using APIs via AWS CLI

1. Run the below CLI command to view the rules in your connect instance.

aws connect list-rules --instance-id <REPLACE_WITH_YOUR_CONNECT_INSTANCE_ID> --region <REPLACE_WITH_YOUR_CONNECT_REGION>

1. The response to the API execution will display all the rules as follows

1. The response contains rule id, rule arn, rule name, rule condition, status of the rule, rule actions and rule specific timestamps.
2. Run the below CLI command to view the rule details for the rule that you created in Step 3

aws connect describe-rule --instance-id <YOUR_CONNECT_INSTANCE_ID> --rule-id <YOUR_NEWLY_CREATED_RULE_ID> --region <YOUR_CONNECT_REGION>

1. The API response will provide all pertinent details related to the rule, similar to the input json file

{
    "Rule": {
        "Name": "PAYMENT_API_RULE",
        "RuleId": "94d22f2a-4ad3-4eaa-zzzzz-zzzzzzz",
        "RuleArn": "arn:aws:connect:us-west-2:xxxxxxxxxxx:instance/xxxxxxxxxxx-zzzzzz-zzzzzzz-zzzz/rule/94d22f2a-4ad3-4eaa-zzzzz-zzzzzzz",
        "TriggerEventSource": {
            "EventSourceName": "OnPostCallAnalysisAvailable"
        },
        "Function": "{\"Version\":\"2022-03-30\",\"RuleFunction\":{\"Operator\":\"AND\",\"Operands\":[{\"Operator\":\"CONTAINS_ANY\",\"Operands\":[\"PAYMENT\"],\"ComparisonValue\":\"$.ContactLens.PostCall.ExactMatch.Transcript\",\"FilterClause\":{\"LogicOperator\":\"AND\",\"Filters\":[{\"Type\":\"ParticipantRole\",\"Data\":\"ANY\"}]}},{\"Operator\":\"OR\",\"Operands\":[{\"Operator\":\"EQUALS\",\"Operands\":[\"YES\"],\"ComparisonValue\":\"$.ContactLens.PostCall.ContactAttribute.PAY_CARD\"}]}]}}",
        "Actions": [
            {
                "ActionType": "ASSIGN_CONTACT_CATEGORY",
                "AssignContactCategoryAction": {}
            },
            {
                "ActionType": "GENERATE_EVENTBRIDGE_EVENT",
                "EventBridgeAction": {
                    "Name": "PC_Rule_Email_EB"
                }
            },
            {
                "ActionType": "SEND_NOTIFICATION",
                "SendNotificationAction": {
                    "DeliveryMethod": "EMAIL",
                    "Subject": "Rules notification - Contact Id: $.ContactLens.RealTimeCall.ContactId",
                    "Content": "This notification from Amazon Connect is for contact Id: $.ContactLens.RealTimeCall.ContactId\n\nView contact: https://connectaccessurl/connect/contact-trace-records/details/$.ContactLens.RealTimeCall.ContactId#realtime",
                    "ContentType": "PLAIN_TEXT",
                    "Recipient": {
                        "UserIds": [
                            "9449ab01-zzzzzzzzzzz-ef8d8b246989"
                        ]
                    }
                }
            

        ],
        "PublishStatus": "PUBLISHED",
        "CreatedTime": "2022cccccc:10:25.784000+00:00",
        "LastUpdatedTime": "2022cccccc:08:00.584000+00:00",
        "LastUpdatedBy": "arn:aws:connect:us-west-2:xxxxxxxxxxx:instance/xxxxxxxxxxx-zzzzzz-zzzzzzz-zzzz/user/IAM@ccccccc"
    }
}

Step 5 : Update Rules using API via AWS CLI

1. We would be updating the newly created rule with additional action to create tasks as a follow-up.
2. Download the UpdateRule template json file and SampleUpdateRule API import json file
3. UpdateRule template json file will provide the structure required to build the input json for rules API execution (Please review file to understand all parameters)
4. Update the following parameters in the SampleUpdateRule API import json file
  - InstanceId -> Connect instance should be updated for this key value
  - RuleId -> Newly created rule id
  - Name -> Newly created rule Name
  - EventBridgeAction -> Name
  - SendNotificationAction -> Content -> Connect Access URL -> Replace “CONNECTACCESSURL“ with your instance url
  - SendNotificationAction -> Recipient -> UserIds -> Replace with the Amazon Connect USER ID (This information can be obtained by using the API)
  - TaskAction -> ContactFlowId -> Replace with your Contact Flow ARN
  - TaskAction -> References -> TaskRef -> Replace with your Connect Access URL
5. Save the updated json file and run the below CLI command

aws connect update-rule --instance-id <REPLACE_WITH_YOUR_CONNECT_INSTANCE_ID> --region <REPLACE_WITH_YOUR_CONNECT_REGION> --cli-input-json file://"REPLACE_WITH_YOUR_FILE_PATH/Sample_Update_Rule_API_Import.json"

1. You would see an empty response when the API execution is successful. You can navigate to the Amazon Connect Rules UI and verify the updated rule where you can see Task as an additional action.

Step 6 : Testing Contact Lens rules

Now if you call into your Amazon Connect instance you can test the real time notification system. Try saying the phrase defined in the rule to the agent (e.g. Payment, Cancellation etc.), shortly after you should receive an email notification containing all the relevant event information as given below.

Step 7 : Deleting Rules using API via AWS CLI

Run the below CLI command to delete the rule in your connect instance.

aws connect delete-rule --instance-id <YOUR_CONNECT_INSTANCE_ID> --rule-id <YOUR_NEWLY_CREATED_RULE_ID> --region <YOUR_CONNECT_REGION>

You would see an empty response when the API execution is successful. You can navigate to the Amazon Connect Rules UI and verify the rule is now deleted.

Cleaning up

To avoid incurring future charges, delete the Amazon Connect rules that we created in this blog.

Conclusion

This post demonstrates how to configure and manage Amazon Connect Rules using APIs via AWS CLI. Using the new send notification email action in the rules, you can now define rules to send emails to specific user or user group for your business use case.

Finally, Amazon Connect rules API can also be accessed via Postman or other AWS services like lambda using respective AWS SDK, though the scope of this blog is access via AWS CLI.

To learn more about the technologies or features used in this blog, see the following:

Join us for AWS Contact Center Day, a free virtual event where you’ll learn about the future of customer service, how machine learning can optimize customer and agent experiences—and more. Register now »

AWS Contact Center

How to programmatically access Amazon Connect Rules using APIs

Resources

Follow