Amazon Connect および Amazon Connect Participant Service API とネイティブに連携するアプリケーション用のチャットウィジェットを設定する方法を教えてください。

解決策

Amazon Connect および Amazon Connect Participant Service API を使用して、アプリケーションから直接カスタマーチャットの連絡先を開始するには、次の操作を行います。

お客様がチャットコンタクトを開始したときに、StartChatContact Amazon Connect API を呼び出す

お客様がチャットコンタクトを開始したときに StartChatContact Amazon Connect API を呼び出すようにアプリケーションを設定します。API レスポンスは ParticipantToken 値を返します。この値は、CreateParticipantConnection API を呼び出すために必要です。

**重要:**API コールを行うクライアントには、connect:StartChatContact アクションを実行するための AWS Identity and Access Management (AWS IAM) 権限が必要です。

StartChatContact API を呼び出すために必要なリソースをデプロイするには、GitHub ウェブサイトにある amazon-connect-chat-ui-examples AWS CloudFormation テンプレートを使用してください。このテンプレートは、必要な IAM アクセス権限を含む AWS Lambda 関数を呼び出す Amazon API Gateway エンドポイントを作成します。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 Participant Servie API を呼び出し、ParticipantToken の値を渡します。

チャットコンタクトが開始された後に CreateParticipantConnection Amazon Connect Participant Service API を呼び出すようにアプリケーションを設定します。

CreateParticipantConnection API を呼び出すと、WebSocket URL と ConnectionToken が返されます。チャット参加者の接続を作成するには、クライアントは手動で WebSocket URL に接続し、目的のトピック (「aws/chat」) にサブスクライブする必要があります。

**注:**Amazon Connect Participant Service API は Signature Version 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 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))
});

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 Participant Service API を使用してチャットメッセージまたはイベントを送信する

**注:**WebSocket 接続を介してメッセージやイベントを直接送信することはできません。代わりに Amazon Connect Participant Service API の 1 つを使用する必要があります。

チャットメッセージを送信するには、SendMessage Amazon Connect Participant Service API を呼び出します。または、イベントを送信するには、SendEvent Amazon Connect Participant Service 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
});