¿Cómo configuro un widget de chat para mi aplicación que interactúa de forma nativa con las API de Amazon Connect y Amazon Connect Participant Service?

Resolución

Para iniciar contactos por chat con clientes de forma directa desde su aplicación mediante las API de Amazon Connect y Amazon Connect Participant Service, configure su aplicación de manera que haga lo siguiente.

Llamar a la API StartChatContact de Amazon Connect cuando un cliente inicie un contacto por chat

Configure su aplicación para que llame a la API StartChatContact de Amazon Connect cuando un cliente inicie un contacto por chat. La respuesta de la API devuelve un valor ParticipantToken que es necesario para llamar a la API CreateParticipantConnection en el siguiente paso.

Importante: El cliente que realiza la llamada a la API debe contar con los permisos de AWS Identity and Access Management (IAM) necesarios para realizar la acción connect:StartChatContact.

Para implementar los recursos necesarios para llamar a la API StartChatContact desde su aplicación, puede utilizar la siguiente plantilla de AWS CloudFormation en GitHub:amazon-connect-chat-ui-examples. La plantilla crea un punto de conexión de Amazon API Gateway que invoca una función de AWS Lambda, la cual incluye los permisos de IAM necesarios. La función de AWS Lambda invoca la API StartChatContact de Amazon Connect y devuelve el resultado de esa llamada.

Ejemplo de solicitud a la API StartChatContact (JavaScript)

Si utiliza axios en su aplicación, puede utilizar el siguiente código JavaScript para llamar a la API StartChatContact:

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

Llamar a la API CreateParticipantConnection de Amazon Connect Participant Service y transmitir el valor ParticipantToken

Configure su aplicación para que llame a la API CreateParticipantConnection de Amazon Connect Participant Service después de que se inicia un contacto por chat.

La invocación de la API CreateParticipantConnection devuelve una dirección URL de WebSocket y el ConnectionToken. Los clientes deben conectarse de forma manual a la dirección URL de WebSocket y suscribirse al tema deseado (“aws/chat”) para crear la conexión del participante por chat.

Nota: Las API de Amazon Connect Participant Service no utilizan la autenticación Signature Version 4. Para el valor del encabezado de la solicitud X-Amz-Bearer, debe utilizar el valor ParticipantToken o ConnectionToken en su lugar. El valor ParticipantToken se utiliza solo cuando se llama a la API CreateParticipantConnection. Otras API de Amazon Connect Participant Service necesitan que transmita el valor ConnectionToken.

Ejemplo de solicitud a la API CreateParticipantConnection (JavaScript)

Si utiliza axios en su aplicación, puede utilizar el siguiente código JavaScript para llamar a la API CreateParticipantConnection:

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

Crear una conexión de WebSocket con la dirección URL de WebSocket que se devolvió y suscribir la aplicación al tema “aws/chat”

Después de invocar la API CreateParticipantConnection, el cliente debe conectarse de forma manual a la dirección URL de WebSocket que se devolvió y suscribirse al tema “aws/chat”.

Para obtener más información, consulte CreateParticipantConnection en la Referencia de la API de Amazon Connect Participant Service.

Ejemplo de código JavaScript que crea una conexión de WebSocket y suscribe a un cliente al tema “aws/chat”

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

Enviar mensajes o eventos por chat mediante llamadas a las API de Amazon Connect Participant Service

Nota: No se pueden enviar mensajes ni eventos de forma directa a través de la conexión de WebSocket. En su lugar, se debe utilizar una de las API de Amazon Connect Participant Service.

Para enviar mensajes por chat, llame a la API SendMessage de Amazon Connect Participant Service.

-o bien-

Para enviar eventos, llame a la API SendEvent de Amazon Connect Participant Service.

Importante: Para el encabezado de la solicitud X-Amz-Bearer, asegúrese de utilizar el valor ConnectionToken que devuelve la API CreateParticipantConnection.

Ejemplo de solicitud a la API SendMessage (JavaScript)

Si utiliza axios en su aplicación, puede utilizar el siguiente código JavaScript para llamar a la API SendMessage:

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

Ejemplo de solicitud a la API SendEvent (JavaScript)

Si utiliza axios en su aplicación, puede utilizar el siguiente código JavaScript para llamar a la API SendEvent:

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

---