Wie richte ich ein Chat-Widget für meine Anwendung ein, das mit den APIs aus Amazon Connect und dem Amazon Connect Participant Service nativ interagiert?

Auflösung

Um Kunden-Chat-Kontakte mithilfe der APIs aus Amazon Connect und dem Amazon Connect Participant Service direkt von Ihrer Anwendung aus zu initiieren, konfigurieren Sie Ihre Anwendung so, dass sie Folgendes ausführt.

Aufruf der Amazon Connect-API StartChatContact, wenn ein Kunde einen Chat-Kontakt initiiert

Konfigurieren Sie Ihre Anwendung so, dass sie die Amazon Connect-API StartChatContact aufruft, wenn ein Kunde einen Chat-Kontakt initiiert. Die API-Antwort gibt einen ParticipantToken-Wert zurück, der zum Aufrufen der API CreateParticipantConnection im nächsten Schritt benötigt wird.

Wichtig: Der Client, der den API-Aufruf tätigt, muss über die entsprechenden Berechtigungen im AWS Identity and Access Management (IAM) verfügen, um die Aktion connect:StartChatContact ausführen zu können.

Zum Bereitstellen der Ressourcen, die zum Aufrufen der API StartChatContact von Ihrer Anwendung aus erforderlich sind, können Sie die folgende AWS CloudFormation-Vorlage auf GitHub verwenden: amazon-connect-chat-ui-examples. Die Vorlage erstellt einen Amazon API Gateway-Endpunkt, der eine AWS Lambda-Funktion mit den erforderlichen IAM-Berechtigungen aufruft. Die AWS Lambda-Funktion ruft die Amazon Connect-API StartChatContact auf und gibt das Ergebnis dieses Aufrufs zurück.

Beispiel einer Anforderung der API StartChatContact (JavaScript)

Wenn Sie axios in Ihrer Anwendung verwenden, können Sie die API StartChatContact mit dem folgenden JavaScript-Code aufrufen:

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

Aufruf der API CreateParticipantConnection aus dem Amazon Connect Participant Service und Übergabe des ParticipantToken-Werts

Konfigurieren Sie Ihre Anwendung so, dass die API CreateParticipantConnection aus dem Amazon Connect Participant Service aufgerufen wird, nachdem ein Chat-Kontakt initiiert wurde.

Beim Aufrufen der API CreateParticipantConnection werden eine WebSocket-URL und ein ConnectionToken zurückgegeben. Clients müssen sich manuell mit der WebSocket-URL verbinden und das gewünschte Thema („aws/chat“) abonnieren, um die Verbindung des Chat-Teilnehmers herzustellen.

Hinweis: Die APIs aus dem Amazon Connect Participant Service verwenden keine Authentifizierung der Signaturversion 4. Für den Header-Wert der X-Amz-Bearer-Anforderung müssen Sie stattdessen entweder den ParticipantToken- oder den ConnectionToken-Wert verwenden. Der ParticipantToken-Wert wird nur beim Aufruf der API CreateParticipantConnection verwendet. Bei anderen APIs aus dem Amazon Connect Participant Service müssen Sie den ConnectionToken-Wert übergeben.

Beispiel einer Anforderung der API CreateParticipantConnection (JavaScript)

Wenn Sie axios in Ihrer Anwendung verwenden, können Sie die API CreateParticipantConnection mit dem folgenden JavaScript-Code aufrufen:

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

Erstellen einer WebSocket-Verbindung mit der zurückgegebenen WebSocket-URL und Abonnieren der Anwendung für das Thema „aws/chat“

Nach dem Aufrufen der API CreateParticipantConnection muss der Client manuell eine Verbindung zur zurückgegebenen WebSocket-URL herstellen und das Thema „aws/chat“ abonnieren.

Weitere Informationen finden Sie unter CreateParticipantConnection in der Referenz zu den APIs des Amazon Connect Participant Service.

Beispiel für JavaScript-Code, der eine WebSocket-Verbindung herstellt und einen Client für das Thema „aws/chat“ abonniert

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

Senden von Chat-Nachrichten oder Ereignissen durch Aufrufen von APIs aus dem Amazon Connect Participant Service

Hinweis: Sie können keine Nachrichten oder Ereignisse direkt über die WebSocket-Verbindung senden. Sie müssen stattdessen eine der APIs aus dem Amazon Connect Participant Service verwenden.

Rufen Sie zum Senden von Chat-Nachrichten die API SendMessage aus dem Amazon Connect Participant Service auf.

–oder–

Rufen Sie zum Senden von Ereignissen die API SendEvent aus dem Amazon Connect Participant Service auf.

Wichtig: Stellen Sie für den Header der X-Amz-Bearer-Anforderung sicher, dass Sie den ConnectionToken-Wert verwenden, der von der API CreateParticipantConnection zurückgegeben wird.

Beispiel einer Anforderung der API SendMessage (JavaScript)

Wenn Sie axios in Ihrer Anwendung verwenden, können Sie die API SendMessage mit dem folgenden JavaScript-Code aufrufen:

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

Beispiel einer Anforderung der API SendEvent (JavaScript)

Wenn Sie axios in Ihrer Anwendung verwenden, können Sie die API SendEvent mit dem folgenden JavaScript-Code aufrufen:

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

---