如何為我的應用程式設定與 Amazon Connect 和 Amazon Connect 參與者服務 API 進行原生互動的聊天小工具？

解決方法

若要使用 Amazon Connect 和 Amazon Connect 參與者服務 API 直接從您的應用程式啟動客戶聊天聯絡，請執行下列操作：

當客戶啟動聊天聯絡時，呼叫 StartChatContact Amazon Connect API

將應用程式設定為在客戶啟動聊天聯絡時呼叫 StartChatContact Amazon Connect API。API 回應會傳回 ParticipantToken 值。呼叫 CreateParticipantConnection API 需要此值。

**重要事項：**進行 API 呼叫的用戶端必須具有 AWS Identity and Access Management (IAM) 權限才能執行 connect:StartChatContact動作。

使用 GitHub 網站上的 amazon-connect-chat-ui-examples AWS CloudFormation 範本來部署呼叫 StartChatContact API 所需的資源。該範本會建立 Amazon API Gateway 端點，該端點會調用包含所需的 IAM 權限的 AWS Lambda 函數。AWS Lambda 函數會調用 Amazon Connect StartChatContact API 並傳回該呼叫的結果。

StartChatContact API 請求 (JavaScript) 範例

如果您在應用程式中使用 axios，請使用下列 JavaScript 程式碼來呼叫 StartChatContact API：

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

如需詳細資訊，請參閱 GitHub 網站上的 axios 命令。

呼叫 CreateParticipantConnection Amazon Connect 參與者服務 API 並傳遞 ParticipantToken 值

設定您的應用程式以在啟動聊天聯絡後呼叫 CreateParticipantConnection Amazon Connect 參與者服務 API。

當您調用 CreateParticipantConnection API 時，它會傳回 WebSocket 網址和 ConnectionToken。用戶端必須手動連線到 WebSocket 網址並訂閱所需的主題 (「aws/chat」)，才能建立聊天參與者的連線。

**注意：**Amazon Connect 參與者服務 API 不使用 簽章版本 4 驗證。對於 X-Amz-Bearer 請求標頭值，您必須改用 ParticipantToken 或 ConnectionToken 值。ParticipantToken 值僅用於呼叫 CreateParticipantConnection API。其他 Amazon Connect 參與者服務 API 要求您傳遞 ConnectionToken 值。

CreateParticipantConnection API 請求 (JavaScript) 範例：

如果您在應用程式中使用 axios，請使用下列 JavaScript 程式碼來呼叫 CreateParticipantConnection API：

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

使用傳回的 WebSocket 網址建立 WebSocket 連線，並向應用程式訂閱「aws/chat」主題

調用 CreateParticipantConnection API 後，用戶端必須手動連線到傳回的 WebSocket 網址並訂閱**「aws/chat」**主題。

如需詳細資訊，請參閱 Amazon Connect 參與者服務 API 參考中的 CreateParticipantConnection。

建立 WebSocket 連線，並向用戶端訂閱「aws/chat」主題的 JavaScript 程式碼範例：

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

透過 WebSocket 連線接收聊天事件和訊息

開啟 WebSocket 連線並訂閱**「aws/chat」** 主題後，您可以透過 WebSocket 接收聊天事件和訊息。若要執行此操作，請為「訊息」事件新增事件接聽程式。

為「訊息」事件建立事件接聽程式的 JavaScript 程式碼範例：

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

如需有關 responseMessage 物件結構的詳細資訊，請參閱 Amazon Connect 文件中的項目。

透過 Amazon Connect 參與者服務 API 傳送聊天訊息或事件

**注意：**您無法直接透過 WebSocket 連線傳送訊息或事件。您必須改用其中一個 Amazon Connect 參與者服務 API。

若要傳送聊天訊息，請呼叫 SendMessage Amazon Connect 參與者服務 API。或者，若要傳送事件，請呼叫 SendEvent Amazon Connect 參與者服務 API。

**重要事項：**對於 X-Amz-Bearer 請求標頭，請使用 CreateParticipantConnection API 傳回的 ConnectionToken 值。

SendMessage API 請求 (JavaScript) 範例

如果您在應用程式中使用 axios，請使用下列 JavaScript 程式碼來呼叫 SendMessage API：

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

SendEvent API 請求 (JavaScript) 範例

如果您在應用程式中使用 axios，請使用下列 JavaScript 程式碼來呼叫 SendEvent API：

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