Amazon Connect のDescribeContact API では、より詳細なコンタクト情報が取得可能になりました
2025.05.22はじめに
Amazon Connect の DescribeContact API がアップデートされ、1 回の呼び出しで取得できるコンタクト情報が大幅に増えました。
本記事では、アップデート前後で取得できる項目を比較してみます。
まずは Internet Archive Wayback Machine で確認した 2023 年 4 月時点のDescribeContact APIのドキュメントのレスポンス例です。
（2023 年 4 月〜2025 年 4 月の記録は見つかりませんでしたが、この間にはもう少し取得可能な項目は増えていると思います）
{
"Contact": {
"AgentInfo": {
"ConnectedToAgentTimestamp": number,
"Id": "string"
},
"Arn": "string",
"Channel": "string",
"Description": "string",
"DisconnectTimestamp": number,
"Id": "string",
"InitialContactId": "string",
"InitiationMethod": "string",
"InitiationTimestamp": number,
"LastUpdateTimestamp": number,
"Name": "string",
"PreviousContactId": "string",
"QueueInfo": {
"EnqueueTimestamp": number,
"Id": "string"
},
"RelatedContactId": "string",
"ScheduledTimestamp": number,
"WisdomInfo": {
"SessionArn": "string"
}
}
}
次に、アップデート後のドキュメントに掲載されているレスポンス例を示します。
{
"Contact": {
"AdditionalEmailRecipients": {
"CcList": [
{
"Address": "string",
"DisplayName": "string"
}
],
"ToList": [
{
"Address": "string",
"DisplayName": "string"
}
]
},
"AgentInfo": {
"AfterContactWorkDuration": number,
"AfterContactWorkEndTimestamp": number,
"AfterContactWorkStartTimestamp": number,
"AgentInitiatedHoldDuration": number,
"AgentPauseDurationInSeconds": number,
"Capabilities": {
"ScreenShare": "string",
"Video": "string"
},
"ConnectedToAgentTimestamp": number,
"DeviceInfo": {
"OperatingSystem": "string",
"PlatformName": "string",
"PlatformVersion": "string"
},
"HierarchyGroups": {
"Level1": {
"Arn": "string"
},
"Level2": {
"Arn": "string"
},
"Level3": {
"Arn": "string"
},
"Level4": {
"Arn": "string"
},
"Level5": {
"Arn": "string"
}
},
"Id": "string",
"StateTransitions": [
{
"State": "string",
"StateEndTimestamp": number,
"StateStartTimestamp": number
}
]
},
"AnsweringMachineDetectionStatus": "string",
"Arn": "string",
"Attributes": {
"string" : "string"
},
"Campaign": {
"CampaignId": "string"
},
"Channel": "string",
"ConnectedToSystemTimestamp": number,
"ContactAssociationId": "string",
"ContactDetails": {
"Description": "string",
"Name": "string"
},
"ContactEvaluations": {
"string" : {
"DeleteTimestamp": number,
"EndTimestamp": number,
"EvaluationArn": "string",
"ExportLocation": "string",
"FormId": "string",
"StartTimestamp": number,
"Status": "string"
}
},
"Customer": {
"Capabilities": {
"ScreenShare": "string",
"Video": "string"
},
"DeviceInfo": {
"OperatingSystem": "string",
"PlatformName": "string",
"PlatformVersion": "string"
}
},
"CustomerEndpoint": {
"Address": "string",
"DisplayName": "string",
"Type": "string"
},
"CustomerId": "string",
"CustomerVoiceActivity": {
"GreetingEndTimestamp": number,
"GreetingStartTimestamp": number
},
"Description": "string",
"DisconnectDetails": {
"PotentialDisconnectIssue": "string"
},
"DisconnectReason": "string",
"DisconnectTimestamp": number,
"Id": "string",
"InitialContactId": "string",
"InitiationMethod": "string",
"InitiationTimestamp": number,
"LastPausedTimestamp": number,
"LastResumedTimestamp": number,
"LastUpdateTimestamp": number,
"Name": "string",
"PreviousContactId": "string",
"QualityMetrics": {
"Agent": {
"Audio": {
"PotentialQualityIssues": [ "string" ],
"QualityScore": number
}
},
"Customer": {
"Audio": {
"PotentialQualityIssues": [ "string" ],
"QualityScore": number
}
}
},
"QueueInfo": {
"EnqueueTimestamp": number,
"Id": "string"
},
"QueuePriority": number,
"QueueTimeAdjustmentSeconds": number,
"Recordings": [
{
"DeletionReason": "string",
"FragmentStartNumber": "string",
"FragmentStopNumber": "string",
"Location": "string",
"MediaStreamType": "string",
"ParticipantType": "string",
"StartTimestamp": number,
"Status": "string",
"StopTimestamp": number,
"StorageType": "string"
}
],
"RelatedContactId": "string",
"RoutingCriteria": {
"ActivationTimestamp": number,
"Index": number,
"Steps": [
{
"Expiry": {
"DurationInSeconds": number,
"ExpiryTimestamp": number
},
"Expression": {
"AndExpression": [
"Expression"
],
"AttributeCondition": {
"ComparisonOperator": "string",
"MatchCriteria": {
"AgentsCriteria": {
"AgentIds": [ "string" ]
}
},
"Name": "string",
"ProficiencyLevel": number,
"Range": {
"MaxProficiencyLevel": number,
"MinProficiencyLevel": number
},
"Value": "string"
},
"NotAttributeCondition": {
"ComparisonOperator": "string",
"MatchCriteria": {
"AgentsCriteria": {
"AgentIds": [ "string" ]
}
},
"Name": "string",
"ProficiencyLevel": number,
"Range": {
"MaxProficiencyLevel": number,
"MinProficiencyLevel": number
},
"Value": "string"
},
"OrExpression": [
"Expression"
]
},
"Status": "string"
}
]
},
"ScheduledTimestamp": number,
"SegmentAttributes": {
"string" : {
"ValueInteger": number,
"ValueMap": {
"string" : "SegmentAttributeValue"
},
"ValueString": "string"
}
},
"SystemEndpoint": {
"Address": "string",
"DisplayName": "string",
"Type": "string"
},
"Tags": {
"string" : "string"
},
"TotalPauseCount": number,
"TotalPauseDurationInSeconds": number,
"WisdomInfo": {
"SessionArn": "string"
}
}
}
取得できる項目が大幅に増えていることが分かりました。
何がうれしいか
今回のアップデートにより、例えば次のような項目を 1 回の API 呼び出しでまとめて取得 できるようになりました。
- 切断理由 （
Contact.DisconnectReason） - 録音ステータス（
Contact.Recordings[].Status） - アフターコンタクトワーク時間（
Contact.AgentInfo.AfterContactWorkDuration） - カスタム連絡先属性 （
Contact.Attributes） など
これにより、以下のメリットが得られます。
- 追加 API 呼び出しやデータ結合の手間が減少
- 処理フローがシンプルになり、パフォーマンスも向上
たとえば、エージェント側の問題でチャットが途中で切断された場合でも、DisconnectReason を参照するだけで原因を即座に特定できます。切断直後に自動で再キューイングし、フォローアップを行う、といった処理も簡単に組み込めます。
実際に取得してみる
エージェント対応が完了した後に describe-contact コマンドを実行し、実際のレスポンス内容を確認します。
なお、DescribeContact で取得できる情報は InitiationTimestamp から 24 か月間保持 され、その後自動的に削除されます。
$ aws connect describe-contact \
--instance-id 3ff2093d-af96-43fd-b038-3c07cdd7609c \
--contact-id a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292
{
"Contact": {
"Arn": "arn:aws:connect:ap-northeast-1:アカウントID:instance/3ff2093d-af96-43fd-b038-3c07cdd7609c/contact/a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292",
"Id": "a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292",
"ContactAssociationId": "a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292",
"InitiationMethod": "INBOUND",
"Channel": "VOICE",
"QueueInfo": {
"Id": "ba8d05d9-27b3-406e-b089-f5707174697e",
"EnqueueTimestamp": "2025-05-12T01:23:51.652000+00:00"
},
"AgentInfo": {
"Id": "104b4727-a2ef-4f12-8daf-6068ce627667",
"ConnectedToAgentTimestamp": "2025-05-12T01:23:56.148000+00:00",
"DeviceInfo": {
"PlatformName": "Chrome",
"PlatformVersion": "135",
"OperatingSystem": "Mac OS X"
},
"AfterContactWorkDuration": 2,
"AfterContactWorkStartTimestamp": "2025-05-12T01:24:07.787000+00:00",
"AfterContactWorkEndTimestamp": "2025-05-12T01:24:10.136000+00:00"
},
"InitiationTimestamp": "2025-05-12T01:23:50.033000+00:00",
"DisconnectTimestamp": "2025-05-12T01:24:07.787000+00:00",
"LastUpdateTimestamp": "2025-05-12T01:31:32.982000+00:00",
"TotalPauseCount": 0,
"CustomerEndpoint": {
"Type": "TELEPHONE_NUMBER",
"Address": "+8150xxxxxxx"
},
"SystemEndpoint": {
"Type": "TELEPHONE_NUMBER",
"Address": "+8150xxxxxxx"
},
"Tags": {
"aws:connect:instanceId": "3ff2093d-af96-43fd-b038-3c07cdd7609c",
"aws:connect:systemEndpoint": "+8150xxxxxxx"
},
"ConnectedToSystemTimestamp": "2025-05-12T01:23:50.644000+00:00",
"QualityMetrics": {
"Agent": {
"Audio": {
"QualityScore": 4.36,
"PotentialQualityIssues": []
}
}
},
"SegmentAttributes": {
"connect:Subtype": {
"ValueString": "connect:Telephony"
}
},
"Recordings": [
{
"StorageType": "S3",
"Location": "S3バケット名/connect/インスタンス名/CallRecordings/2025/05/12/a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292_20250512T01:23_UTC.wav",
"MediaStreamType": "AUDIO",
"Status": "AVAILABLE"
},
{
"StorageType": "S3",
"Location": "S3バケット名/connect/インスタンス名/CallRecordings/AUTOMATED_INTERACTION_LOG/2025/05/12/a4d5b1ba-c25e-4cb2-a5a5-8ec93691d292_3d87ae70-55be-4078-9aac-c18267a86749_20250512T01:31_UTC.json",
"MediaStreamType": "AUTOMATED_INTERACTION",
"Status": "AVAILABLE"
}
],
"DisconnectReason": "CUSTOMER_DISCONNECT",
"ContactDetails": {},
"Attributes": {
"Agent": "hirai",
"memo": "test",
"type": "その他"
}
}
}
このレスポンスから、以下の内容が取得できていることを確認できます。
- 切断理由
DisconnectReasonが CUSTOMER_DISCONNECT（顧客切断） - アフターコンタクトワーク時間
AfterContactWorkDurationが 2 秒 - 録音ステータス（
Status）が AVAILABLE
最後に
DescribeContact API のアップデートにより、コンタクト項目をより詳細に取得できるようになりました。
これにより、たとえば 切断要因の即時判定 や 自動リカバリー処理の実装 といったワークフローを、よりシンプルに組み立てられます。
日々の運用・分析にぜひ活用してみてください。
