Amazon Connect Customer AI エージェントセルフサービスの会話を ListMessages API で取得してみた

Amazon Connect Customer AI エージェントセルフサービスの会話を ListMessages API で取得してみた

Amazon Connect の AI エージェントとの会話履歴を Contact ID から取得する方法を紹介します。`ListMessages` API を使って顧客と AI エージェントのメッセージをプログラムで取り出し、外部システム連携や回答精度の分析などに活用できます。
2026.09.09

はじめに

Amazon Connect Customer の AI エージェントを利用してセルフサービスの問い合わせ対応を行う場合、通話終了後に顧客と AI エージェントの会話内容を確認したいことがあります。

たとえば、以下のような用途です。

  • AI エージェントの回答内容を確認する
  • 問い合わせ内容と対応結果を外部システムへ連携する
  • AI エージェントの回答精度を分析する

Amazon Connect Customer の AI エージェントに関する情報は、用途に応じて ListMessages API、ListSpans API、CloudWatch Logs、Automated Interaction Log、Contact Lens などから確認できます。

今回は、その中から AI エージェントのセッション内にある会話メッセージを取得できる ListMessages API を使用します。

AWS CloudShell から Contact ID を起点に DescribeContact API を実行し、取得した Session ARN から Assistant ID と Session ID を抽出して、ListMessages API で会話を取得してみました。

https://docs.aws.amazon.com/connect/latest/APIReference/API_amazon-q-connect_ListMessages.html

先に結論

Contact ID から AI エージェントとの会話を取得する流れは以下です。

Contact ID

DescribeContact

Contact.WisdomInfo.SessionArn

Assistant ID・Session ID を抽出

ListMessages

顧客と AI エージェントのメッセージを取得

DescribeContact のレスポンスに含まれる Contact.WisdomInfo.SessionArn から Assistant ID と Session ID を抽出し、aws qconnect list-messages に指定します。

今回の検証では、以下のコマンドを AWS CloudShell から実行しました。

export AWS_REGION="ap-northeast-1"
export INSTANCE_ID="<connect-instance-id>"
export CONTACT_ID="<contact-id>"

SESSION_ARN=$(aws connect describe-contact \
  --instance-id "$INSTANCE_ID" \
  --contact-id "$CONTACT_ID" \
  --region "$AWS_REGION" \
  --query 'Contact.WisdomInfo.SessionArn' \
  --output text)

if [ -z "$SESSION_ARN" ] ||
   [ "$SESSION_ARN" = "None" ] ||
   [ "$SESSION_ARN" = "null" ]; then
  echo "ERROR: AI エージェントの Session ARN を取得できませんでした。" >&2
  exit 1
fi

ASSISTANT_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $(NF-1)}')
SESSION_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $NF}')

echo "CONTACT_ID=$CONTACT_ID"
echo "ASSISTANT_ID=$ASSISTANT_ID"
echo "SESSION_ID=$SESSION_ID"

aws qconnect list-messages \
  --assistant-id "$ASSISTANT_ID" \
  --session-id "$SESSION_ID" \
  --filter TEXT_ONLY \
  --region "$AWS_REGION" \
  --output json |
jq -r '
  .messages
  | sort_by(.timestamp)
  | .[]
  | select(.value.text.value? != null)
  | "\(.participant): \(.value.text.value | gsub("\\s+"; " "))"
'

今回の検証では、通話終了後にこのコマンドを実行し、顧客と AI エージェントのメッセージを CUSTOMERBOT の形式で確認できました。

先に結論

ListMessages API には Contact ID を直接指定できません。実行には、AI エージェントの Assistant ID と Session ID が必要です。

そこで、まず Contact ID を指定して DescribeContact API を実行し、レスポンスの Contact.WisdomInfo.SessionArn を取得します。Session ARN の末尾には Assistant ID と Session ID が含まれているため、それぞれを抽出して ListMessages API に指定します。

今回の検証では、AWS CloudShell から以下の手順で会話を取得しました。

  1. Contact IDを指定して DescribeContact APIを実行する
  2. Contact.WisdomInfo.SessionArn を取得する
  3. Session ARNから Assistant IDとSession IDを抽出する
  4. 抽出したIDを指定して ListMessages APIを実行する
  5. 取得したメッセージを jq で時系列に整形する

以下が、今回実行したコマンドです。

export AWS_REGION="ap-northeast-1"
export INSTANCE_ID="<connect-instance-id>"
export CONTACT_ID="<contact-id>"

SESSION_ARN=$(aws connect describe-contact \
  --instance-id "$INSTANCE_ID" \
  --contact-id "$CONTACT_ID" \
  --region "$AWS_REGION" \
  --query 'Contact.WisdomInfo.SessionArn' \
  --output text)

if [ -z "$SESSION_ARN" ] ||
   [ "$SESSION_ARN" = "None" ] ||
   [ "$SESSION_ARN" = "null" ]; then
  echo "ERROR: AI エージェントの Session ARN を取得できませんでした。" >&2
  exit 1
fi

ASSISTANT_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $(NF-1)}')
SESSION_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $NF}')

echo "CONTACT_ID=$CONTACT_ID"
echo "ASSISTANT_ID=$ASSISTANT_ID"
echo "SESSION_ID=$SESSION_ID"

aws qconnect list-messages \
  --assistant-id "$ASSISTANT_ID" \
  --session-id "$SESSION_ID" \
  --filter TEXT_ONLY \
  --region "$AWS_REGION" \
  --output json |
jq -r '
  .messages
  | sort_by(.timestamp)
  | .[]
  | select(.value.text.value? != null)
  | "\(.participant): \(.value.text.value | gsub("\\s+"; " "))"
'

通話終了後にこのコマンドを実行したところ、顧客の発話は CUSTOMER、AI エージェントの応答は BOT として取得できました。

前提

今回は以下の環境で確認しました。

  • リージョン:ap-northeast-1
  • Amazon Connect Customer インスタンス:作成済み
  • セルフサービス用の AI エージェント:作成済み
  • AI エージェントを使用する音声フロー:作成済み
  • 実行環境:AWS CloudShell

記事内のリソース ID、メッセージ ID、アカウント ID、電話番号は、例示用の値に変更しています。

また、AWS CloudShell には aws コマンドと jq コマンドが用意されている環境を使用しています。jq を使わない場合の確認方法は、後半で説明します。

Contact ID から会話を取得する流れ

ListMessages API を実行するには、Assistant ID と Session ID が必要です。

今回は、Contact ID を指定して DescribeContact API を実行し、レスポンスの Contact.WisdomInfo.SessionArn からこれらの ID を取得します。

DescribeContact API は、指定したコンタクトの情報を取得する API です。レスポンスには、AI エージェントに関連する情報として WisdomInfo が含まれ、その中に Session ARN が格納されます。

{
  "Contact": {
    "WisdomInfo": {
      "SessionArn": "arn:aws:wisdom:ap-northeast-1:111111111111:session/aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee/ffffffff-1111-4222-8333-444444444444"
    }
  }
}

今回の検証では、Session ARN は以下の形式でした。

arn:aws:wisdom:<region>:<account-id>:session/<assistant-id>/<session-id>

このため、ARN を / で分割し、末尾から Assistant ID と Session ID を抽出します。

arn:aws:wisdom:<region>:<account-id>:session/<assistant-id>/<session-id>
                                                        ↑             ↑
                                                Assistant ID       Session ID

DescribeContact API の詳細は、以下のドキュメントに記載されています。

https://docs.aws.amazon.com/ja_jp/connect/latest/APIReference/API_DescribeContact.html

WisdomInfo の詳細は、以下のドキュメントに記載されています。

https://docs.aws.amazon.com/ja_jp/connect/latest/APIReference/API_WisdomInfo.html

Session ARN から ID を抽出する

以下のコマンドで、Session ARN の末尾から Assistant ID と Session ID を抽出します。

ASSISTANT_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $(NF-1)}')
SESSION_ID=$(echo "$SESSION_ARN" | awk -F/ '{print $NF}')

awk -F/ によって / を区切り文字として扱い、NF から要素数を取得しています。

  • $(NF-1):末尾から 2 番目の要素
  • $NF:末尾の要素

今回確認した Session ARN の形式では、末尾から 2 番目が Assistant ID、末尾が Session ID に該当します。

Session ARN を取得できない場合

SessionArnWisdomInfo の必須項目ではないため、対象 Contact によっては取得できない場合があります。

そのため、実際の処理では Session ARN が空の場合を確認するようにしています。

