Amazon Connect StartOutboundVoiceContact APIの留守電検知設定AnswerMachineDetectionConfigの仕様を確認してみた

はじめに

Amazon Connectで StartOutboundVoiceContact APIを利用すると、指定した電話番号へアウトバウンド発信し、指定したコンタクトフローを開始できます。

このAPIには AnswerMachineDetectionConfig というパラメータがあります。

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

名前のとおり、留守電検知（AMD、Answering Machine Detection）に関する設定ですが、Amazon Connectのフロー側にも [通話の進捗を確認] ブロックがあります。

AnswerMachineDetectionConfig の設定内容と、[通話の進捗を確認] ブロックとの役割の違いが少し分かりづらかったため、本記事で整理します。

結論

AnswerMachineDetectionConfig は、アウトバウンド発信時に留守電検知を実行するかどうかを指定するAPI側の設定です。

主な設定項目は以下の2つです。

EnableAnswerMachineDetection=true の場合は、StartOutboundVoiceContact の TrafficType=CAMPAIGN が必要です。EnableAnswerMachineDetection=false または未指定の場合は、留守電検知を使わない発信のため TrafficType=GENERAL を使用します。

一方、[通話の進捗を確認] ブロックは、留守電検知の結果を使ってフローを分岐するブロックです。

つまり、[通話の進捗を確認] ブロックをフローに配置するだけでは、StartOutboundVoiceContact の発信で留守電検知が有効になるわけではありません。

StartOutboundVoiceContact で留守電検知を使いたい場合は、API側で AnswerMachineDetectionConfig を指定し、その結果をフロー側の [通話の進捗を確認] ブロックで利用します。

StartOutboundVoiceContactとは

StartOutboundVoiceContact は、アウトバウンド通話を開始し、指定したフローを実行するAPIです。

Places an outbound call to a contact, and then initiates the flow. It performs the actions in the flow that's specified (in ContactFlowId).

コンタクトにアウトバウンド通話を発信し、その後フローを開始します。ContactFlowId で指定されたフロー内のアクションを実行します。

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

StartOutboundVoiceContact では、主に以下を指定します。

• InstanceId
• ContactFlowId
• DestinationPhoneNumber
• SourcePhoneNumber または QueueId
• Attributes
• RingTimeoutInSeconds
• AnswerMachineDetectionConfig
• TrafficType

ContactFlowId を指定するため「フローを呼び出すAPI」と捉えがちですが、実際には発信時の挙動に関する設定も指定できます。

その1つが、今回確認する AnswerMachineDetectionConfig です。

AnswerMachineDetectionConfigとは

AnswerMachineDetectionConfig は、アウトバウンド通話に対する留守電検知の設定です。

Configuration of the answering machine detection.

留守番電話検知の設定です。

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

設定項目は以下の2つです。

また、EnableAnswerMachineDetection=true を指定する場合は、StartOutboundVoiceContact 側で TrafficType=CAMPAIGN も指定する必要があります。

EnableAnswerMachineDetection

EnableAnswerMachineDetection は、音声通話に対して留守電検知の分析を実行するかどうかを指定するフラグです。

The flag to indicate if answer machine detection analysis needs to be performed for a voice call. If set to true, TrafficType must be set as CAMPAIGN.

音声通話に対して留守番電話検知の分析を実行する必要があるかを示すフラグです。true に設定する場合、TrafficType は CAMPAIGN に設定する必要があります。

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

EnableAnswerMachineDetection=true を指定すると、Amazon Connectが発信先の応答を解析します。

この解析結果を、フロー側の [通話の進捗を確認] ブロックで利用できます。

一方、EnableAnswerMachineDetection=false または未指定の場合は、留守電検知を使わない発信になります。

AwaitAnswerMachinePrompt

AwaitAnswerMachinePrompt は、留守電のプロンプトを待つかどうかを指定する項目です。

Wait for the answering machine prompt.

留守番電話のプロンプトを待ちます。

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

AwaitAnswerMachinePrompt=true の場合、留守電と判断されたあと、相手側の留守電ガイダンスやビープ音を待ってから、[通話の進捗を確認] ブロックの Voicemail (beep) または Voicemail (no beep) の分岐へ進む動きになります。

