AWS Contact Center

Perform an external screen pop with Amazon Connect

One of the most commonly asked questions we get when people begin using Amazon Connect is, “How can I pop my existing web-based application using data gathered in a contact flow?”

This post provides a comprehensive example that grabs the incoming data and uses it to pop an external web-based application a new window. It can be used as the foundation for more complex and customer-specific use cases. To accomplish this, we use:

That’s it! After you follow the steps in this post, you’ll have a functioning screen pop wrapper for Amazon Connect.

To complete the steps in this post, you need the following:

  1. An active AWS account.
  2. An Amazon Connect instance that has been configured for internal identity management and inbound calls (this simple example is not designed for SAML or Directory based authentication instances). After you create your instance, claim a phone number for it. For more information, see Getting Started with Amazon Connect.

Download and modify the wrapper sample

To simplify this example, here is a ZIP file that has everything required to make an external webpage open on call arrival. The ZIP file includes:

  • An HTML wrapper for the Contact Control Panel (updated for CCP V2).
  • An Amazon Connect Streams API JavaScript file (updated for version 2.0).
  • A sample contact flow that provides the data used for the screen pop.

To download and modify the sample:

  1. Download the ZIP file from Amazon S3.
  2. Extract the contents of the ZIP file. It contains the three files that are used for this blog post.
  3. Find the newly extracted file named simple_screen_template.html. You must modify the HTML file to reference your connect instance.
  4. Open simple_screen_template.html with a text editor.
  5. At line 25, find the section marked:
    /*************** Begin Mod Area ***************/
  6. Below that, on line 28, find the declaration for the variable instanceBase: var instanceBase = "REPLACEME";
  7. Replace REPLACEME with your Amazon Connect access URL base, excluding anything after the base domain, for example: var instanceBase = "https://myinstance.my.connect.aws";
  8. Lines 25 through 30 should now look similar to the following example:
  9. Save and close the file.

That’s the only modification you need to do. Next, upload two of these files to Amazon S3.

Upload to Amazon S3

After modifying the HTML file, save it and the JavaScript file to Amazon S3, which functions as the origin for your new custom contact control panel.

Note: Make sure to log into the AWS Management Console using an account that has the appropriate IAM permissions to create Amazon S3 buckets, such as an IAM account, which belongs to the AdministratorAccess group.

To upload to Amazon S3:

  1. Open the Amazon S3 management console.
  2. Choose Create Bucket.
  3. Provide a unique name for your new bucket. Keep the other default settings, then at the bottom of the page, choose Create.
    NOTE: You can change the default Region for this bucket; however, because the bucket is globally addressable, it is not required.
  4. The bucket is created almost immediately. After you return to the list of buckets, choose the name of the new bucket that you created.
  5. Choose Upload, then add your modified simple_screen_template.html file and the amazon-connect.min.js file. Choose Upload.
  6. Verify that the upload is successful, then Close the status page.

Creating an Amazon CloudFront distribution

Now that you have your custom screen pop page in S3, you will need to provide web access to that page so that you can log in as an Amazon Connect agent. Keeping with best practices, you will use Amazon CloudFront to securely deliver the page to your browser while protecting your S3 objects from public access.

To create a CloudFront distribution for your modified web page:

  1. Open the Amazon CloudFront console.
  2. Select Create distribution
  3. For the Origin domain, choose the S3 bucket that you created in the previous section.
  4. In the S3 bucket access section, select Yes use OAI (bucket can restrict access to only CloudFront).
  5. Choose Create new OAI, then select Create.
  6. Select the Bucket policy option Yes, update the bucket policy.
  7. Leave all other options as their default, and select Create distribution.
  8. On the Distribution detail page, note the Distribution domain name.

The distribution will take a few minutes to deploy. While it does, continue the process to integrate the distribution with your Amazon Connect Instance.

Integrating the CloudFront distribution with your Amazon Connect Instance

In this post, I use Amazon CloudFront to deliver the webpage that embeds the Amazon Connect Contact Control Panel (CCP) by using the Amazon Connect Streams API library. Because the embedded CCP must load within the webpage hosted on Amazon S3 and delivered by CloudFront, I must explicitly allow the domain for CloudFront to display the CCP. This protects customer data from being loaded in an unauthorized page, where the data could be exposed.

