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

Last updated: 2020-01-17

When my customers call into my Amazon Connect contact center, I want their contact attributes to appear for my agents to see. How do I set that up?

Short Description

Use a screenpop, which shows caller contact attributes to your agents in the Amazon Connect Contact Control Panel (CCP). Screenpops aren't available directly in the Amazon Connect instance CCP. Instead, you can use the Amazon Connect Streams API to integrate the CCP into a custom web application. For more information, see the Amazon Connect Streams repository on GitHub.

Follow these instructions to design a contact flow that sets contact attributes during call routing. Then, create an example web application using the provided example code. 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 perform a data dip to an Amazon DynamoDB database of customer information.

For more information, see Use Contact Attributes in the CCP and Contact Attribute Concepts. For another example setup, see Perform an external screen pop with Amazon Connect on the AWS Contact Center blog.


Create or update a contact flow

  1. In the Amazon Connect console, under Access URL, choose the access URL for your instance.
  2. Log in to your instance using the administrator account.
  3. In the left navigation bar, pause on Routing, and then choose Contact flows.
  4. Under Contact flows, choose a template or an existing contact flow that you want to update, or choose Create contact flow to design a contact flow from scratch. For more information, see Create a New Contact Flow.
    Note: You can use the Sample note for screenpop template, but it's not required for setting up a screenpop.
  5. In the contact flow designer, for Enter a name, enter a name for the contact flow. (For example, Contact attributes for screenpop.)
  6. Choose Save.

For more information, see Create Amazon Connect Contact Flows.

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.

  1. In the contact flow designer, choose Set, and 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, and 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, and then do the following:
    For Destination key, enter a name for the phone number attribute, such as 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, and then do the following:
    For Destination key, enter a name for the account number attribute, such as accountNumber.
    For Value, enter an example account number for testing. For example, 9876543210.
  8. Choose Save.

Set up contact transfers

Add a Set working queue block and a Transfer to queue block. For more information, see Set Up Contact Transfers.

Connect the blocks

In the contact flow designer, drag the arrows from each block to the block that you want to perform the next action. All connectors must be connected to a block before you can publish the contact flow.

  • 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
  • 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 the CCP in a custom web application

Integrate the Amazon Connect CCP into a custom web application using the Streams API. For details on setting up the Streams API with a webpage, see Amazon Connect Streams Documentation on GitHub.

This example code integrates the CCP in a basic HTML file hosted as a static website on Amazon Simple Storage Service (Amazon S3). It makes a screenpop display when an agent connects to a caller. You can also have the screenpop display when a call is accepted or when it's routed to an agent.

Note: Modify this code as needed to reference the contact attributes as you defined them in the Set contact attributes block in the contact flow. Be sure also to 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["name"]["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);



To troubleshoot issues with the 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.