PlayAudioAndGetDigits

오디오를 재생하고 DTMF 숫자를 수집합니다. 사용자가 올바른 DTMF 자릿수를 입력하지 않는 등 오류가 발생하는 경우, 액션은 “실패” 오디오를 재생한 다음 SIP 미디어 애플리케이션이Repeat 파라미터에 정의된 시도 횟수를 모두 소진할 때까지 기본 오디오를 재생합니다.

S3 버킷에서 오디오 파일을 재생해야 합니다. S3 버킷은 SIP 미디어 애플리케이션과 동일한AWS 계정에 속해야 합니다. 또한 Amazon Chime SDK 음성 커넥터 서비스 주체에게s3:GetObject 권한을 부여해야voiceconnector.chime.amazonaws.com 합니다. 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"
                }
            }
        }
    ]
}

오디오 서비스는 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

설명 — 연결된 참가자ParticipantTag 중 한 명에 대한 설명CallDetails

허용된 값 —LEG-A 또는LEG-B

필수 — 아니요

기본값 — 지정한 경우 호출된callLeg 항목ParticipantTag 중 무시됨CallId

InputDigitsRegex

설명 — 정규 표현식 패턴

허용되는 값 — 유효한 정규 표현식 패턴

필수 — 아니요

기본값 – 없음

AudioSource. 유형

설명 — 오디오 파일 유형의 소스 유형

허용된 값 — S3 버킷

필수 — 예

기본값 —"S3"

AudioSource.BucketName

설명 — S3AudioSource.Type 값의 경우 S3 버킷은 SIP 미디어 애플리케이션과 동일한AWS 계정에 속해야 합니다. 버킷 S3는 Amazon Chime SDK 음성 커넥터 서비스 주체에 액세스할 수 있어야voiceconnector.chime.amazonaws.com 합니다.

허용된 값 — Amazon Chime SDK에서s3:GetObject 작업에 액세스할 수 있는 유효한 S3 버킷입니다.

필수 — 예

기본값 – 없음

AudioSource. 키

설명 —AudioSource.BucketName S3 버킷에 있는 오디오 객체의 키 이름입니다.

허용된 값 — 유효한 오디오 파일

필수 — 예

기본값 – 없음

FailureAudioSource. 유형

설명 —FailureAudioSource.BucketName S3 버킷에 있는 오디오 객체의 키 이름입니다.

허용되는 값 — S3

필수 — 예

기본값 – 없음

FailureAudioSource.BucketName

설명 — S3 소스 유형의 경우 S3 버킷은 SIP 미디어 애플리케이션과 동일한AWS 계정에 속해야 합니다. Amazon Chime SDK 음성 커넥터 서비스 주체는 S3 버킷에 대한 액세스 권한이 있어야 합니다.voiceconnector.chime.amazonaws.com

허용된 값 — Amazon Chime SDK에서s3:GetObject 작업에 액세스할 수 있는 유효한 S3 버킷입니다.

필수 — 예

기본값 – 없음

FailureAudioSource. 키

설명 —FailureAudioSource.BucketName S3 버킷에 있는 오디오 객체의 키 이름입니다.

허용된 값 — 유효한 오디오 파일

필수 — 예

기본값 – 없음

MinNumberOfDigits

설명 — 제한 시간이 초과되거나 “통화 실패” 오디오를 재생하기 전에 캡처할 최소 자릿수입니다.

허용된 값 — >=0

필수 — 아니요

기본값 — 0

MaxNumberOfDigits

설명 — 종료 숫자 없이 중지하기 전에 캡처할 최대 자릿수입니다.

허용된 값 — >MinNumberOfDigits

필수 — 아니요

기본값은 128입니다.

TerminatorDigits

설명 — 사용자가 입력값보다 작게 입력한 경우 입력을 종료하는 데 사용되는 숫자MaxNumberOfDigits

허용되는 값 — 다음 숫자 중 하나: 0123456789#*

필수 — 아니요

기본값 — #

InBetweenDigitsDurationInMilliseconds

설명 — 재생하기 전 숫자 입력 사이의 대기 시간 (밀리초)FailureAudio 입니다.

허용된 값 — >0

필수 — 아니요

기본값 — 지정하지 않을 경우 기본값으로 설정됩니다.RepeatDurationInMilliseconds

반복

설명 — 자릿수 가져오기를 시도한 총 횟수

허용된 값 — >0

필수 — 아니요

기본값 — 1

RepeatDurationInMilliseconds

설명 —Repeat 시도 사이의 대기 시간 (밀리초)

허용된 값 — >0

필수 — 예

기본값 – 없음

SIP 미디어 애플리케이션은PlayAudioAndGetDigits 작업을 실행한 후 항상ACTION_SUCCESSFUL 또는ACTION_FAILED 호출 이벤트 유형을 사용하여 해당AWS Lambda 함수를 호출합니다. 응용 프로그램이 성공적으로 숫자를 수집하면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	오디오 소스 파라미터 값이 잘못되었습니다.	이 오류는 여러 가지 이유로 발생할 수 있습니다. 예를 들어 SIP 미디어 애플리케이션은 권한 문제 또는 S3 버킷 문제로 인해 파일에 액세스할 수 없습니다. 또는 오디오 파일의 길이, 크기 또는 지원되지 않는 형식으로 인해 유효성 검사가 실패할 수 있습니다.
InvalidActionParameter	CallId또는 작업ParticipantTag 매개 변수가 잘못되었습니다.	ACallIdParticipantTag, 또는 다른 매개변수가 유효하지 않습니다.
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 -콜