To allow embedded CCP in webpages delivered by CloudFront:

  1. Open the Amazon Connect console.
  2. Choose the name of the instance that you are using.
  3. On the left side of the console, choose the Approved origins
  4. Choose Add domain.
  5. In the Enter domain URL box, enter the URL of the CloudFront distribution that you created, prefixed with https://. For example: https://mycloudfrontdistro.cloudfront.net
  6. Choose Add domain.

Import the Contact Flow and Assign it to a Phone Number

The wrapper is now set up and the CloydFront domain is allow-listed. The last step is to configure Amazon Connect to send the parameters required for the screenpop to happen. This is accomplished by setting parameters in a contact flow, and assigning that contact flow to an inbound phone number.

To import a contact flow

  1. Log in to your Amazon Connect instance. The account must be assigned a security profile that includes edit permissions for contact flows.
  2. Choose Routing, Contact flows.
  3. Choose the Create contact flow button in the upper right
  4. Choose the dropdown arrow next to Save, Import flow (beta).
  5. Select the contact flow that was extracted from the zip file, SimpleScreenPopExample, and choose Import.
  6. Select Publish, and confirm by again selecting Publish to make the contact flow available for use.Note: There may be a warning indicator on the Set Working Queue block in the contact flow. This is because I used an imported contact flow. The block references a queue by ARN, but ARNs are globally unique. When I import the contact flow, no queue with the ARN specified in the exported flow is found in your instance. Amazon Connect automatically resolves to the queue in your instance with the same name. If you renamed the default BasicQueue in Amazon Connect, you must select the appropriate queue.

The contact flow assigned to a phone number is the contact flow that executes when a call comes in to that number. So I’ll use the contact flow I just saved as the flow for this phone number. You can either claim a new number and assign the contact flow to it, or you can associate an existing number to the contact flow. If you associate an existing number, you disconnect it from the currently assigned contact flow, so don’t do this for a production environment where customers are placing calls to that number.

Note: If you claim an additional phone number, additional charges may be incurred for Amazon Connect. As part of the Free Tier, you can claim one DID number free of charge. For more information, reference the Amazon Connect Pricing page.

To claim a number for your contact center:

  1. Choose Routing, Phone numbers.
  2. Choose Claim a number in the top-right corner of the screen. You can choose a Toll free or a DID (Direct Inward Dialing) number.
  3. Enter a description for the number and in the Contact flow/IVR dropdown, choose SimpleScreenPopExample.
  4. Choose Save.

To associate a phone number with a contact flow:

  1. Choose Routing, Phone numbers.
  2. Select the number to edit, expand Contact flow/IVR, and choose SimpleScreenPopExample.
  3. Choose Save.

After you save the phone number, wait a couple of minutes before the change has propagated. Make a note of the phone number, because you need it to send calls to your agent.

Log in and take a call

Now that you have everything set up, the last step is to log in and take a call using your modified Contact Control Panel. Use the domain you saved earlier from your CloudFront distribution.

To log in and take a call:

  1. Open Chrome or Firefox.
  2. In the URL field, paste the full domain (with https://) of your CloudFrond distribution and add /simple_screen_template.html to complete the URL. It should be similar to:
    https://mycloudfrontdistro.cloudfront.net/simple_screen_template.html
  3. When the page is loading, it displays a second tab to authenticate your agent.
    NOTE: If the authentication window does not display, your browser’s pop-up blocker may be preventing it. For information about enabling pop-ups, check your browser.
  4. After the authentication completes, you are asked to allow notifications and microphone access. Grant both.
  5. Close the new tab.
  6. Make sure you (the agent) are in the Available state. If you are not set to Available, select the status dropdown menu and choose Available.
  7. Call into the number that you associated with your new contact flow.
  8. As the call is delivered, a new tab or browser window (depending on your browser settings) should open and display a search result.

You have successfully popped an external URL based on data within Amazon Connect.

How this screen pop works

This screen pop works by passing two contact attributes from the contact flow to the CCP: screenPopURL and screenPopValue. When the call arrives to the CCP, the embedded Amazon Connect Streams API sees the onConnecting event, reads the contact attributes from the incoming call, and then uses these two attributes to form the URL of the website to pop. JavaScript is used to open a new window or tab using the generated URL.

You can easily modify these values in the contact flow by editing them in the Set contact attributes block. You could even use dynamic values from an AWS Lambda function call.

Conclusion

This post provided you with a working sample webpage that has an embedded Contact Control Panel that retrieves data from an incoming call using the streams API and builds a URL that opens in a new tab or window. This is the foundation for a screen pop function that can be modified to work in any number of use cases.