if [ -z "$SESSION_ARN" ] ||
   [ "$SESSION_ARN" = "None" ] ||
   [ "$SESSION_ARN" = "null" ]; then
  echo "ERROR: AI エージェントの Session ARN を取得できませんでした。" >&2
  exit 1
fi

今回の検証では、AI エージェントを利用した音声コンタクトを対象にしたため、Session ARN を取得できました。

AWS CloudShell から ListMessages API を実行する

Assistant ID と Session ID を取得できたら、aws qconnect list-messages を実行します。

AWS CLI のコマンド名は qconnect ですが、対象は Amazon Connect Customer の AI エージェントのセッションです。

aws qconnect list-messages \
  --assistant-id "$ASSISTANT_ID" \
  --session-id "$SESSION_ID" \
  --filter TEXT_ONLY \
  --region "$AWS_REGION" \
  --output json

ListMessages では、Assistant ID と Session ID を指定してセッション内のメッセージを取得します。AWS CLI リファレンスでは、list-messages はページネーション対象の API とされています。

今回のコマンドでは、以下のオプションを使用しています。

オプション 内容
--assistant-id AI エージェントの Assistant ID
--session-id メッセージを取得する Session ID
--filter TEXT_ONLY テキストメッセージを対象にするフィルター
--region API を実行するリージョン
--output json レスポンスを JSON 形式で出力する

実行結果

今回の環境では、以下のように Contact ID、Assistant ID、Session ID が表示されました。

記事内の ID は例示用に変更しています。

CONTACT_ID=11111111-2222-4333-8444-555555555555
ASSISTANT_ID=aaaaaaaa-bbbb-4ccc-8ddd-eeeeeeeeeeee
SESSION_ID=ffffffff-1111-4222-8333-444444444444

続いて、顧客と AI エージェントの会話が表示されました。

CUSTOMER: 配送日時を確認したいんですけど
BOT: かしこまりました。配送日時を確認させていただきます。注文番号の下4桁と、ご注文時に登録いただいた電話番号を教えていただけますか?
CUSTOMER: 4桁は1742で電話番号は090xxxxxxxxです
BOT: ありがとうございます。確認させていただきます。
BOT: 配送予定日は9月8日、配送時間帯は午後4時から午後6時です。
CUSTOMER: 配送時間帯だけ14時に変更したいです
BOT: かしこまりました。配送時間帯を午後2時に変更したいということですね。確認させていただきます。9月8日の午後2時から午後4時の時間帯が利用可能かどうか確認いたします。
BOT: 申し訳ございません。午後2時から午後4時の時間帯は満席となっております。同じ9月8日でしたら、午後12時から午後2時、または午後6時から午後8時でしたら利用可能です。いかがでしょうか?
CUSTOMER: じゃあ午後6時から8時でお願いします
BOT: かしこまりました。変更内容を確認させていただきます。現在の配送予定:9月8日の午後4時から午後6時。変更後:9月8日の午後6時から午後8時。こちらでよろしいでしょうか?
CUSTOMER: はい
BOT: ありがとうございます。配送日時を変更いたします。
BOT: 配送日時の変更が完了いたしました。9月8日の午後6時から午後8時での配送となります。変更内容をSMSでお送りいたしました。
CUSTOMER: はい、ありがとうございました
BOT: こちらこそ、ご利用ありがとうございました。ご不明な点がございましたら、いつでもお気軽にお問い合わせください。

今回の検証では、以下の情報を取得できました。

  • 顧客の発話
  • AI エージェントの応答
  • 発話者を表す CUSTOMERBOT
  • メッセージの時系列

表示上は時刻を省略していますが、sort_by(.timestamp) によってメッセージを時系列で確認しています。

また、通話終了後にコマンドを実行し、最後の AI エージェントの応答まで取得できました。

jq を使わずに JSON を確認する

会話を整形せず、ListMessages のレスポンスをそのまま確認する場合は、jq を使用する必要はありません。

Assistant ID と Session ID を取得した後、以下のコマンドを実行します。

aws qconnect list-messages \
  --assistant-id "$ASSISTANT_ID" \
  --session-id "$SESSION_ID" \
  --filter TEXT_ONLY \
  --region "$AWS_REGION" \
  --output json

出力例は以下です。

メッセージ ID とタイムスタンプは記事用に変更しています。

