Comment configurer un widget de chat dans mon application pour qu’il interagisse directement avec les API Amazon Connect et Amazon Connect Participant Service ?

Solution

Pour permettre à vos clients d’initier des contacts de chat directement depuis votre application à l’aide des API Amazon Connect et Amazon Connect Participant Service, procédez comme suit :

Appel de l’API StartChatContact d’Amazon Connect lorsqu’un client démarre un contact de chat

Configurez votre application pour appeler l’API StartChatContact d’Amazon Connect lorsqu’un client démarre un contact de chat. La réponse de l’API renvoie une valeur ParticipantToken. Cette valeur est requise pour appeler l’API CreateParticipantConnection.

Important : le client qui effectue l’appel d’API doit disposer des autorisations nécessaires dans Gestion des identités et des accès AWS (AWS IAM) pour exécuter l’action connect:StartChatContact.

Utilisez le modèle AWS CloudFormation amazon-connect-chat-ui-examples sur le site web de GitHub pour déployer les ressources nécessaires à l’appel d’API StartChatContact. Ce modèle crée un point de terminaison Amazon API Gateway qui invoque une fonction AWS Lambda incluant les autorisations IAM requises. La fonction AWS Lambda invoque l’API StartChatContact d’Amazon Connect et renvoie le résultat de cet appel.

Exemple de requête d’API StartChatContact (JavaScript)

Si vous utilisez axios dans votre application, utilisez le code JavaScript suivant pour appeler l’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
    }
  }
);

Pour plus d’informations, consultez la commande axios sur le site web de GitHub.

Appel de l’API CreateParticipantConnection d’Amazon Connect Participant Service et transmission de la valeur ParticipantToken

Configurez votre application pour appeler l’API CreateParticipantConnection d’Amazon Connect Participant Service une fois le contact de chat initié.

Lorsque vous invoquez l’API CreateParticipantConnection, elle renvoie une URL WebSocket ainsi qu’une valeur ConnectionToken. Les clients doivent se connecter manuellement à l’URL WebSocket et s’abonner au topic souhaité, « aws/chat », afin d’établir la connexion du participant au chat.

Remarque : les API Amazon Connect Participant Service n’utilisent pas l’authentification Signature Version 4. Pour la valeur de l’en-tête de requête X-Amz-Bearer, utilisez à la place la valeur ParticipantToken ou ConnectionToken. La valeur ParticipantToken est utilisée uniquement pour appeler l’API CreateParticipantConnection. Les autres API d’Amazon Connect Participant Service nécessitent que vous transmettiez la valeur ConnectionToken.

Exemple de requête d’API CreateParticipantConnection (JavaScript) :

Si vous utilisez axios dans votre application, utilisez le code JavaScript suivant pour appeler l’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
});

Création d’une connexion WebSocket avec l’URL WebSocket renvoyée et abonnement de l’application au topic « aws/chat »

Après avoir invoqué l’API CreateParticipantConnection, le client doit se connecter manuellement à l’URL WebSocket renvoyée et s’abonner au topic « aws/chat ».

Pour plus d’informations, consultez la section CreateParticipantConnection de la référence d’API Amazon Connect Participant Service.

Exemple de code JavaScript permettant de créer une connexion WebSocket et d’abonner un client au topic « 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))
});

Réception d’événements et de messages de chat via la connexion WebSocket

Une fois la connexion WebSocket ouverte et l’abonnement au topic « aws/chat » effectué, vous pouvez recevoir des événements et des messages de chat via le WebSocket. Pour ce faire, ajoutez un écouteur d’événements pour l’événement « message ».

Exemple de code JavaScript permettant de créer un écouteur d’événements pour l’événement « 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
    }
  }
}

Pour plus d’informations sur la structure de l’objet responseMessage, consultez la section Item de la documentation Amazon Connect.

Envoi de messages ou d’événements de chat via les API Amazon Connect Participant Service

Remarque : vous ne pouvez pas envoyer de messages ou d’événements directement via la connexion WebSocket. Vous devez utiliser l’une des API Amazon Connect Participant Service à la place.

Pour envoyer des messages de chat, appelez l’API SendMessage d’Amazon Connect Participant Service. Pour envoyer des événements, appelez l’API SendEvent d’Amazon Connect Participant Service.

Important : pour l’en-tête de requête X-Amz-Bearer, utilisez la valeur ConnectionToken renvoyée par l’API CreateParticipantConnection.

Exemple de requête d’API SendMessage (JavaScript)

Si vous utilisez axios dans votre application, utilisez le code JavaScript suivant pour appeler l’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
  });

Exemple de requête d’API SendEvent (JavaScript)

Si vous utilisez axios dans votre application, utilisez le code JavaScript suivant pour appeler l’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
});