Amazon Connect の SearchContacts API で発信元電話番号を使って検索する方法
こんにちは。
繁松です。
はじめに
Amazon Connect で過去の通話履歴を取得する場合、「SearchContacts」API を使えば、期間などの条件を指定して通話履歴を検索できます。
通常のレスポンスには発信元電話番号の情報は含まれていませんが、コールフロー内でカスタム属性を設定し、コンタクトの検索の「検索可能なカスタムコンタクト属性」にその属性のキーを登録することで、発信元電話番号を条件に検索できるようになります。
前回対応したエージェントと同じエージェントに電話を転送したい場合などに有効です。
具体的には、コールフローで Lambda を実行し、SearchContacts API によって発信元電話番号を使って過去のコンタクトを検索し、その結果からエージェント情報を取得する、というフローが考えられます。
レスポンス構文；https://docs.aws.amazon.com/ja_jp/connect/latest/APIReference/API_SearchContacts.html
HTTP/1.1 200
Content-type: application/json
{
"Contacts": [
{
"AgentInfo": {
"ConnectedToAgentTimestamp": number,
"Id": "string"
},
"Arn": "string",
"Channel": "string",
"DisconnectTimestamp": number,
"Id": "string",
"InitialContactId": "string",
"InitiationMethod": "string",
"InitiationTimestamp": number,
"Name": "string",
"PreviousContactId": "string",
"QueueInfo": {
"EnqueueTimestamp": number,
"Id": "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" : {
"ValueMap": {
"string" : {
"ValueArn": "string",
"ValueInteger": number,
"ValueList": [
"SegmentAttributeValue"
],
"ValueMap": {
"string" : "SegmentAttributeValue"
},
"ValueString": "string"
}
},
"ValueString": "string"
}
}
}
],
"NextToken": "string",
"TotalCount": number
}
やってみた
コールフローの設定
コールフロー内にカスタム属性の設定ブロックを配置し、顧客の電話番号をコンタクト属性に設定します。
例：
検索可能なカスタムコンタクト属性の作成
Amazon Connect のコンタクトの検索を開き、検索可能なカスタムコンタクト属性を作成します。
検索可能なカスタムコンタクト属性を作成するページのURLは以下のようになります。
https://インスタンスエイリアス.my.connect.aws/connect/contact-attributes-config
AWS CLIで実行してみた
設定後に実際に架電して、SearchContacts APIを使って検索してみました。
コマンド
~ $ aws connect search-contacts \
--instance-id xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx \
--time-range Type=INITIATION_TIMESTAMP,StartTime=2025-11-01T00:00:00Z,EndTime=2025-11-30T23:59:59Z \
--search-criteria '{
"SearchableContactAttributes": {
"Criteria": [
{
"Key": "number",
"Values": [
"+81XXXXXXXXXX"
]
}
],
"MatchType": "MATCH_ALL"
}
}'
実行結果
{
"Contacts": [
{
"Arn": "arn:aws:connect:ap-northeast-1:123456789012:instance/xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx/contact/abcdef12-3456-7890-abcd-ef1234567890",
"Id": "abcdef12-3456-7890-abcd-ef1234567890",
"InitiationMethod": "INBOUND",
"Channel": "VOICE",
"QueueInfo": {},
"AgentInfo": {},
"InitiationTimestamp": "2025-11-29T15:31:00.117000+00:00",
"DisconnectTimestamp": "2025-11-29T15:31:03.349000+00:00",
"SegmentAttributes": {
"connect:Subtype": {
"ValueString": "connect:Telephony"
}
},
"RoutingCriteria": {
"Steps": [
{
"Expression": {
"AttributeCondition": {
"MatchCriteria": {
"AgentsCriteria": {
"AgentIds": []
}
}
}
}
}
]
}
}
],
"TotalCount": 1
}
さいごに
発信元電話番号で通話履歴を検索するには、コールフローでカスタム属性を設定し、「検索可能なカスタムコンタクト属性」に登録する必要があります。
その後、SearchContacts API を使ってその属性を検索条件に指定すれば、目的の履歴を取得できます。
この仕組みがあれば、同じ担当者への転送など、応用可能なシーンが広がります。
