New Case Study:See how Anthropic automated 95% of dependency reviews with Socket.Learn More →

amazon-connect-chatjs

Package Overview

Dependencies

Advanced tools

Install Socket

Detect and block malicious and high-risk dependencies

Install

amazon-connect-chatjs

Provides chat support to AmazonConnect customers

3.0.3
latest
Source
npm

Version published: last month

Maintainers: 0

Created: 5 years ago

Source

Amazon Connect ChatJS

Important note: Amazon Connect has migrated the Connection Acknowledgement(ConnAck) from the SendEvent API to the CreateParticipant API. Please upgrade your ChatJS to 1.4.0 or a newer version to complete the migration by 12/31/2024.

About

The Amazon Connect Chat javascript library (ChatJS) gives you the power to build your own chat widget to customize the chat experience. This can be used for both the agent user interface, in conjunction with Amazon Connect Streams, and for the customer chat interface.

There is a Chat UI reference implementation here. This will help you deploy an API Gateway and Lambda function for initiating chat from your webpage. From there you can use the ChatJS library to build a custom widget.

Learn More

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

New to Amazon Connect and looking to onboard with Chat/Messaging capabilities? Refer to the “Amazon Connect Chat Open Source Walkthrough” documentation, and “Hosted Widget vs Custom Builder Solution” if building a customer-facing chat interface.

Getting Started

A note about the AWS-SDK and ChatJS

The AWS-SDK is, by default, included in ChatJS as a "baked-in" dependency. You can view it at ./client/aws-sdk-connectparticipant.js. In ./client/client.js we import ConnectParticipant from this file. This file and import can be removed while using the AWS SDK imported through a script in the page file of your application, assuming that version of the AWS SDK has the ConnectParticipant service included. Incidentally, Amazon Connect Streams also contains a "baked-in" AWS SDK. This SDK cannot be removed, as it contains unreleased APIs that will not be available in the SDK you include as a script in the page file. Therefore, there are several occasions where implementations can run into AWS SDK issues.

Scenario 1: Streams and ChatJS are used. You are not importing the AWS SDK

Ensure you import ChatJS after Streams.

Scenario 2: Streams and ChatJS are used. You are importing the AWS SDK

Import Streams, then ChatJS, then the SDK. Ensure that your AWS SDK includes the ConnectParticipant Service (it is relatively new, so make sure you have an up-to-date AWS SDK version [^2.597.0]).

Scenario 3: ChatJS only, no AWS SDK import

No need to worry here, this will always work.

Scenario 4: ChatJS only, with AWS SDK import

Import ChatJS before the AWS SDK, and ensure the AWS SDK version you are using contains the ConnectParticipant Service.

A note for Scenarios 2 and 4

When using the SDK and ChatJS, you may remove the SDK from ChatJS to ensure lack of import conflicts. However, this should not be relevant if the order in which you are importing these libraries is the order reflected above.

Using AWS SDK ConnectParticipant Client

If you have replaced ./client/aws-sdk-connectparticipant.js and use @aws-sdk/client-connectparticipant, make sure to import the aws-sdk after ChatJS

import 'amazon-connect-streams'; // <-- (optional) MUST be before ChatJS
import 'amazon-connect-chatjs';
import '@aws-sdk/client-connect'; // or 'aws-sdk'
import '@aws-sdk/clients/connectparticipant'; // <-- IMPORTANT - should be last

Usage

Using ChatJS from npm

npm install amazon-connect-chatjs

Using ChatJS from CDN Link

amazon-connect-chat.js bundle file is also available over a CDN.

<script src="https://unpkg.com/amazon-connect-chatjs@1.5.1"></script>
<!-- OR -->
<script src="https://cdn.jsdelivr.net/npm/amazon-connect-chatjs@1.5.1/dist/amazon-connect-chat.js"></script>

<!-- Specify exact version -->
<script src="https://unpkg.com/amazon-connect-chatjs@1.5.1"></script>
<script src="https://unpkg.com/amazon-connect-chatjs@1"></script>
<script src="https://unpkg.com/amazon-connect-chatjs"></script>

<!-- Use crossorigin if needed -->
<script crossorigin src="https://unpkg.com/amazon-connect-chatjs"></script>

Importing using npm and ES6

