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

Last updated: 2022-03-22

I want to create a chat widget for an application that natively interacts with Amazon Connect and Amazon Connect Participant Service APIs. How do I set that up?

Resolution

To initiate customer chat contacts directly from your application using Amazon Connect and Amazon Connect Participant Service APIs, configure your application to 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 that's required to call the CreateParticipantConnection API in the next step.

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

To deploy the resources required to call the StartChatContact API from your application, you can use the following AWS CloudFormation template on GitHub: amazon-connect-chat-ui-examples. 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're using axios in your application, you can 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" // This is going to be a display name of your customer during a chat contact
    }
  }
);

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.

Invoking the CreateParticipantConnection API 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 when calling the CreateParticipantConnection API only. Other Amazon Connect Participant Service APIs require you to pass the ConnectionToken value.

Example CreateParticipantConnection API request (JavaScript)

If you're using axios in your application, you can 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 using the returned WebSocket URL and subscribe the application to the "aws/chat" topic

After invoking 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))
});

Send chat messages or events by calling 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, make sure that you use the ConnectionToken value that's returned by the CreateParticipantConnection API.

Example SendMessage API request (JavaScript)

If you're using axios in your application, you can 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're using axios in your application, you can 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
});

Did this article help?


Do you need billing or technical support?