Voicemail (beep) は留守電でビープ音を検出した場合、Voicemail (no beep) は留守電だがビープ音を検出しなかった、またはビープ音が不明な場合の分岐です。

留守電にメッセージを残したい場合は、相手側の留守電ガイダンスが終わり、ビープ音の後にメッセージを再生したいケースがあるため、AwaitAnswerMachinePrompt=true を検討します。

一方、AwaitAnswerMachinePrompt=false の場合、留守電と判断された場合でも、留守電プロンプトを待たずに [通話の進捗を確認] ブロックの分岐へ進みます。

EnableAnswerMachineDetection=true であれば留守電検知自体は有効ですが、AwaitAnswerMachinePrompt=false は留守電ガイダンスやビープ音を待つ設定ではありません。そのため、留守電にメッセージを残す目的でビープ音後の再生を期待する場合は、AwaitAnswerMachinePrompt=true を利用するのが分かりやすいです。

TrafficTypeとの関係

StartOutboundVoiceContact では、TrafficType に GENERAL または CAMPAIGN を指定できます。

EnableAnswerMachineDetection=true を指定する場合は、TrafficType=CAMPAIGN が必要です。

一方、EnableAnswerMachineDetection=false または AnswerMachineDetectionConfig を指定しない場合は、留守電検知を使わない発信のため、TrafficType=GENERAL を使用します。

StartOutboundVoiceContact のドキュメントにも以下の記載があります。

Denotes the class of traffic. Calls with different traffic types are handled differently by Amazon Connect. The default value is GENERAL. Use CAMPAIGN if EnableAnswerMachineDetection is set to true. For all other cases, use GENERAL.

トラフィックの種類を示します。異なるトラフィックタイプの通話は、Amazon Connectによって異なる方法で処理されます。デフォルト値は GENERAL です。EnableAnswerMachineDetection が true に設定されている場合は CAMPAIGN を使用します。それ以外の場合は GENERAL を使用します。

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

なお、Amazon Connect Outbound Campaigns で作成するキャンペーンを使っていない場合でも、StartOutboundVoiceContact で EnableAnswerMachineDetection=true を指定する場合は、TrafficType=CAMPAIGN が必要です。

StartOutboundVoiceContact のドキュメントでは、TrafficType=CAMPAIGN の通話はデフォルトでは許可されておらず、Amazon Connect campaigns のクォータ引き上げ申請が必要と記載されています。

Campaign calls are not allowed by default. Before you can make a call with TrafficType = CAMPAIGN, you must submit a service quota increase request to the quota Amazon Connect campaigns.

キャンペーン通話はデフォルトでは許可されていません。TrafficType = CAMPAIGN で通話する前に、Amazon Connect campaigns のクォータに対してサービスクォータ引き上げリクエストを送信する必要があります。

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

申請対象としては、Amazon Connect Outbound campaigns service quotas の Concurrent campaign active calls per instance を確認します。このクォータは、現在のリージョンの対象インスタンスで同時に持てるキャンペーンアクティブ通話数を表します。

Concurrent campaign active calls per instance

The maximum number of concurrent campaign active calls you can have in this instance in the current Region.

インスタンスあたりの同時キャンペーンアクティブ通話数

現在のリージョンのこのインスタンスで持つことができる同時キャンペーンアクティブ通話の最大数です。

https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-service-limits.html

実際に利用できるクォータ値は、アカウントやリージョン、インスタンスの状態によって異なる可能性があります。そのため、Service Quotasで現在値を確認し、必要な同時発信数を満たしていない場合は引き上げ申請を行います。

Service Quotasでは、以下のように対象クォータを確認できます。

TrafficType=CAMPAIGN を利用する場合は、まずService Quotasで現在の Concurrent campaign active calls per instance の値を確認しておくとよいです。

通話の進捗を確認ブロックとは

[通話の進捗を確認] ブロックは、留守電検知の結果を使ってフローを分岐するブロックです。

This topic defines the flow block for engaging with the output provided by an answering machine, and providing the appropriate branches to route the contact.

このトピックでは、留守番電話から提供される出力を利用し、コンタクトをルーティングするための適切なブランチを提供するフローブロックについて説明します。

