PlayAudio
Play an audio file on any leg of a call. The audio can be repeated any number of times. The in-progress audio can be terminated using the DTMF digits set in the PlaybackTerminators
.
Currently, Amazon Chime SDK only supports
playing audio files from the Amazon Simple Storage Service (Amazon S3) bucket. The S3 bucket must belong
to the same AWS account as the SIP media application. In addition, you must give the s3:GetObject
permission to the Amazon Chime SDK Voice Connector
service principal. You can do that by using the S3 console or the command-line interface (CLI).
The following code example shows a typical bucket policy.
{ "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
" } } } ] }
The Audio Service reads and writes to your S3 bucket on behalf of your Sip Media Application. To avoid the confused deputy problem, you can restrict S3 bucket access to a single SIP media application.
{ "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
" } } } ] }
The following code example shows a typical action.
{ "Type": "PlayAudio", "Parameters": { "CallId": "
call-id-1
", "ParticipantTag": "LEG-A", "PlaybackTerminators": ["1
", "8
", "#
"], "Repeat": "5
", "AudioSource": { "Type": "S3", "BucketName": "valid-S3-bucket-name
", "Key": "wave-file.wav
" } } }
- CallID
-
Description –
CallId
of participant in theCallDetails
.Allowed values – A valid call ID.
Required – No, if
ParticipantTag
is present.Default value – None.
- ParticipantTag
-
Description –
ParticipantTag
of one of the connected participants in theCallDetails
.Allowed values –
LEG-A
orLEG-B
.Required – No, if
CallId
is present.Default value –
ParticipantTag
of the invokedcallLeg
. Ignored if you specifyCallId
. - PlaybackTerminator
-
Description – Terminates in-progress audio by using DTMF input from the user
Allowed values – An array of the following values; “0”, ”1”, ”2”, ”3”, ”4”, ”5”, ”6”, ”7”, ”8”, ”9”, ”#”, ”*”
Required – No
Default value – None
- Repeat
-
Description – Repeats the audio the specified number of times
Allowed values – An integer greater than zero
Required – No
Default value – 1
- AudioSource.Type
-
Description – Type of source for audio file.
Allowed values – S3.
Required – Yes.
Default value – None.
- AudioSource.BucketName
-
Description – For S3 source types, the S3 bucket must belong to the same AWS account as the SIP application. The bucket must have access to the Amazon Chime SDK Voice Connector service principal, which is voiceconnector.chime.amazonaws.com.
Allowed values – A valid S3 bucket for which Amazon Chime SDK has access to the
s3:GetObject
action.Required – Yes.
Default value – None.
- AudioSource.key
-
Description – For S3 source types, the file name from the S3 bucket specified in the
AudioSource.BucketName
attribute.Allowed values – A valid audio file.
Required – Yes.
Default value – None.
The SIP media application tries to play the audio from the source URL. You can use raw, uncompressed PCM .wav files of no more than 50 MB in size. Amazon Chime SDK recommends 8 KHz mono.
When the last instruction in a dialplan is PlayAudio
and the
file finishes playback, or if a user stops playback with a key press, the
application invokes the AWS Lambda function with the event shown in the following example.
{ "SchemaVersion": "1.0", "Sequence": INTEGER, "InvocationEventType": "ACTION_SUCCESSFUL", "ActionData": { "Type": "PlayAudio", "Parameters" : { "CallId": "
call-id-1
", "AudioSource": { "Type": "S3", "BucketName": "valid-S3-bucket-name
", "Key": "wave-file.wav
", } } }
After a terminating digit stops the audio, it won't be repeated.
Error handling
When the validation file contains errors, or an error occurs while running an action, the SIP media application calls an AWS Lambda function with the appropriate error code.
Error | Message | Reason |
---|---|---|
|
The audio source parameter is invalid. |
This error can happen for multiple reasons. For example, the SIP media application cannot access the file due to permission issues, or issues with the URL. Or, the audio file may fail validation due to format, duration, size, and so on. |
|
System error while running action. |
Another system error occurred while running the action. |
|
CallId or ParticipantTag parameter for action is invalid. |
The action contains an invalid parameter. |
The following code example shows a typical invocation failure.
{ "SchemaVersion": "1.0", "Sequence": 2, "InvocationEventType": "ACTION_FAILED", "ActionData": { "Type": "PlayAudio", "Parameters" : { "CallId": "
call-id-1
", "AudioSource": { "Type": "S3", "BucketName": "bucket-name
", "Key": "audio-file.wav
" }, }, "ErrorType": "InvalidAudioSource", "ErrorMessage": "Audio Source parameter value is invalid." } "CallDetails": { ... } }
See working examples on GitHub: