PlayAudioAndGetDigits

音声を再生して DTMF ディジットを収集します。ユーザーが正しい DTMF ディジット数を入力しなかったなどの失敗が発生した場合、このアクションは「失敗」音声を再生し、Repeat パラメータで定義された試行回数を SIP メディアアプリケーションが使い切るまでメイン音声を再生します。

S3 バケットから音声ファイルを再生する必要があります。S3 バケットは、SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。さらに、Amazon Chime SDK Voice Connector サービスプリンシパル (voiceconnector.chime.amazonaws.com) に s3:GetObject 許可を付与する必要があります。これを行うには、S3 コンソールまたは CLI を使用できます。

次のコード例は、一般的な S3 バケットポリシーを示しています。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id"
                }
            }
        }
    ]
}

Audio Service は、Sip メディアアプリケーションの代わりに S3 バケットに対して読み書きします。「混乱した代理」の問題を回避するには、S3 バケットアクセスを単一の SIP メディアアプリケーションに制限できます。

{
    "Version": "2012-10-17",
    "Statement": [
        {
            "Sid": "SMARead",
            "Effect": "Allow",
            "Principal": {
                "Service": "voiceconnector.chime.amazonaws.com"
            },
            "Action": [
                "s3:GetObject"
            ],
            "Resource": "arn:aws:s3:::bucket-name/*",
                "Condition": {
                "StringEquals": {
                    "aws:SourceAccount": "aws-account-id",
                    "aws:SourceArn": "arn:aws:chime:region:aws-account-id:sma/sip-media-application-id"
                }
            }
        }
    ]
}

一般的な PlayAudioAndGetDigits アクションの例を次に示します。

{
    "Type" : "PlayAudioAndGetDigits",
    "Parameters" : {
        "CallId": "call-id-1",
        "ParticipantTag": "LEG-A"      
        "InputDigitsRegex": "^\d{2}#$",
        "AudioSource": {
            "Type": "S3",
            "BucketName": "bucket-name",
            "Key": "audio-file-1.wav"
        },
        "FailureAudioSource": {
            "Type": "S3",
            "BucketName": "bucket-name",
            "Key": "audio-file-failure.wav"
        },
        "MinNumberOfDigits": 3,
        "MaxNumberOfDigits": 5,
        "TerminatorDigits": ["#"],        
        "InBetweenDigitsDurationInMilliseconds": 5000,
        "Repeat": 3,
        "RepeatDurationInMilliseconds": 10000
    }
}

CallId

説明 — AWS Lambda 関数呼び出しCallDetailsの におけるCallId参加者の数

使用できる値 – 有効な通話 ID

必須 – いいえ

デフォルト値 – なし

ParticipantTag

説明 – CallDetails に接続されている参加者のうちの 1 人の ParticipantTag。

使用できる値 – LEG-A または LEG-B

必須 – いいえ

デフォルト値 – 呼び出された callLeg の ParticipantTag (CallId を指定すると無視されます)

InputDigitsRegex

説明 - 正規表現パターン

使用できる値 - 有効な正規表現パターン

必須 – いいえ

デフォルト値 – なし

AudioSource.Type

説明 – 音声ファイルタイプのソースのタイプ

使用できる値 - S3 バケット

必須 – はい

デフォルト値 – "S3"

AudioSource.BucketName

説明 – S3 AudioSource.Type値の場合、S3 バケットは SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。S3 バケットは、Amazon Chime SDK Voice Connector サービスプリンシパルである voiceconnector.chime.amazonaws.com にアクセスできる必要があります。

使用できる値 – Amazon Chime SDK が s3:GetObject アクションにアクセスできる有効な S3 バケット。

必須 – はい

デフォルト値 – なし

AudioSource.Key

説明 - AudioSource.BucketName S3 バケット内の音声オブジェクトのキー名。

使用できる値 - 有効な音声ファイル

必須 – はい

デフォルト値 – なし

FailureAudioSource.Type

説明 - FailureAudioSource.BucketName S3 バケット内の音声オブジェクトのキー名。

使用できる値 – S3

必須 – はい

デフォルト値 – なし

FailureAudioSource.BucketName

説明 – S3 ソースタイプの場合、S3 バケットは SIP メディアアプリケーションと同じ AWS アカウントに属している必要があります。Amazon Chime SDK Voice Connector サービスプリンシパルである voiceconnector.chime.amazonaws.com は S3 バケットにアクセスできる必要があります。

使用できる値 – Amazon Chime SDK が s3:GetObject アクションにアクセスできる有効な S3 バケット。

必須 – はい

デフォルト値 – なし

FailureAudioSource.Key

説明 - FailureAudioSource.BucketName S3 バケット内の音声オブジェクトのキー名。

使用できる値 - 有効な音声ファイル

必須 – はい

デフォルト値 – なし

MinNumberOfDigits

