What’s New with Streams API v1.4

With the release of the new chat functionality in Amazon Connect, the Amazon Connect Streams API also got an update. This update provides easy access to chat interactions by supplying new action methods and event handlers.   

Media Controller API for Chat

Media Controller is an API that allows for simple chat interactions such as receiving and sending messages, retrieving transcripts, and subscribing to events.

Usage

To initialize a media controller instance, it uses the contact ID and the connection Id of the contact. We also want to make sure the contact is connected to an agent and the media type is chat, before initializing the instance.

function handleContactConnected(contact) {
  if (contact) {
      console.log("[contact.onConnected] Contact connected to an agent. Contact state is " + contact.getStatus().type);

      if (contact.getAgentConnection().getMediaType() === connect.MediaType.CHAT) {
        contact.getAgentConnection().getMediaController()
          .then(controller => {
            // The media controller which provides methods
            // for easy chat interactions.

          })
      }
  }
}

Event / Action Methods

onMessage(cb)

Listens for all incoming messages that are sent between the customer and the agent.

Parameters:

• Callback – Function * Required

controller.onMessage(function (response, contentType) {
  if (response.data.ParticipantRole === 'CUSTOMER') {
    // Handle customer interaction
  }
});

Response: Inside the data object of the response, you are able to see whether the message is coming from the agent or the customer, as well as the content of the message. The content/event type will be “INCOMING MESSAGE”.

Use Case:

Build a custom Agent Chat window by sorting out the messages from the customer and the agent.

sendMessage({ message: “text”, contentType: “text/plain” })

Sends a message to the recipient. Both the message and the content type are necessary.

Parameters:

• message – String * Required
• contentType – String * Required

getTranscript({ maxResults: 15, sortOrder : “ASCENDING” })

Retrieve messages and events that occurred within the contact. * Only available if the contact still exists.

Parameters:

• maxResults – Number * Optional
  • Default is 15
• sortOrder – String * Optional
  • Default is “ASCENDING”

controller.getTranscript({ maxResults: 30, sortOrder: "DESCENDING"})
  .then(response => {
    // Array of Transcripts
    response.data.Transcript.forEach(transcript => {
      if (transcript.ParticipantRole === 'AGENT' && transcript.Type === 'MESSAGE') {
        // Agent Messages
      }

      if (transcript.ParticipantRole === 'CUSTOMER' && transcript.Type === 'MESSAGE') {
        // Customer messages
      }
   });
  })
  .catch(err => {
    // Handle error
  })

Response: Each transcript shows either the event that occurred, such as when the customer joined, or the details of the message, such as the content and    identification of the sender.

Use Case:

Show the history of the conversation to an agent to provide a better customer experience.

sendEvent({ contentType: “event” })

Send events to the customer to provide additional information, such as when the agent is typing or when the agent leaves the chat.

Parameters:

• contentType – String * Required
• Available content types
  • Typing: application/vnd.amazonaws.connect.event.typing
  • Participant Joined: application/vnd.amazonaws.connect.event.participant.joined
  • Participant Left: application/vnd.amazonaws.connect.event.participant.left
  • Transfer Succeeded: application/vnd.amazonaws.connect.event.transfer.succeed
  • Transfer Failed: application/vnd.amazonaws.connect.event.transfer.failed
  • Acknowledge: application/vnd.amazonaws.connect.event.connection.acknowledged
  • Chat Ended: application/vnd.amazonaws.connect.event.chat.ended

controller.sendEvent({ contentType: "application/vnd.amazonaws.connect.event.typing" })
  .then(res => {
    // Response from sending an agent typing event to the customer
  })
  .catch(err => {
    // Handle error
  })

Use Case:

Let the customer know if the agent is typing to provide a better user experience.

View Contact API

View Contact API provides the ability to switch between contacts in the CCP. This functionality works across media types and contacts.

core.viewContact(“contactID”)

The method allows you to switch to the specified contact whether it’s a chat or a phone conversation.

Parameters:

• contactId – String * Required

core.onViewContact(cb)

Subscribe a method to be called when the viewContact method is invoked to switch to a different contact.

Parameters:

• Callback – Function * Required

Response: The response is the contact id of the contact that the agent just switched to.

connect.core.onViewContact(function (contact) {
  // The contact that the agent just switched to
});

New Event Handlers

core.onAuthFail(cb)

Helpful for the custom and embedded CCPs to handle the auth failure and custom login use cases.

Parameter: Callback – Function * Required

connect.core.onAuthFail(function () {
  // agent logged out or session expired.  needs login
  // show button for login or popup a login screen.
});

core.onAccessDenied(cb)

Helpful for the custom and embedded CCPs to know about the access denied use case where agent does not have permission to CCP as per the security profile.

Parameter: Callback – Function * Required

connect.core.onAccessDenied(function () {
  // Agent does not have permission to the CCP. Show access denied page.
});

subscribe(connect.WebSocketEvents.ALL_MESSAGE, cb)

Subscribe a method to be called when an event or a message is sent between the agent and the customer.

Parameters: Callback – Function * Required

bus.subscribe(connect.WebSocketEvents.ALL_MESSAGE, function (websocketEvent) {
  const parsedWebSocketEvent = JSON.parse(websocketEvent.content);

  if (
    parsedWebSocketEvent.ContentType === "application/vnd.amazonaws.connect.event.typing"
    && parsedWebSocketEvent.ParticipantRole === "CUSTOMER"
  ) {
    // Show on the custom chat window that the customer is typing.
  }
});

Response: The event or the message is passed through as a JSON string within the content key of the response. The response also shows the media type as a topic.

Within the content object, it shows the timestamp of the event, the type of event or the message that was sent, the contact Id, and as well as the identification of the sender.

subscribe(connect.WebSocketEvents.CONNECTION_GAIN, cb)

Subscribe a method to be called when the websocket connection is connected.

Parameters: Callback – Function * Required

bus.subscribe(connect.WebSocketEvents.CONNECTION_GAIN, function () {
  // Websocket Connection Gained
});

subscribe(connect.WebSocketEvents.CONNECTION_LOST, cb)

Subscribe a method to be called when the websocket connection is lost.

Parameters: Callback – Function * Required

bus.subscribe(connect.WebSocketEvents.CONNECTION_LOST, function ()  {
  // Websocket Connection Lost
});

For information on how Perficient can help you integrate Amazon Connect chat into your contact center, please contact us here.