{
  "messages": [
    {
      "value": {
        "text": {
          "value": "\nこちらこそ、ご利用ありがとうございました。ご不明な点がございましたら、いつでもお気軽にお問い合わせください。\n"
        }
      },
      "messageId": "aaaaaaaa-1111-4222-8333-bbbbbbbbbbbb",
      "participant": "BOT",
      "timestamp": "2026-08-05T23:56:38.745000+00:00"
    },
    {
      "value": {
        "text": {
          "value": "はい、ありがとうございました"
        }
      },
      "messageId": "cccccccc-1111-4222-8333-dddddddddddd",
      "participant": "CUSTOMER",
      "timestamp": "2026-08-05T23:56:37.161000+00:00"
    },
    {
      "value": {
        "text": {
          "value": "\n配送日時の変更が完了いたしました。9月8日の午後6時から午後8時での配送となります。変更内容をSMSでお送りいたしました。\n"
        }
      },
      "messageId": "eeeeeeee-1111-4222-8333-ffffffffffff",
      "participant": "BOT",
      "timestamp": "2026-08-05T23:56:22.978000+00:00"
    }
  ]
}

この形式では、以下の情報を確認できます。

  • messageId
  • participant
  • timestamp
  • value.text.value

メッセージ本文に含まれる改行

BOT のメッセージ本文を見ると、文字列の先頭や末尾に \n が含まれています。

"value": "\n配送日時の変更が完了いたしました。\n"

この改行文字が含まれているため、JSON をそのまま表示すると、BOT: と本文が別の行に分かれて表示される場合があります。

会話本文を読みやすく表示したい場合は、先ほどのように jq で本文を抽出し、改行や連続する空白を半角スペースへ置換します。

ListMessages は通話全体の文字起こしではない

ListMessages で取得しているのは、AI エージェントのセッション内にあるメッセージです。

そのため、AI エージェントが関与していない区間を含めた音声コンタクト全体のトランスクリプトを取得する API ではありません。

取得したい情報によって、利用する機能を選択する必要があります。

取得したい情報 確認方法の例
顧客と AI エージェントのメッセージ ListMessages
AI エージェントの処理やツール実行 ListSpans
AI エージェントの詳細なイベントログ CloudWatch Logs
管理画面で自動応対の履歴を確認 Automated Interaction Log
音声コンタクトのトランスクリプト Contact Lens

今回のように、AI エージェントのセッション内で顧客と AI エージェントが交換したメッセージを API から取得する場合は、ListMessages が適しています。

一方で、AI エージェントの内部処理やツール実行、音声コンタクト全体のトランスクリプトが必要な場合は、別の機能を組み合わせて確認します。

取得時に確認しておきたいこと

Session ARN の有無を確認する

ListMessages の実行には Assistant ID と Session ID が必要です。

今回は DescribeContactContact.WisdomInfo.SessionArn から取得しましたが、SessionArn が存在しない Contact も考慮する必要があります。

実装する場合は、Session ARN が取得できなかったときのエラー処理や、対象外として扱う処理を追加してください。

メッセージの取得タイミングを考慮する

今回の検証では、通話終了後にコマンドを実行し、最後の AI エージェントの応答まで取得できました。

ただし、実運用で取得処理を自動化する場合は、問い合わせ終了直後に必ずすべてのメッセージが取得できるかを、利用するフローや環境で確認する必要があります。

取得処理に失敗した場合に備えて、一定時間後の再試行や、取得済み Contact ID の管理なども検討するとよさそうです。

ページネーションを考慮する

list-messages はページネーション対象のコマンドです。

AWS CLI はデフォルトで自動ページネーションを行うため、今回掲載しているコマンドでは、複数ページに分かれている場合もすべてのメッセージが取得されます。

一方、--no-paginate を指定した場合は最初の1ページだけが取得されます。また、--max-items で取得件数を制限した場合は、必要に応じて返却されたトークンを --starting-token に指定して取得を再開します。

APIやSDKを使って独自に取得処理を実装する場合は、レスポンスに含まれる nextToken を使用して次のページを取得してください。

まとめ

Contact ID から Session ARN を取得し、抽出した Assistant ID と Session ID を ListMessages API に指定することで、顧客と AI エージェントの会話を取得できました。

ListMessages の対象は AI エージェントのセッション内のメッセージです。通話全体のトランスクリプトや処理トレースが必要な場合は、Contact Lens、ListSpans、CloudWatch Logs などを利用します。

この記事をシェアする

AWSのお困り事はクラスメソッドへ

関連記事