¿Cómo configuro un widget de chat para mi aplicación que interactúe 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, 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.

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.

Utilice la plantilla Amazon connect-chat-ui-examples de AWS CloudFormation en el sitio web de GitHub para desplegar los recursos necesarios para llamar a la API StartChatContact. La plantilla crea un punto de enlace 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" // A display name of your customer during a chat contact
    }
  }
);

Para obtener más información, consulte el comando axios en el sitio web de GitHub.

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

Recibir eventos y mensajes de chat mediante la conexión WebSocket

Después de abrir la conexión de WebSocket y suscribirse al tema "aws/chat", puede recibir eventos y mensajes de chat mediante WebSocket. Para ello, añada un agente de escucha de eventos para el evento "message".

Ejemplo de código JavaScript que crea un agente de escucha de eventos para el evento "message":

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

Para obtener más información sobre la estructura del objeto «responseMessage», consulte Item en la documentación de Amazon Connect.

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