Merge pull request #618 from seiyako/master

Streams 2.4.2

CHANGELOG.md

@@ -1,10 +1,16 @@
 # CHANGELOG.md
 
+
+## 2.4.2
+- Fix an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs).
+
+## 2.4.1
+- This version brings in updates that will provide enhanced monitoring experience to agents and supervisors, allowing to silently monitor multiparty calls, and if needed to barge in the call and take over control, mute agents, or drop them from the call. New APIs introduced with this feature are `isSilentMonitor`, `isBarge`, `isSilentMonitorEnabled`, `isBargeEnabled`, `isUnderSupervision`, `updateMonitorParticipantState`, `getMonitorCapabilities`, `getMonitorStatus`, `isForcedMute`.
+
 ## 2.4.0
 - Introduce Amazon Connect Step-by-step guides embedding support via `connect.agentApp.initApp`.
 
 ## 2.3.0
-- Fix an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs).
 - Make StreamsJS compatible with strict mode
 - Fix an issue that connect.ValueError and connect.StateError don't print error message properly
 

Documentation.md

@@ -15,10 +15,12 @@ In version 1.x, we also support `make` for legacy builds. This option was remove
 1. December 2022 - In addition to the CCP, customers can now embed the Step-by-step guides application using the connect.agentApp. See the [updated documentation](https://github.com/amazon-connect/amazon-connect-streams/blob/master/Documentation.md#initialization-for-ccp-customer-profiles-and-wisdom) for details on usage. 
     * ### About Amazon Connect Step-by-step guides 
       + With Amazon Connect you can now create guides that walk agents through tailored views that focus on what must be seen or done by the agent at a given moment during an interaction. You can design workflows for various types of customer interactions and present agents with different step-by-step guides based on context, such as call queue, customer information, and interactive voice response (IVR). This feature is available in the Connect agent workspace as well as an embeddable application that can be embedded into another website via the Streams API. For more information, visit the AWS website: https://aws.amazon.com/connect/agent-workspace/
+1. December 2022 - 2.4.2
+    * This patch fixes an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs). This occurred in some scenarios where you call either enrollSpeakerInVoiceId(), evaluateSpeakerWithVoiceId(), or updateVoiceIdSpeakerId() in your custom CCP integration code. If you are using Voice ID and consuming Voice ID CTRs, or updating speaker ID in your agent workflow, please upgrade to this version.
 1. December 2022 - 2.4.1
     * This version brings in updates that will provide enhanced monitoring experience to agents and supervisors, allowing to silently monitor multiparty calls, and if needed to barge in the call and take over control, mute agents, or drop them from the call. New APIs introduced with this feature are `isSilentMonitor`, `isBarge`, `isSilentMonitorEnabled`, `isBargeEnabled`, `isUnderSupervision`, `updateMonitorParticipantState`, `getMonitorCapabilities`, `getMonitorStatus`, `isForcedMute`.
 1. August 2022 - 2.3.0
-    * This patch fixes an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs). This occurred in some scenarios where you call either enrollSpeakerInVoiceId(), evaluateSpeakerWithVoiceId(), or updateVoiceIdSpeakerId() in your custom CCP integration code. If you are using Voice ID and consuming Voice ID CTRs, please upgrade to this version.
+    * [Update on 12/13/2022] Please see 2.4.2 for final resolution of the Voice ID CTR fix.
 1. Jan 2022 - 2.0.0
     * Multiple calls to `initCCP` will no longer append multiple embedded CCPs to the window, and only the first call to `initCCP` will succeed. Please note that the use-case of initializing multiple CCPs has never been supported by Streams, and this change has been added to prevent unpredictable behavior arising from such cases.
     * `agent.onContactPending` has been removed. Please use `contact.onPending` instead. `connect.onError` now triggers. Previously, this api did not work at all. Please be aware that, if you have application logic within this function, its behavior has changed. See its entry in documentation.md for more details.