import "amazon-connect-chatjs" Note: this will apply the global connect variable to your current scope.

TypeScript Support

amazon-connect-chatjs is compatible with TypeScript. You'll need to use version typescript@^3.0.1 or higher:

import "amazon-connect-streams";

connect.ChatSession.create({ /* ... */ });

Using ChatJS from Github

git clone https://github.com/amazon-connect/amazon-connect-chatjs

Building

Install latest LTS version of NodeJS
Checkout this package into workspace and navigate to root folder
npm install
To build (non-minified):
1. npm run devo for a non-minified build.
2. Find build artifacts in dist directory.
To build (minified):
1. npm run release for a minified build.
2. Find build artifacts in dist directory.
To run unit tests:
1. npm run test
To clean node_modules:
1. npm run clean
To make webpack watch all files:
1. npm run watch

Find build artifacts in dist directory - This will generate a file called amazon-connect-chat.js - this is the full Connect ChatJS API which you will want to include in your page.

React Native Support

Additional configuration is required to support ChatJS in React Native applications. Use amazon-connect-chatjs@^1.5.0 and follow the documenation: ReactNativeSupport.md

A demo application implementing basic ChatJS functionality is also available in the ui-examples repository: connectReactNativeChat

API

`connect.ChatSession` API

This is the main entry point to amazon-connect-chatjs. All your interactions with the library start here.

`connect.ChatSession.setGlobalConfig()`

connect.ChatSession.setGlobalConfig({
  loggerConfig: { // optional, the logging configuration. If omitted, no logging occurs
    // You can provide your own logger here, otherwise this property is optional
    customizedLogger: {
      debug: (...msg) => console.debug(...msg), // REQUIRED, can be any function
      info: (...msg) => console.info(...msg), // REQUIRED, can be any function
      warn: (...msg) => console.warn(...msg), // REQUIRED, can be any function
      error: (...msg) => console.error(...msg) // REQUIRED, can be any function
    },
    // There are five levels available - DEBUG, INFO, WARN, ERROR, ADVANCED_LOG. Default is INFO
    level: connect.LogLevel.INFO,
    // Choose if you want to use the default logger
    useDefaultLogger: true
  },
  region: "us-east-1", // optional, defaults to: "us-west-2"
  //Control switch for enabling/disabling message-receipts (Read/Delivered) for messages
  //message receipts use sendEvent API for sending Read/Delivered events https://docs.aws.amazon.com/connect-participant/latest/APIReference/API_SendEvent.html
  features: {
    messageReceipts: {
      shouldSendMessageReceipts: true, // DEFAULT: true, set to false to disable Read/Delivered receipts
      throttleTime: 5000 //default throttle time - time to wait before sending Read/Delivered receipt.
    }
  }
});

Set the global configuration to use. If this method is not called, the defaults of loggerConfig and region are used. This method should be called before connect.ChatSession.create().

Customizing loggerConfig for ChatJS:

If you don't want to use any logger, you can skip this field.
There are five log levels available - DEBUG, INFO, WARN, ERROR, ADVANCED_LOG.
If you want to use your own logger, you can add them into customizedLogger, and add customizedLogger object as the value of loggerConfig.customizedLogger, then set the lowest logger level. globalConfig.loggerConfig.useDefaultLogger is not required.
If you want to use the default logger provided by ChatJS, you can set the logger level, and set useDefaultLogger to true. loggerConfig.customizedLogger is not required.
If you not only provide your own logger, but also set useDefaultLogger to true, your own logger will be overwritten by the default logger.
amazon-connect-chatjs/src/log.js - has the logic to select LogLevel. Default value is INFO - which cause all logs with higher priority than INFO to be logged. eg: by default info, warn, error and advancedLog messages will be logged.
Priority of logs: 10: "DEBUG" 20: "INFO" 30: "WARN" 40: "ERROR" 50: "ADVANCED_LOG"

`connect.ChatSession.create()`

const customerChatSession = connect.ChatSession.create({
  chatDetails: { // REQUIRED
    contactId: "...", // REQUIRED
    participantId: "...", // REQUIRED
    participantToken: "...", // REQUIRED
  },
  options: { // optional
    region: "us-east-1", // optional, defaults to `region` set in `connect.ChatSession.setGlobalConfig()`
  },
  type: "CUSTOMER", // REQUIRED
});

