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:
- An active AWS account.
- An Amazon Connect instance that has been configured for inbound calls. 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).
- A sample contact flow that provides the data used for the screen pop.
To download and modify the sample:
- Download the ZIP file from Amazon S3.
- Extract the contents of the ZIP file. It contains the three files that are used for this blog post.
- Find the newly extracted file named simple_screen_template.html. You must modify the HTML file to reference your connect instance.
- Open simple_screen_template.html with a text editor.
- At line 24, find the section marked:
/*************** Begin Mod Area ***************/
- Just below that, on line 27, find the declaration for the variable instanceName:var instanceName = “REPLACEME”;
- Replace REPLACEME with your Amazon Connect instance name, for example:var instanceName = “myinstance”;
- Lines 26 through 29 should now look similar to the following example:
- 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 and make the file public
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:
- Open the Amazon S3 management console.
- Choose Create Bucket.
- 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.
- The bucket is created almost immediately. After you return to the list of buckets, choose the name of the new bucket that you created.
- Choose Upload, then add your modified simple_screen_template.html file and the amazon-connect.min.js file. Choose Upload
- After the upload completes, make the files public so that everyone can access your website. To make files public, modify your bucket’s Public Access settings, as shown in the following example (if you have not already set them).
For more information about Amazon S3 Public Access settings, see the Amazon Simple Storage Service documentation.
To make the files publicly readable:
- Select the check box next to the two files that you uploaded into Amazon S3.
- On the Actions menu, choose Make Public.
- Choose the Make Public button on the pop-up window.
- Choose the name of the HTML file.
- On the Overview page, copy the URL in the Link Save it for later.
Integrating S3 hosted webpages with your Amazon Connect Instance
In this post, I use Amazon S3 to host a 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, I must explicitly allow the domain for Amazon S3 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 hosted in Amazon S3:
- Open the Amazon Connect console.
- Choose the name of the instance that you are using.
- On the left side of the console, choose the Application integration
- Choose Add Origin.
- In the Enter origin URL box, enter the URL of the template file that you saved above. You only need to include the URL through the domain name. For example: https://samplescreenpopblogtest.s3.amazonaws.com
- Choose Add.
Import the Contact Flow and Assign it to a Phone Number
The wrapper is now set up and the Amazon S3 bucket is whitelisted. 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
- Log in to your Amazon Connect instance. The account must be assigned a security profile that includes edit permissions for contact flows.
- Choose Routing, Contact flows.
- Choose the Create contact flow button in the upper right
- Choose the dropdown arrow next to Save, Import flow (beta).
- Select the contact flow that was extracted from the zip file, SimpleScreenPopExample, and choose Import.
- Choose the same dropdown arrow, Save and 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 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, see .
To claim a number for your contact center:
- Choose Routing, Phone numbers.
- 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.
- Enter a description for the number and in the Contact flow/IVR dropdown, choose SimpleScreenPopExample.
- Choose Save.
To associate a phone number with a contact flow:
- Choose Routing, Phone numbers.
- Select the number to edit, expand Contact flow/IVR, and choose SimpleScreenPopExample.
- 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 URL you saved earlier from the modified HTML file that you put in Amazon S3.
To log in and take a call:
- Open Chrome or Firefox.
- Navigate to the URL you saved earlier. It should be similar to:
- When the page is loading, it displays a second tab to authenticate your agent. 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.
- After the authentication completes, you are asked to allow notifications and microphone access. Grant both.
- Close the new tab.
- Make sure you (the agent) are in the Available state. If you are not set to Available, choose Set to available, or choose Change Status, and then choose Available.
- Call into the number that you associated with your new contact flow.
- 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
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.
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.