@@ -1429,7 +1431,12 @@ conn.muteParticipant({
    failure: function(err) { /* ... */ }
 });
 ```
-Mute the connection server side.
+Mute the connection server side. 
+#### Multiparty call
+Any agent participant can mute another agent participant. 
+
+#### Supervisor barges into the call
+Agents can mute themselves, but cannot mute other agents or supervisor.  
 
 Optional success and failure callbacks can be provided to determine if the operation was successful.
 
@@ -1440,7 +1447,12 @@ conn.unmuteParticipant({
    failure: function(err) { /* ... */ }
 });
 ```
-Unmute the connection server side.
+Unmute the connection server side. 
+#### Multiparty call 
+Any agent can only unmute themselves.
+
+#### Supervisor barges into the call
+Agents can only unmute themselves up until the point they have been muted by the supervisor (isForcedMute API can help checking that). Once they have been muted by the supervisor, agent cannot unmute themselves until supervisor unmutes agent (at which point agent will regain ability to mute and unmute themselves). If supervisor has muted but not unmuted agent then drops from call, agent will be able to unmute themselves once supervisor has dropped.
 
 Optional success and failure callbacks can be provided to determine if the operation was successful.
 
@@ -1989,3 +2001,113 @@ voiceConnection.deleteVoiceIdSpeaker()
     console.error(err);
   });
 ```
+
+## Enhanced Monitoring APIs
+Enhanced monitoring providing real-time silent monitoring and barge capability to help managers and supervisors to listen in the agents' conversations and barge into the call if needed to take over the control and provide better customer experience. Supervisors in barge mode will be able to force mute agents and prevent them from unmuting themselves, will be able to hold, drop any connection, or directly speak with the customer. If the supervisor has muted an agent and then drops from the call, the agent will be able to unmute themselves once supervisor has dropped. Monitoring APIs are expected to be used against agent's(or supervisor's) connection. To start enhanced monitoring supervisor/manager will need to click an eye icon on the Real Time Metrics page.
+
+Streams Enhanced Monitoring APIs can be tested after all these prerequisites are met:
+1. Enable Multi-Party Calls and Enhanced Monitoring in Telephony section of the Amazon Connect Console.
+1. Enable Real-time contact monitoring and Real-time contact barge-in in Security Profiles
+
+### `voiceConnection.isSilentMonitor()`
+```js
+if (conn.isSilentMonitor()) { /* ... */ }
+```
+Returns true if monitorStatus is `MonitoringMode.SILENT_MONITOR`. This means the supervisor connection is in silent monitoring state. Regular agent will not see supervisor's connection in the snapshot while it is in silent monitor state.
+
+### `voiceConnection.isBarge()`
+```js
+if (conn.isBarge()) { /* ... */ }
+```
+Returns true if monitorStatus is `MonitoringMode.BARGE`. This means the connection is in barge-in state. Regular agent will see the supervisor's connection in the list of connections in the snapshot.
+
+### `voiceConnection.isSilentMonitorEnabled()`
+```js
+if (conn.isSilentMonitorEnabled()) { /* ... */ }
+```
+Returns true if agent's monitoringCapabilities contain `MonitoringMode.SILENT_MONITOR` type. 
+
+### `voiceConnection.isBargeEnabled()`
+```js
+if (conn.isBargeEnabled()) { /* ... */ }
+```
+Returns true if agent's monitoringCapabilities contain `MonitoringMode.BARGE` state type.
+
+### `voiceConnection.getMonitorCapabilities()`
+```js
+var allowedMonitorStates = conn.getMonitorCapabilities();
+```
+Returns the array of enabled monitor states of this connection. The array will consist of `MonitoringMode` enum values.
+
+### `voiceConnection.getMonitorStatus()`
+```js
+var monitorState = conn.getMonitorStatus();
+```
+Returns the current monitoring state of this connection. The value can be on of `MonitoringMode` enum values if the agent is supervisor, or the monitorStatus will not be present for the agent.
+
+### `voiceConnection.isForcedMute()`
+```js
+if (conn.isForcedMute()) { /* ... */ }
+```
+Determine whether the connection was forced muted by the manager.
+
+### `contact.updateMonitorParticipantState()`
+```js
+contact.updateMonitorParticipantState(targetState, {
+   success: function() { /* ... */ },
+   failure: function(err) { /* ... */ }
+});
+```
+Updates the monitor participant state to switch between different monitoring modes. The targetState value is a `MonitoringMode` enum member.
+
+### `contact.isUnderSupervision()`
+```js
+if (contact.isUnderSupervision()) { /* ... */ }
+```
+Determines if the contact is under manager's supervision
+
+#### Usage examples
+
+Check that barge is enabled before switching to the barge mode - first we need to make sure that barge is enabled for the supervisor connection, and after that initiate monitor status change on the contact.
+```js
+if(voiceConnection.isBargeEnabled()) {
+  contact.updateMonitorParticipantState(connect.MonitoringMode.BARGE, {
+   success: function() { 
+    console.log("Successfully changed the monitoring status to barge, now you can control the conversation")
+   },
+   failure: function(err) { 
+    console.log("Somenting went wrong, here is the error ", err) 
+   }
+  }); 
+}
+```
+
+Check that silent monitor is enabled before switching to the silent monitor mode - first we need to make sure that silent monitor is enabled for the supervisor connection, and after that initiate monitor status change on the contact.
+```js
+if(voiceConnection.isSilentMonitorEnabled()) {
+  contact.updateMonitorParticipantState(connect.MonitoringMode.SILENT_MONITOR, {
+   success: function() { 
+    console.log("Successfully changed the monitoring status to silent monitor")
+   },
+   failure: function(err) { 
+    console.log("Somenting went wrong, here is the error ", err) 
+   }
+  }); 
+}
+```
+
+After supervisor mutes the agent - force mute field is automatically updated on the agent side. You may want to display a banner or somehow indicate to the agent that he cannot unmute himself back anymore.
+
+```js
+if(voiceConnection.isForcedMute()) {
+  /* Some logic here to indicate forced mute to the agent */
+}
+```
+
+After supervisor barges the call - agent doesn't have control anymore. Agent can only mute or unmute himself until he was forced muted, or leave the call. It will be good to indicate that to ahent as well by hiding or disabling buttons.
+
+```js
+if(voiceConnection.isUnderSupervision()) {
+  /* Some logic here to indicate disabled call controls to the agent */
+}
+```

README.md

@@ -21,8 +21,12 @@ In version 1.x, we also support `make` for legacy builds. This option was remove
 1. December 2022 - In addition to the CCP, customers can now embed the Step-by-step guides application using the connect.agentApp. See the [updated documentation](https://github.com/amazon-connect/amazon-connect-streams/blob/master/Documentation.md#initialization-for-ccp-customer-profiles-and-wisdom) for details on usage. 
     * ### About Amazon Connect Step-by-step guides 
       + With Amazon Connect you can now create guides that walk agents through tailored views that focus on what must be seen or done by the agent at a given moment during an interaction. You can design workflows for various types of customer interactions and present agents with different step-by-step guides based on context, such as call queue, customer information, and interactive voice response (IVR). This feature is available in the Connect agent workspace as well as an embeddable application that can be embedded into another website via the Streams API. For more information, visit the AWS website: https://aws.amazon.com/connect/agent-workspace/
+1. December 2022 - 2.4.2
+    * This patch fixes an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs). This occurred in some scenarios where you call either enrollSpeakerInVoiceId(), evaluateSpeakerWithVoiceId(), or updateVoiceIdSpeakerId() in your custom CCP integration code. If you are using Voice ID and consuming Voice ID CTRs, or updating speaker ID in your agent workflow, please upgrade to this version.
+1. December 2022 - 2.4.1
+    * This version brings in updates that will provide enhanced monitoring experience to agents and supervisors, allowing to silently monitor multiparty calls, and if needed to barge in the call and take over control, mute agents, or drop them from the call. New APIs introduced with this feature are `isSilentMonitor`, `isBarge`, `isSilentMonitorEnabled`, `isBargeEnabled`, `isUnderSupervision`, `updateMonitorParticipantState`, `getMonitorCapabilities`, `getMonitorStatus`, `isForcedMute`.
 1. August 2022 - 2.3.0
-    * This patch fixes an issue in Streams’ Voice ID APIs that may have led to incorrect values being set against the generatedSpeakerID field in the VoiceIdResult segment of Connect Contact Trace Records (CTRs). This occurred in some scenarios where you call either enrollSpeakerInVoiceId(), evaluateSpeakerWithVoiceId(), or updateVoiceIdSpeakerId() in your custom CCP integration code. If you are using Voice ID and consuming Voice ID CTRs, please upgrade to this version.
+    * [Update on 12/13/2022] Please see 2.4.2 for final resolution of the Voice ID CTR fix.
 1. Jan 2022 - 2.0.0
     * Multiple calls to `initCCP` will no longer append multiple embedded CCPs to the window, and only the first call to `initCCP` will succeed. Please note that the use-case of initializing multiple CCPs with `initCCP` has never been supported by Streams, and this change has been added to prevent unpredictable behavior arising from such cases.
     * `agent.onContactPending` has been removed. Please use `contact.onPending` instead. `connect.onError` now triggers. Previously, this api did not work at all. Please be aware that, if you have application logic within this function, its behavior has changed. See its entry in documentation.md for more details.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "amazon-connect-streams",
-  "version": "2.4.1",
+  "version": "2.4.2",
   "description": "Amazon Connect Streams Library",
   "engines": {
     "node": ">=12.0.0"

release/connect-streams.js

@@ -3795,7 +3795,8 @@ module.exports = cloneDeep;
         client.call(connect.AgentAppClientMethods.UPDATE_SESSION, params, {
             success: function (data) {
               connect.getLog().info("updateSpeakerIdInVoiceId succeeded").withObject(data).sendInternalLogToServer();
-              self._updateSpeakerIdInLcms(speakerId, data.generatedSpeakerId)
+              var generatedSpeakerId = data && data.Session && data.Session.GeneratedSpeakerId;
+              self._updateSpeakerIdInLcms(speakerId, generatedSpeakerId)
                 .then(function() {
                   resolve(data);
                 })
@@ -27482,7 +27483,7 @@ AWS.apiLoader.services['connect']['2017-02-15'] = require('../apis/connect-2017-
 
   connect.core = {};
   connect.core.initialized = false;
-  connect.version = "2.4.1";
+  connect.version = "2.4.2";
   connect.DEFAULT_BATCH_SIZE = 500;
 
   var CCP_SYN_TIMEOUT = 1000; // 1 sec

src/api.js

@@ -1846,7 +1846,8 @@
         client.call(connect.AgentAppClientMethods.UPDATE_SESSION, params, {
             success: function (data) {
               connect.getLog().info("updateSpeakerIdInVoiceId succeeded").withObject(data).sendInternalLogToServer();
-              self._updateSpeakerIdInLcms(speakerId, data.generatedSpeakerId)
+              var generatedSpeakerId = data && data.Session && data.Session.GeneratedSpeakerId;
+              self._updateSpeakerIdInLcms(speakerId, generatedSpeakerId)
                 .then(function() {
                   resolve(data);
                 })

test/unit/voiceid.spec.js

@@ -1161,7 +1161,11 @@ describe('VoiceId', () => {
 
   describe('updateSpeakerIdInVoiceId', () => {
     it('should get resolved with data', async () => {
-      const response = 'fakeData';
+      const response = {
+        Session: {
+          GeneratedSpeakerId: 'dummy-generated-speaker-id'
+        }
+      };
       sinon.stub(connect.core, 'getClient').callsFake(() => ({
         call: (endpoint, params, callbacks) => {
           callbacks.success(response);
@@ -1175,7 +1179,7 @@ describe('VoiceId', () => {
       expect(obj).to.equal(response);
       sinon.assert.calledOnce(voiceId.checkConferenceCall);
       sinon.assert.calledOnce(voiceId.getDomainId);
-      sinon.assert.calledOnce(voiceId._updateSpeakerIdInLcms);
+      sinon.assert.calledWith(voiceId._updateSpeakerIdInLcms, speakerId, 'dummy-generated-speaker-id');
       connect.core.getClient.restore();
     });