説明 - タイムアウトになるか「通話失敗」の音声が再生される前にキャプチャする最小ディジット数。

使用できる値 – >=0

必須 – いいえ

デフォルト値 - 0

MaxNumberOfDigits

説明 - 終了ディジットなしで停止する前にキャプチャする最大ディジット数。

使用できる値 – >MinNumberOfDigits

必須 – いいえ

デフォルト値 – 128

TerminatorDigits

説明 - ユーザーが MaxNumberOfDigits 未満の値を入力した場合に、入力を終了するのに使用されるディジット。

使用できる値 - 次のディジットのいずれか: 0123456789#*

必須 – いいえ

デフォルト値 – #

InBetweenDigitsDurationInMilliseconds

説明 - FailureAudio を再生するまでのディジット入力間の待ち時間 (ミリ秒単位)。

使用できる値 – 0 より大きい値

必須 – いいえ

デフォルト値 - 指定しない場合、デフォルトは RepeatDurationInMilliseconds 値になります。

Repeat

説明 - ディジットの取得を試みた回数の合計。

使用できる値 – 0 より大きい値

必須 – いいえ

デフォルト値 – 1

RepeatDurationInMilliseconds

説明 — Repeat の試行間の待ち時間 (ミリ秒単位)。

使用できる値 – 0 より大きい値

必須 – はい

デフォルト値 – なし

SIP メディアアプリケーションは、 ACTION_SUCCESSFULまたは 呼び出しイベントタイプを使用して、 PlayAudioAndGetDigitsアクションを実行した後、常にその AWS Lambda 関数ACTION_FAILEDを呼び出します。このアプリケーションは、ディジットの収集に成功すると、ActionData オブジェクトに ReceivedDigits 値を設定します。次の例は、その AWS Lambda 関数の呼び出しイベント構造を示しています。

{
    "SchemaVersion": "1.0",
    "Sequence": 3,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
        "Type": "PlayAudioAndGetDigits",
        "Parameters" : {
            "CallId": "call-id-1",
            "ParticipantTag": "LEG-A",
            "InputDigitsRegex": "^\d{2}#$",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-1.wav"
            },
            "FailureAudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-failure.wav"
            },
            "MinNumberOfDigits": 3,
            "MaxNumberOfDigits": 5,
            "TerminatorDigits": ["#"],
            "InBetweenDigitsDurationInMilliseconds": 5000,
            "Repeat": 3,
            "RepeatDurationInMilliseconds": 10000
        },
        "ErrorType": "InvalidAudioSource",
        "ErrorMessage": "Audio Source parameter value is invalid."
    },
        "ReceivedDigits": "1234"
    },
    "CallDetails": {
        ...
    }
}

エラー処理

検証エラーが発生すると、SIP メディアアプリケーションは、対応するエラーメッセージで AWS Lambda 関数を呼び出します。次の表に、発生する可能性のあるエラーメッセージを示します。

エラー	メッセージ	理由
InvalidAudioSource	Audio Source parameter value is invalid.	このエラーは、さまざまな理由で発生します。例えば、許可や S3 バケットの問題により、SIP メディアアプリケーションがファイルにアクセスできなくなります。または、継続時間、サイズ、サポートされていない形式により、音声ファイルの検証に失敗することがあります。
InvalidActionParameter	アクションの CallId または ParticipantTag パラメータが無効です。	CallId、ParticipantTag、またはそれ以外のパラメータが無効です。
SystemException	アクションの実行中にシステムエラーが発生しました。	アクションの実行中にシステムエラーが発生しました。

タイムアウトまたは再試行回数が多すぎるため、アクションが指定された桁数を収集できない場合、SIP メディアアプリケーションはACTION_FAILED呼び出しイベントタイプで AWS Lambda 関数を呼び出します。

{
    "SchemaVersion": "1.0",
    "Sequence": 4,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData": {
        "Type": "PlayAudioAndGetDigits",
        "Parameters" : {
            "CallId": "call-id-1",
            "ParticipantTag": "LEG-A",
            "InputDigitsRegex": "^\d{2}#$",
            "AudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-1.wav"
            },
            "FailureAudioSource": {
                "Type": "S3",
                "BucketName": "bucket-name",
                "Key": "audio-file-failure.wav"
            },
            "MinNumberOfDigits": 3,
            "MaxNumberOfDigits": 5,
            "TerminatorDigits": ["#"],
            "InBetweenDigitsDurationInMilliseconds": 5000,
            "Repeat": 3,
            "RepeatDurationInMilliseconds": 10000
        },
        "ErrorType": "InvalidAudioSource",
        "ErrorMessage": "Audio Source parameter value is invalid."
    }
    "CallDetails": {
        ...
    }
}

の作業例を参照してください GitHub。

• https://github.com/aws-samples/amazon-chime-sma-bridging。

• https://github.com/aws-samples/amazon-chime-sma-update-call