Comment configurer un widget de chat pour mon application qui interagit de manière native avec les API Amazon Connect et Amazon Connect Participant Service ?

Résolution

Pour initier des contacts de chat avec les clients directement à partir de votre application en utilisant les API Amazon Connect et Amazon Connect Participant Service, configurez votre application de la manière suivante.

Appeler l'API Amazon Connect StartChatContact lorsqu'un client initie un contact par chat

Configurez votre application pour appeler l'API Amazon Connect StartChatContact lorsqu'un client initie un contact par chat. La réponse de l'API renvoie une valeur ParticipantToken qui est requise pour appeler l'API CreateParticipantConnection à l'étape suivante.

Important : le client qui effectue l'appel d'API doit disposer des autorisations AWS Identity and Access Management (IAM) pour effectuer l'action Connect:StartChatContact.

Pour déployer les ressources requises pour appeler l'API StartChatContact à partir de votre application, vous pouvez utiliser le modèle AWS CloudFormation suivant sur GitHub : amazon-connect-chat-ui-examples. Le modèle crée un point de terminaison Amazon API Gateway qui appelle une fonction AWS Lambda incluant les autorisations IAM requises. La fonction AWS Lambda appelle l'API StartChatContact d'Amazon Connect et renvoie le résultat de cet appel.

Exemple de demande d'API StartChatContact (JavaScript)

Si vous utilisez axios dans votre application, vous pouvez utiliser 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" // This is going to be a display name of your customer during a chat contact
    }
  }
);

Appeler l'API CreateParticipantConnection Amazon Connect Participant Service et transmettre la valeur ParticipantToken

Configurez votre application pour appeler l'API CreateParticipantConnection Amazon Connect Participant Service après l'établissement d'un contact par chat.

L'appel de l'API CreateParticipantConnection renvoie une URL WebSocket et un ConnectionToken. Les clients doivent se connecter manuellement à l'URL WebSocket et s'abonner au sujet souhaité (« aws/chat ») pour créer la connexion du participant au chat.

Remarque : les API Amazon Connect Participant Service n'utilisent pas l'authentification Signature Version 4. Pour la valeur d'en-tête de demande X-Amz-Bearer, vous devez utiliser la valeur ParticipantToken ou ConnectionToken à la place. La valeur ParticipantToken est utilisée uniquement lors de l'appel de l'API CreateParticipantConnection. Les autres API 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, vous pouvez utiliser 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éez une connexion WebSocket à l'aide de l'URL WebSocket renvoyée et abonnez l'application à la rubrique « aws/chat »

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

Pour plus d'informations, consultez CreateParticipantConnection dans lea Référence d'API Amazon Connect Participant Service.

Exemple de code JavaScript qui crée une connexion WebSocket et abonne un client à 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))
});

Envoyez des messages ou des événements de chat en appelant 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 discussion, appelez l'API Amazon Connect Participant Service SendMessage.

-ou-

Pour envoyer des événements, appelez l'API Amazon Connect Participant Service SendEvent.

Important : pour l'en-tête de demande X-Amz-Bearer, assurez-vous d'utiliser la valeur ConnectionToken renvoyée par l'API CreateParticipantConnection.

Exemple de demande d'API SendMessage (JavaScript)

Si vous utilisez axios dans votre application, vous pouvez utiliser 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, vous pouvez utiliser 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
});

---