Creates an instance of AgentChatSession or CustomerChatSession, depending on the specified type.

If you're creating a CustomerChatSession, the chatDetails field should be populated with the response of the StartChatContact API.

If you're creating an AgentChatSession, you must also include amazon-connect-streams. For example:

// order is important, alternatively use <script> tags
import "amazon-connect-streams";
import "amazon-connect-chatjs";

connect.contact(contact => {
  if (contact.getType() !== connect.ContactType.CHAT) {
    // applies only to CHAT contacts
    return;
  }

  // recommended: calls `connect.ChatSession.setGlobalConfig()` and `connect.ChatSession.create()` internally
  contact.onAccepted(async () => {
    const cnn = contact.getConnections().find(cnn => cnn.getType() === connect.ConnectionType.AGENT);

    const agentChatSession = await cnn.getMediaController();
  });

  // alternative: if you want control over the args of `connect.ChatSession.setGlobalConfig()` and `connect.ChatSession.create()`
  contact.onAccepted(() => {
    const cnn = contact.getConnections().find(cnn => cnn.getType() === connect.ConnectionType.AGENT);

    const agentChatSession = connect.ChatSession.create({
      chatDetails: cnn.getMediaInfo(), // REQUIRED
      options: { // REQUIRED
        region: "us-east-1", // REQUIRED, must match the value provided to `connect.core.initCCP()`
      },
      type: connect.ChatSession.SessionTypes.AGENT, // REQUIRED
      websocketManager: connect.core.getWebSocketManager() // REQUIRED
    });
  });
});

See the amazon-connect-streams API documentation for more information on the methods not documented here.

Note: AgentChatSession and CustomerChatSession are logical concepts. As a result, the instanceof operator will not work how you expect:

if (connect.ChatSession.create(/* ... */) instanceof connect.ChatSession) {
  // this will never execute
}

`connect.ChatSession.LogLevel`

connect.ChatSession.LogLevel = {
  DEBUG: /* ... */,
  INFO: /* ... */,
  WARN: /* ... */,
  ERROR: /* ... */
};

Enumerates the logging levels.

`connect.ChatSession.SessionTypes`

connect.ChatSession.SessionTypes = {
  AGENT: /* ... */,
  CUSTOMER: /* ... */
};

Enumerates the session types.

ChatSession API

The ChatSession API divided into three sections: Amazon Connect Participant Service API wrappers, events, and other.

Amazon Connect Participant Service API wrappers

Functions in this section:

Wrap the APIs of the Amazon Connect Participant Service.
Return a Promise<Response> (except for chatSession.connect()), where:
- Response is an aws-sdk Response object.
- If the Promise rejects, the error will still be a Response object. However, the data field will not be populated while the error field will.
Can optionally specify a metadata arg field (except for customerChatSession.disconnectParticipant()). The metadata arg field is not used directly by amazon-connect-chatjs, rather it's merely copied to the response object for usage by developers.

For example:

function handleResponse(response) {
  // `response` is an aws-sdk `Response` object
  // `data` contains the response data
  // `metadata` === "foo"
  const { data, metadata } = response;
  // ...
}

function handleError(response) {
  // `response` is an aws-sdk `Response` object
  // `error` contains the response error
  // `metadata` === "foo"
  const { error, metadata } = response;
  // ...
}

chatSession
  .getTranscript({ metadata: "foo" })
  .then(handleResponse, handleError);

`chatSession.connect()`

// connectCalled: indicates whether the Amazon Connect Participant Service was called
// connectSuccess: indicates whether the operation succeeded
const { connectCalled, connectSuccess } = await chatSession.connect();

Wraps the CreateParticipantConnection API.

The arguments and response do not overlap with the API request or response.

Note: If the operation fails, the Promise will reject, but the error will have the same schema as a successful response.

`chatSession.getTranscript()`

const awsSdkResponse = await chatSession.getTranscript({
  maxResults: 100,
  sortOrder: "ASCENDING"
});
const { InitialContactId, NextToken, Transcript } = awsSdkResponse.data;

Wraps the GetTranscript API.

The arguments are based on the API request body with the following differences:

Fields are in camelCase.
MaxResults defaults to 15.
ScanDirection defaults to BACKWARD always.
SortOrder defaults to ASCENDING.