How do I display caller contact attributes in an Amazon Connect screenpop?

Last updated: 2021-08-17

I want agents in my Amazon Connect contact center to be able to see the contact attributes of incoming customer calls. How do I set that up?

Short description

To display caller contact attributes to your agents in the Amazon Connect Contact Control Panel (CCP), use a screenpop.

To use a screenpop in Amazon Connect, you must use the Amazon Connect Streams API to integrate the CCP into a custom application. Screenpops aren't directly available in the CCP.

The example procedure in this article shows how to display caller contact attributes in the CCP by doing the following:

For more information, see Use contact attributes in the CCP. For another example setup, see Perform an external screenpop with Amazon Connect on the AWS Contact Center blog.


Note: For this example setup, you can hard-code the contact attribute values as a test. For a more advanced setup, you can retrieve the contact attribute values by using AWS Lambda to retrieve customer information from an Amazon DynamoDB database. For a similar example, see How do I set up extensions for agent-to-agent calling in my Amazon Connect contact center?

Create or update a contact flow to set contact attributes during call routing

Create a new contact flow or open an existing contact flow in the contact flow designer

1.    Open the Amazon Connect console.

2.    Under Access URL, choose the access URL for your Amazon Connect instance.

3.    Log in to your instance using the administrator account.

4.    In the left navigation pane, pause on Routing. Then, choose Contact flows.

5.    Under Contact flows, choose a template or an existing contact flow that you want to update.
Note: You can use the Sample note for screenpop template, but it's not required for setting up a screenpop in Amazon Connect.


To design a custom contact flow, choose Create contact flow.

6.    In the contact flow designer, for Enter a name, enter a name for the contact flow. For example: Contact attributes for screenpop.

7.    Choose Save.

For more information, see Create a new contact flow.

Add a Set contact attributes block

Important: The contact attributes that you define in this block must be referenced in the HTML file that you use for your custom web application.

To store key-value pairs as contact attributes, use a Set contact attributes block.

1.    In the contact flow designer, choose Set. Then, drag and drop a Set contact attributes block onto the canvas.

2.    Choose the block title (Set contact attributes). The block's settings menu opens.

3.    Under Attribute to save, choose Use text. Then, do the following:
For Destination key, enter a name for the first name attribute, such as firstName.
For Value, enter an example first name for testing. For example, Alexa.

4.    Choose Add another attribute.

5.    In the new attribute, choose Use text. Then, do the following:
For Destination key, enter a name for the phone number attribute. For example: phoneNumber.
For Value, enter an example phone number for testing. For example: 123-456-7890.

6.    Choose Add another attribute.

7.    In the new attribute, choose Use text. Then, do the following:
For Destination key, enter a name for the account number attribute. For example: accountNumber.
For Value, enter an example account number for testing. For example: 9876543210.

8.    Choose Save.

Add a Transfer to queue block

To end the current contact flow and place the customer in a queue, add a Transfer to queue block.

For more information, see Set up contact transfers.

Add a Set working queue block

To specify the queue to be used when the Transfer to queue block is invoked, add a Set working queue block.

For more information, see Set up contact transfers.

Connect the blocks

Important: All connectors must be connected to a block before you can publish the contact flow.

In the contact flow designer, drag the arrows from each block to the block that you want to perform the next action by doing the following:

1.    For each block, connect Start or Success to the next block in this order:
Entry point > Set contact attributes > Set working queue > Transfer to queue

2.    For each block, connect Error and At capacity to the Disconnect / hang up block.

Save and publish the contact flow

1.    Choose Save.

2.    In the Save flow dialog, choose Save.

3.    Choose Publish.

4.    In the Publish dialog, choose Publish.

Set up your Amazon Connect instance's CCP in a custom web application

To integrate your instance's CCP into a custom web application, follow the instructions in the Amazon Connect Streams documentation on GitHub.

Example Amazon Connect Streams API code that makes a screenpop display when an agent connects with a caller

The following example code integrates the CCP in a basic HTML file hosted as a static website on Amazon Simple Notification Service (Amazon S3).

Important: Modify the example code as needed to reference the required contact attributes as you defined them in the Set contact attributes block in the contact flow. Make sure that you also replace bucketName with your S3 bucket name, and replace connectInstanceName with your Amazon Connect instance name. For more information, see Accessing a bucket and Launch the CCP.

<!--Copyright 2019, Inc. or its affiliates. All Rights Reserved.-->
<!--SPDX-License-Identifier: MIT-0-->

 <script src=""></script>
<h1> Amazon Connect </h1>
<h2> Screenpop Example </h1>
<div id="containerDiv" ></div>
connect.core.initCCP(containerDiv, {
   ccpUrl:        '',        /*REQUIRED (*** has been replaced) */
   loginPopup:    true,          /*optional, default TRUE*/
   softphone:     {              /*optional*/
      allowFramedSoftphone: true
}); {

        contact.onIncoming(function(contact) {

        contact.onRefresh(function(contact) {

        contact.onAccepted(function(contact) {

        contact.onEnded(function() {

        contact.onConnected(function() {
                var attributeMap = contact.getAttributes();
                var name = JSON.stringify(attributeMap["firstName"]["value"]);
                var phone = JSON.stringify(attributeMap["phoneNumber"]["value"]);
                var account = JSON.stringify(attributeMap["accountNumber"]["value"]);
                window.alert("Customer's name: " + name + "\nCustomer's phone #: " + phone + "\nCustomer's account #: " + account);


Note: You can also configure the screenpop to display when a call is accepted or when it's routed to an agent.

To troubleshoot issues with the Amazon Connect Streams API

Use console.log() statements in the script. When you're on your webpage, view the logging output in the console of your web browser's developer tools.

For more information, see console.log() on the MDN Web Docs page.