https://docs.aws.amazon.com/connect/latest/adminguide/check-call-progress.html

このブロックでは、以下のような分岐を利用できます。

[通話の進捗を確認] ブロックは、Voiceチャネルで利用できます。また、ドキュメント上はすべてのフロータイプで利用可能とされています。

Voice
Yes

音声
はい

https://docs.aws.amazon.com/connect/latest/adminguide/check-call-progress.html

You can use this block in the following flow types:
All flow types

このブロックは以下のフロータイプで使用できます。
すべてのフロータイプ

https://docs.aws.amazon.com/connect/latest/adminguide/check-call-progress.html

ポイントは、[通話の進捗を確認] ブロックは留守電検知を有効化する設定そのものではない点です。

このブロックは、留守電検知の結果を使ってフローを分岐するために利用します。

AnswerMachineDetectionConfigと通話の進捗を確認ブロックの違い

AnswerMachineDetectionConfig と [通話の進捗を確認] ブロックの関係は、以下のように整理できます。

StartOutboundVoiceContact
  ↓
AnswerMachineDetectionConfigで留守電検知を有効化
  ↓
Amazon Connectが発信先の応答を解析
  ↓
フロー内の[通話の進捗を確認]ブロックで結果を利用
  ├─ Call answered
  ├─ Voicemail (beep)
  ├─ Voicemail (no beep)
  ├─ Not detected
  └─ Error

役割を表にすると以下です。

このため、AnswerMachineDetectionConfig だけ指定しても、フロー側で結果を使わなければ分岐処理はできません。

逆に、[通話の進捗を確認] ブロックだけ配置しても、StartOutboundVoiceContact で留守電検知を有効化していなければ、期待した分岐にならない可能性があります。

設定値の見方

AnswerMachineDetectionConfig と TrafficType の指定を簡単に整理すると、以下のようになります。

なお、TrafficType は AnswerMachineDetectionConfig の配下ではなく、StartOutboundVoiceContact のパラメータです。TrafficType のデフォルト値は GENERAL です。

EnableAnswerMachineDetection=true の場合は、検知結果を [通話の進捗を確認] ブロックで分岐できます。

AwaitAnswerMachinePrompt は、留守電プロンプトを待つかどうかの設定です。true の場合は留守電ガイダンスやビープ音を待ち、false の場合は留守電プロンプトを待たずに分岐へ進みます。

AWS CLIで実行する例

StartOutboundVoiceContact で留守電検知を有効にする場合は、以下のように指定します。

aws connect start-outbound-voice-contact \
  --region ap-northeast-1 \
  --instance-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  --contact-flow-id "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" \
  --destination-phone-number "+819012345678" \
  --source-phone-number "+815012345678" \
  --answer-machine-detection-config "EnableAnswerMachineDetection=true,AwaitAnswerMachinePrompt=false" \
  --traffic-type CAMPAIGN \
  --ring-timeout-in-seconds 60 \
  --attributes "TestType=AnswerMachineDetection,StartedFrom=CloudShell" \
  --output json

成功すると、以下のように ContactId が返ります。

{
  "ContactId": "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"
}

上記の値は例です。instance-id、contact-flow-id、電話番号は利用するAmazon Connect環境に合わせて置き換えてください。

この例では、留守電検知を有効にしつつ、留守電のプロンプト待ちは行わない設定にしています。

まとめ

StartOutboundVoiceContact の AnswerMachineDetectionConfig は、発信時に留守電検知を有効化するためのAPI側の設定です。

一方、[通話の進捗を確認] ブロックは、その検知結果を使ってフローを分岐するためのブロックです。

留守電検知を使わない場合は TrafficType=GENERAL、留守電検知を使う場合は TrafficType=CAMPAIGN を指定します。

人間応答と留守電を区別して処理したい場合は、AnswerMachineDetectionConfig と [通話の進捗を確認] ブロックを組み合わせて利用します。

参考

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

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

https://docs.aws.amazon.com/connect/latest/adminguide/check-call-progress.html

https://docs.aws.amazon.com/connect/latest/adminguide/amazon-connect-service-limits.html

https://docs.aws.amazon.com/cli/latest/reference/connect/start-outbound-voice-contact.html