How do I set up a chat widget for my application that natively interacts with Amazon Connect and Amazon Connect Participant Service APIs?

Resolution

To initiate customer chat contacts directly from your application with Amazon Connect and Amazon Connect Participant Service APIs, do the following:

Call the StartChatContact Amazon Connect API when a customer initiates a chat contact

Configure your application to call the StartChatContact Amazon Connect API when a customer initiates a chat contact. The API response returns a ParticipantToken value. This value is required to call the CreateParticipantConnection API.

Important: The client that makes the API call must have AWS Identity and Access Management (IAM) permissions to perform the connect:StartChatContact action.

Use the amazon-connect-chat-ui-examples AWS CloudFormation template on the GitHub website to deploy the resources needed to call the StartChatContact API. The template creates an Amazon API Gateway endpoint that invokes an AWS Lambda function that includes the required IAM permissions. The AWS Lambda function invokes the Amazon Connect StartChatContact API and returns the result from that call.

Example StartChatContact API request (JavaScript)

If you use axios in your application, then use the following JavaScript code to call the StartChatContact API:

const startChatApi = "https://xxxxxxxxxx.execute-api.<region>.amazonaws.com/Prod"; // API endpoint you deployed with the CloudFormation template. 
...

axios.post(
  startChatApi,
  {
    ParticipantDetails: {
      DisplayName: "CUSTOMER" // A display name of your customer during a chat contact
    }
  }
);

For more information, see the axios command on the GitHub website.

Call the CreateParticipantConnection Amazon Connect Participant Service API and pass the ParticipantToken value

Configure your application to call the CreateParticipantConnection Amazon Connect Participant Service API after a chat contact is initiated.

When you invoke the CreateParticipantConnection API, it returns a WebSocket URL and ConnectionToken. Clients must manually connect to the WebSocket URL and subscribe to the desired topic ("aws/chat") to create the chat participant's connection.

Note: The Amazon Connect Participant Service APIs don't use Signature Version 4 authentication. For the X-Amz-Bearer request header value, you must use either the ParticipantToken or ConnectionToken value instead. The ParticipantToken value is used only to call the CreateParticipantConnection API. Other Amazon Connect Participant Service APIs require you to pass the ConnectionToken value.

Example CreateParticipantConnection API request (JavaScript):

If you use axios in your application, then use the following JavaScript code to call the CreateParticipantConnection API:

const participantServiceEndpoint = "https://participant.connect.<region>.amazonaws.com";// Replace <region> with the one that you are using. i.e. us-west-2. Endpoint list is available in https://docs.aws.amazon.com/general/latest/gr/connect_region.html

...

const requestHeaders = {
  "X-Amz-Bearer": "ParticipantToken", // Replace "ParticipantToken" with the one you obtained from the response of StartChatContact API
  "Content-type": "application/json"
};
const requestBody = {
  "Type": ["WEBSOCKET", "CONNECTION_CREDENTIALS"]
};

axios.post(participantServiceEndpoint + "/participant/connection", requestBody, {
  headers: requestHeaders
});

Create a WebSocket connection with the returned WebSocket URL and subscribe the application to the "aws/chat" topic

After you invoke the CreateParticipantConnection API, the client must manually connect to the returned WebSocket URL and subscribe to the "aws/chat" topic.

For more information, see CreateParticipantConnection in the Amazon Connect Participant Service API Reference.

Example JavaScript code that creates a WebSocket connection and subscribes a client to the "aws/chat" topic:

const ws = new WebSocket(websocketUrl); // Here, you use the websocket URL that you obtained from the response of CreateParticipantConnection API
const initialMessage = {
  topic: "aws/subscribe",
  content: {
    topics: ["aws/chat"]
  }
};
ws.addEventListener("open", () => {
  ws.send(JSON.stringify(initialMessage))
});

Receive chat events and messages through the WebSocket connection

After you open the WebSocket connection and subscribe to the "aws/chat" topic, you can receive chat events and messages through the WebSocket. To do this, add an event listener for the "message" event.

Example JavaScript code that creates an event listener for the "message" event:

ws.addEventListener("message", (event) => {
  // process event here
  const response = JSON.parse(event.data); 
  if (response.topic === "aws/chat") {
  const responseMessage = JSON.parse(response.content);
    if (responseMessage.Type === "MESSAGE") {
      // display message in interface here
    }
  }
}

For more information on the structure of the responseMessage object, see Item in the Amazon Connect documentation.

Send chat messages or events through Amazon Connect Participant Service APIs

Note: You can't send messages or events directly through the WebSocket connection. You must use one of the Amazon Connect Participant Service APIs instead.

To send chat messages, call the SendMessage Amazon Connect Participant Service API. Or, to send events, call the SendEvent Amazon Connect Participant Service API.

Important: For the X-Amz-Bearer request header, use the ConnectionToken value that's returned by the CreateParticipantConnection API.

Example SendMessage API request (JavaScript)

If you use axios in your application, then use the following JavaScript code to call the SendMessage API:

const requestHeaders = {  "X-Amz-Bearer": "ConnectionToken", // Replace "ConnectionToken" with the one you obtained from the response of CreateParticipantConnection API
  "Content-type": "application/json"
};
const requestBody = {
  "ClientToken": "unique string", // [Optional] A unique, case-sensitive identifier that you provide to ensure the idempotency of the request 
  "Content": message, // The actual chat message
  "ContentType": "text/plain", // Currently, supported type is text/plain
};

axios.post(participantServiceEndpoint + "/participant/message", requestBody, {
  headers: requestHeaders
  });

Example SendEvent API request (JavaScript)

If you use axios in your application, then use the following JavaScript code to call the SendEvent API:

const requestHeaders = {  "X-Amz-Bearer": "ConnectionToken", //Replace "ConnectionToken" with the one you obtained from the response of CreateParticipantConnection API
  "Content-type": "application/json"
};
const requestBody = {
  "ClientToken": "unique string", //[Optional] A unique, case-sensitive identifier that you provide to ensure the idempotency of the request 
  "ContentType": "application/vnd.amazonaws.connect.event.typing", //Typing event. You can specify "application/vnd.amazonaws.connect.event.connection.acknowledged" for acknowledged event
};

axios.post(participantServiceEndpoint + "/participant/event", requestBody, {
  headers: requestHeaders
});