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

解決方案

要使用 Amazon Connect 和 Amazon Connect 參與者服務 API 直接從您的應用程式啟動客户聊天聯絡人，請將您的應用程式設定為執行以下操作。

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

將您的應用程式設定為在客户啟動聊天聯絡人時呼叫 StartChatContact Amazon Connect API。API 回應傳回在下一步中呼叫 CreateParticipantConnection API 所需的 ParticipantToken 值。

**重要提示：**正在進行 API 呼叫的用戶端必須具有 AWS Identity and Access Management (IAM) 許可才能執行 connect:StartChatContact 動作。

要部署從應用程式呼叫 StartChatContact API 所需的資源，您可以在 GitHub 上使用以下 AWS CloudFormation 範本：amazon-connect-chat-ui-examples。該範本建立一個 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" // This is going to be a display name of your customer during a chat contact
    }
  }
);

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

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

叫用 CreateParticipantConnection API 會傳回 WebSocket URL 和 ConnectionToken。用戶端必須手動連接到 WebSocket URL 並訂閲所需的主題 (「aws/chat」)，之後才能建立聊天參與者的連線。

**注意：**Amazon Connect 參與者服務 API 不使用簽章版本 4 身分驗證。對於 X-Amz-Bearer 請求標頭值，您必須改為使用 ParticipantToken 或 ConnectionToken 值。僅在呼叫 CreateParticipantConnection API 時使用 ParticipantToken 值。其他 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 URL 建立 WebSocket 連線，並讓應用程式訂閲「aws/chat」主題

叫用 CreateParticipantConnection API 後，用戶端必須手動連接到傳回的 WebSocket URL 並訂閲**「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))
});

透過呼叫 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
});

---