amazon-connect-streams

About

Build Status

The Amazon Connect Streams API (Streams) gives you the power to integrate your existing web applications with Amazon Connect. Streams lets you embed the Contact Control Panel (CCP) and Customer Profiles app UI into your page. It also enables you to handle agent and contact state events directly through an object oriented event driven interface. You can use the built in interface or build your own from scratch: Streams gives you the choice.

This library must be used in conjunction with amazon-connect-chatjs or amazon-connect-taskjs in order to utilize Amazon Connect’s Chat or Task functionality.

Learn More

To learn more about Amazon Connect and its capabilities, please check out the Amazon Connect User Guide.

Usage

amazon-connect-streams is available from npmjs.com. If you’d like to download it here, you can use either of the files like release/connect-streams*.

Run npm run release to generate new release files. Full instructions for building locally with npm can be found below.

In version 1.x, we also support make for legacy builds. This option was removed in version 2.x.

Important Announcements

  1. August 2025 - 2.18.7
    • Adds important stability update addressing periodic login popups that some customers experienced even when agents had valid authentication sessions. This update replaces the heartbeat mechanism used to detect changes in agent authentication status as Chrome now no longer recommends using timers for periodic state checks.
    • Deprecates ccpSynTimeout and ccpAckTimeout init CCP Params
  2. January 2025 - 2.18.1
    • Provides bug fixes for chat and voice. Customers using 2.17 and 2.18 should upgrade to 2.18.1
  3. December 2024 - Major changes:
    • Introducing Multiparty Chat, allowing up to 4 additional agents to join an ongoing chat conversation, making it easier to collaborate and resolve customer issues quickly.
  4. November 2024 - Major changes:
    • Introducing Email
    • Storage access settings from initCCP are now deprecated after Google is no longer deprecating 3rd party cookies by default.
    • Global resiliency involving connect-streams-dr.js is now deprecated. Please reference Documentation-GR.md for the new set of APIs.
  5. July 2024 - The issue with muting while a Voice contact is on hold has been resolved. Agents can use the mute button while a contact is placed on hold. The following APIs will be available when the contact is on hold:
    • voiceConnection.muteParticipant()
    • voiceConnection.unmuteParticipant()
    • agent.mute()
    • agent.unmute()
  6. February 2024 - In response to a Google Chrome feature launched on 7/13/2023 called Storage Partitioning, we made a short term fix on 2/10/2024 to adjust our mute functionality and synchronize the mute state across all CCPs. However, due to current limitations, this change required us to disable muting while being on hold. As a workaround, agents should mute themselves on the call before going on hold. We are planning to address this issue by August 2024 and revert back to original mute behavior.
    • At the moment, the following APIs will fail when the contact is on hold:
      • voiceConnection.muteParticipant()
      • voiceConnection.unmuteParticipant()
      • agent.mute()
      • agent.unmute()
    • As a workaround, you can mute the call prior to placing the call on hold.

Getting Started

Upgrading to the OmniChannel CCP (AKA CCPv2)?

If you are migrating to the new CCP, we encourage you to upgrade to the latest version of this repository. You should also upgrade to the latest version of RTC-JS as well, if you are using it. For a complete migration guide to the new CCP, and to fully understand the differences when using Streams with the new CCP, please see this post: https://docs.aws.amazon.com/connect/latest/adminguide/upgrade-to-latest-ccp.html

Allowlisting

The first step to using Streams is to allowlist the pages you wish to embed. For our customer’s security, we require that all domains which embed the CCP for a particular instance are explicitly allowlisted. Each domain entry identifies the protocol scheme, host, and port. Any pages hosted behind the same protocol scheme, host, and port will be allowed to embed the CCP components which are required to use the Streams library.

To allowlist your pages:

  1. Login to your AWS Account, then navigate to the Amazon Connect console.
  2. Click the instance name of the instance for which you would like to allowlist pages to load the settings page for your instance.
  3. Click the “Application integration” link on the left.
  4. Click “+ Add Origin”, then enter a domain URL, e.g. “https://example.com", or "https://example.com:9595" if your website is hosted on a non-standard port.

A few things to note:

Downloading Streams with npm

npm install amazon-connect-streams

Importing Streams with npm and ES6

import "amazon-connect-streams"; This will make the connect variable available in the current context.

Usage with TypeScript

amazon-connect-streams is compatible with TypeScript. You’ll need to use version 3.0.1 or higher:

import "amazon-connect-streams";

connect.core.initCCP({ /* ... */ });

Downloading Streams from Github

