Comment puis-je configurer un widget de communication dans mon application qui interagit naturellement via les API Amazon Connect et Amazon Connect Participant Service ?

Résolution

Pour initier une discussion en ligne avec un client directement à partir de votre application à l’aide des API Amazon Connect et Amazon Connect Participant Service, procédez comme suit :

Appeler l’API Amazon Connect StartChatContact lorsqu’un client initie une discussion en ligne

Configurez votre application pour appeler l’API Amazon Connect StartChatContact lorsqu’un client initie une discussion en ligne. 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 de 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 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 appelle l’API Amazon Connect StartChatContact et renvoie le résultat de cet appel.

Exemple de demande 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.

Appelez l’API CreateParticipantConnection d’Amazon Connect Participant Service et transmettez la valeur ParticipantToken

Configurez votre application pour appeler l'API CreateParticipantConnection d’Amazon Connect Participant Service après l’initiation d’une discussion en ligne.

Lorsque vous invoquez l’API CreateParticipantConnection, elle renvoie une URL WebSocket et une valeur ConnectionToken. Les clients doivent se connecter manuellement à l’URL WebSocket et s’abonner à la rubrique sélectionnée (« aws/chat ») pour créer la liaison avec le participant en ligne.

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, vous devez plutôt utiliser 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 demande d’API CreateParticipantConnection (JavaScript) :

Si vous utilisez axios dans votre application, saisissez 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éer une connexion WebSocket avec l’URL WebSocket renvoyée et enregistrer l’application sous la rubrique « aws/chat »

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

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

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

Recevoir des événements et des messages en ligne en vous servant d’une connexion WebSocket

Une fois que vous avez ouvert la connexion WebSocket et que vous vous êtes abonné à la rubrique « aws/chat », vous pouvez y recevoir des événements et des messages en ligne. 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 Item dans la documentation Amazon Connect.

Envoyer des messages ou des événements 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 plutôt utiliser l’une des API Amazon Connect Participant Service.

Pour envoyer des messages en ligne, appelez l’API SendMessage d’Amazon Connect Participant Service. Ou, si vous souhaitez envoyer des événements, appelez l’API SendEvent d’Amazon Connect Participant Service.

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

Exemple de demande 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 demande 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
});