Come faccio a configurare un widget di chat per la mia applicazione che interagisce in modo nativo con le API di Amazon Connect e Amazon Connect Participant Service?

Ultimo aggiornamento: 22-03-2022

Voglio creare un widget di chat per un'applicazione che interagisce in modo nativo con le API di Amazon Connect e Amazon Connect Participant Service. Come lo configuro?

Risoluzione

Per avviare i contatti di chat con i clienti direttamente dalla tua applicazione utilizzando le API Amazon Connect e Amazon Connect Participant Service, configura la tua applicazione per eseguire le seguenti operazioni.

Chiama l'API StartChatContact di Amazon Connect quando un cliente avvia un contatto tramite chat

Configura la tua applicazione in modo da chiamare l'API StartChatContact di Amazon Connect quando un cliente avvia un contatto di chat. La risposta API restituisce un valore ParticipantToken necessario per chiamare l'API CreateParticipantConnection nel passaggio successivo.

Importante: il client che sta effettuando la chiamata API deve disporre delle autorizzazioni AWS Identity and Access Management (IAM) per eseguire l'operazione connect:StartChatContact.

Per distribuire le risorse necessarie per chiamare l'API StartChatContact dalla tua applicazione, puoi utilizzare il seguente modello di AWS CloudFormation su GitHub: amazon-connect-chat-ui-examples. Il modello crea un endpoint Amazon API Gateway che richiama una funzione AWS Lambda che include le autorizzazioni IAM richieste. La funzione AWS Lambda richiama l'API StartChatContact di Amazon Connect e restituisce il risultato di quella chiamata.

Esempio di richiesta API StartChatContact (JavaScript)

Se utilizzi axios nella tua applicazione, puoi utilizzare il seguente codice JavaScript per chiamare 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
    }
  }
);

Chiama l'API CreateParticipantConnection di Amazon Connect Participant Service e passa il valore ParticipantToken

Configura l'applicazione per chiamare l'API CreateParticipantConnection di Amazon Connect Participant Service dopo l'avvio di un contatto di chat.

Il richiamo dell'API CreateParticipantConnection restituisce un URL WebSocket e un ConnectionToken. I client devono connettersi manualmente all'URL WebSocket e iscriversi all'argomento desiderato ("aws/chat") per creare la connessione del partecipante alla chat.

Nota: le API Amazon Connect Participant Service non utilizzano l'autenticazione Signature Version 4. Per il valore dell'intestazione della richiesta X-Amz-Bearer, è necessario utilizzare invece il valore ParticipantToken o ConnectionToken. Il valore ParticipantToken viene utilizzato solo quando si chiama l'API CreateParticipantConnection. Altre API di Amazon Connect Participant Service richiedono l’invio del valore ConnectionToken.

Esempio di richiesta API CreateParticipantConnection (JavaScript)

Se utilizzi axios nella tua applicazione, puoi utilizzare il seguente codice JavaScript per chiamare 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
});

Crea una connessione WebSocket utilizzando l'URL WebSocket restituito e sottoscrivi l'applicazione all'argomento "aws/chat"

Dopo aver richiamato l'API CreateParticipantConnection, il client deve connettersi manualmente all'URL WebSocket restituito e iscriversi all'argomento "aws/chat".

Per maggiori informazioni, consulta CreateParticipantConnection nella Documentazione di riferimento delle API di Amazon Connect Participant Service.

Esempio di codice JavaScript che crea una connessione WebSocket e sottoscrive un client all'argomento "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))
});

Invio di messaggi di chat o eventi chiamando le API di Amazon Connect Participant Service

Nota: non è possibile inviare messaggi o eventi direttamente tramite la connessione WebSocket. Devi invece utilizzare una delle API di Amazon Connect Participant Service.

Per inviare messaggi di chat, chiama l'API SendMessage di Amazon Connect Participant Service.

-oppure-

Per inviare eventi, chiama l'API SendEvent di Amazon Connect Participant Service.

Importante: per l'intestazione della richiesta X-Amz-Bearer, assicurati di utilizzare il valore ConnectionToken restituito dall'API CreateParticipantConnection.

Esempio di richiesta API SendMessage (JavaScript)

Se utilizzi axios nella tua applicazione, puoi utilizzare il seguente codice JavaScript per chiamare 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
});

Esempio di richiesta API SendEvent (JavaScript)

Se utilizzi axios nella tua applicazione, puoi utilizzare il seguente codice JavaScript per chiamare 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
});

Questo articolo è stato utile?


Hai bisogno di supporto tecnico o per la fatturazione?