The next step to embedding Connect into your application is to download the Streams library from GitHub. You can do that by cloning our public repository here:

$ git clone https://github.com/aws/amazon-connect-streams

Once you download streams, change into the directory and build it:

$ cd amazon-connect-streams
$ make

This will generate a file called connect-streams-${VERSION}.js, this is the full Connect Streams API which you will want to include in your page. You can serve connect-streams-${VERSION}.js with your web application.

Build your own with NPM

Install latest LTS version of NodeJS

Instructions for Streams version 2.x:

$ git clone https://github.com/aws/amazon-connect-streams
$ cd amazon-connect-streams
$ npm install
$ npm run release

Find build artifacts in release directory - This will generate a file called connect-streams.js and the minified version of the same connect-streams-min.js - this is the full Connect Streams API which you will want to include in your page.

To run unit tests:

$ npm run test-mocha

Note: these tests run on the release files generated above

Instructions for Streams version 1.x:

You will also need to have gulp installed. You can install gulp globally.

$ npm install -g gulp
$ git clone https://github.com/aws/amazon-connect-streams
$ cd amazon-connect-streams
$ npm install
$ npm run release

Find build artifacts in release directory - This will generate a file called connect-streams.js and the minified version of the same connect-streams-min.js - this is the full Connect Streams API which you will want to include in your page.

To run unit tests:

$ npm run gulp-test

Note: these tests run on the release files generated above

Using the AWS SDK and Streams

Streams has a “baked-in” version of the AWS-SDK in the ./src/aws-client.js file. Make sure that you import Streams before the AWS SDK so that the AWS object bound to the Window is the object from your manually included SDK, and not from Streams.

Initialization

Initializing the Streams API is the first step to verify that you have everything setup correctly and that you will be able to listen for events.

connect.core.initCCP()

<!DOCTYPE html>
<html>
  <head>
    <meta charset="UTF-8">
    <script type="text/javascript" src="connect-streams-min.js"></script>
  </head>
  <!-- Add the call to init() as an onload so it will only run once the page is loaded -->
  <body onload="init()">
    <div id="container-div" style="width: 400px; height: 800px;"></div>
    <script type="text/javascript">
      var containerDiv = document.getElementById("container-div");
      var instanceURL = "https://my-instance-domain.my.connect.aws/ccp-v2/";
      // initialize the streams api
      function init() {
        // initialize the ccp
        connect.core.initCCP(containerDiv, {
          ccpUrl: instanceURL,            // REQUIRED
          loginPopup: true,               // optional, defaults to `true`
          loginPopupAutoClose: true,      // optional, defaults to `false`
          loginOptions: {                 // optional, if provided opens login in new window
            autoClose: true,              // optional, defaults to `false`
            height: 600,                  // optional, defaults to 578
            width: 400,                   // optional, defaults to 433
            top: 0,                       // optional, defaults to 0
            left: 0                       // optional, defaults to 0
          },
          region: "eu-central-1",         // REQUIRED for `CHAT`, optional otherwise
          softphone: {                    // optional, defaults below apply if not provided
            allowFramedSoftphone: true,   // optional, defaults to false
            disableRingtone: false,       // optional, defaults to false
            ringtoneUrl: "[your-ringtone-filepath].mp3", // optional, defaults to CCP’s default ringtone if a falsy value is set
            allowFramedVideoCall: true,    // optional, default to false
            allowEarlyGum: true    //optional, default to true
          },
          task: {
            disableRingtone: false, // optional, defaults to false
            ringtoneUrl: "[your-ringtone-filepath].mp3" // optional, defaults to CCP's default ringtone if a falsy value is set
          },
          pageOptions: { //optional
            enableAudioDeviceSettings: false, //optional, defaults to 'false'
            enableVideoDeviceSettings: false, //optional, defaults to 'false'
            enablePhoneTypeSettings: true //optional, defaults to 'true' 
          },
          shouldAddNamespaceToLogs: false, //optional, defaults to 'false'
          ccpAckTimeout: 5000, //optional, defaults to 3000 (ms)
          ccpSynTimeout: 3000, //optional, defaults to 1000 (ms)
          ccpLoadTimeout: 10000 //optional, defaults to 5000 (ms)
         });
      }
    </script>
  </body>
</html>

Integrates with Connect by loading the pre-built CCP located at ccpUrl into an iframe and placing it into the containerDiv provided. API requests are funneled through this CCP and agent and contact updates are published through it and made available to your JS client code.

Where to go from here

Check out the full documentation here to read more about subscribing to events and enacting state changes programmatically.

This site is open source. Improve this page.