SpeakAndGetDigits
Play speech by providing text and gather dual tone multi-frequency (DTMF) digits from
the user. The text can either be plain text or Speech Synthesis Markup Language
(SSML)-enhanced text to provide more control over how the Amazon Chime SDK generates speech by adding
pauses, emphasizing certain words, or changing the speaking style, among other supported
SSML features. If a failure occurs, such as a user not entering the correct number of DTMF
digits, the action plays the "failure" speech and then replays the main speech until the SIP
media application exhausts the number of attempts defined in the Repeat
parameter.
The Amazon Chime SDK uses Amazon Polly, a cloud service that converts text into lifelike speech, Amazon Polly
provides both a standard and a neural engine for improved speech quality, more than 20
supported languages, and 60 voices. Amazon Polly provides speech features at no charge, but you do
pay for using Amazon Polly. See the Amazon Polly pricing page
Important
Use of Amazon Polly is subject to the AWS
Service Terms
Topics
Using the SpeakAndGetDigits action
The following example shows a typical use of the SpeakAndGetDigits
action:
{ "SchemaVersion": "1.0", "Actions":[ { "Type": "SpeakAndGetDigits", "Parameters": { "CallId": "
call-id-1
", // required "InputDigitsRegex": "^\d{2}#$
", // optional "SpeechParameters": { "Text": "Hello World
", // required "Engine": "neural
", // optional. Defaults to standard "LanguageCode": "en-US
", // optional "TextType": "text
", // optional "VoiceId": "Joanna
" // optional. Defaults to Joanna }, "FailureSpeechParameters": { "Text": "Hello World
", // required "Engine": "neural
", // optional. Defaults to the Engine value in SpeechParameters "LanguageCode": "en-US
", // optional. Defaults to the LanguageCode value in SpeechParameters "TextType": "text
", // optional. Defaults to the TextType value in SpeechParameters "VoiceId": "Joanna
" // optional. Defaults to the VoiceId value in SpeechParameters }, "MinNumberOfDigits":3
, // optional "MaxNumberOfDigits":5
, // optional "TerminatorDigits": ["#
"], // optional "InBetweenDigitsDurationInMilliseconds":5000
, // optional "Repeat":3
, // optional "RepeatDurationInMilliseconds":10000
// required } } ] }
- CallId
-
Description – The
CallId
of participant in the CallDetails of the Lambda function invocation.Allowed values – A valid
callID
Required – Yes
Default value – No
- InputDigitsRegex
-
Description – A regular expression pattern to help ensure that users enter the correct digits and letters.
Allowed values – A valid regular expression pattern
Required – No
Default value – None
- SpeechParameters.Engine
-
Description – Specifies the engine – standard or neural – to use when processing text for speech synthesis.
Allowed values –
standard
|neural
Required – No
Default value – Standard
- SpeechParameters.LanguageCode
-
Description – Specifies the language code. This is only necessary if using a bilingual voice. If a bilingual voice is used and no language code is specified, the bilingual voice's default language is used.
Allowed values – Amazon Polly language codes
Required – No
Default value – None
- SpeechParameters.Text
-
Description – Specifies the input text. If you specify
ssml
as theSpeechParameters.TextType
, you must follow the SSML format for the input text. For more information about SSML, see Generating Speech from SSML Documents in the Amazon Polly Developer Guide.Allowed values – String
Required – Yes
Default value – None
- SpeechParameters.TextType
-
Description – Specifies the text format for
SpeechParameters.Text
. If not specified,text
is used by default. For more information about SSML, see Generating Speech from SSML Documents in the Amazon Polly Developer Guide.Allowed values –
ssml
|text
Required – No
Default value –
text
- SpeechParameters.VoiceId
-
Description – The ID of the Amazon Polly voice used to speak the text in
SpeechParameters.Text
.Allowed values – Amazon Polly voice IDs
Required – No
Default value – Joanna
- FailureSpeechParameters.Engine
-
Description – Specifies the engine – standard or neural – to use when processing the failure message used when the customer enters an invalid response for speech synthesis.
Allowed values –
standard
|neural
Required – No
Default value – The
SpeechParameters.Engine
value - FailureSpeechParameters.LanguageCode
-
Description – Specifies the language code used when the customer enters an invalid response. Only necessary when using a bilingual voice. If you use bilingual voice without specifying a language code, the bilingual voice's default language is used.
Allowed values – Amazon Polly language codes
Required – No
Default value – The
SpeechParameters.LanguageCode
value. - FailureSpeechParameters.Text
-
Description – Specifies the input text spoken when the customer enters an invalid response. If you specify
ssml
as theFailureSpeechParameters.TextType
, you must follow the SSML format for the input text.Allowed values – String
Required – Yes
Default value – None
- FailureSpeechParameters.TextType
-
Description – Specifies whether the input text specified in
FailureSpeechParameters.Text
is plain text or SSML. The default value is plain text. For more information, see Generating Speech from SSML Documents in the Amazon Polly Developer Guide.Allowed values –
ssml
|text
Required – No
Default value – The
SpeechParameters.Text
value - FailureSpeechParameters.VoiceId
-
Description – The ID for the voice used to speak the string in
FailureSpeechParameters.Text
.Allowed values – Amazon Polly voice IDs
Required – Yes
Default value – The
SpeechParameters.VoiceId
value - MinNumberOfDigits
-
Description – The minimum number of digits to capture before timing out or playing the "call failed" message.
Allowed values – Greater than or equal to zero
Required – No
Default value – 0
- MaxNumberOfDigits
-
Description – The maximum number of digits to capture before stopping without a terminating digit.
Allowed values – Greater than
MinNumberOfDigits
Required – No
Default value – 128
- TerminatorDigits
-
Description – Digit used to end input if the user enters less than the MaxNumberOfDigits
Allowed values – Any one of: 0 1 2 3 4 5 6 7 8 9 # or *
Required – No
Default value – #
- InBetweenDigitsDurationInMilliseconds
-
Description – The wait time in milliseconds between digit inputs before playing the failure speech.
Allowed values – Greater than zero
Required – No
Default value – If not specified, defaults to the
RepeatDurationInMilliseconds
value - Repeat
-
Description – Total number of attempts to get digits. If you omit this parameter, the default is one attempt to collect digits.
Allowed values – Greater than zero
Required – No
Default value – 1
- RepeatDurationInMilliseconds
-
Description – Timeout in milliseconds for each attempt to get digits.
Allowed values – Greater than zero
Required – Yes
Default value – None
Handling ACTION_SUCCESSFUL events
The following example shows a typical ACTION_SUCCESSFUL
event.
{ "SchemaVersion": "1.0", "Sequence": 3, "InvocationEventType": "ACTION_SUCCESSFUL", "ActionData": { "Type": "SpeakAndGetDigits", "Parameters": { "CallId": "
call-id-1
", "InputDigitsRegex": "^\d{2}#$
", "SpeechParameters": { "Engine": "neural
", "LanguageCode": "en-US
", "Text": "Hello World
", "TextType": "text
", "VoiceId": "Joanna
" }, "FailureSpeechParameters": { "Engine": "neural
", "LanguageCode": "en-US
", "Text": "Hello World
", "TextType": "text
", "VoiceId": "Joanna
" }, "MinNumberOfDigits":3
, "MaxNumberOfDigits":5
, "TerminatorDigits": ["#
"], "InBetweenDigitsDurationInMilliseconds":5000
, "Repeat":3
, "RepeatDurationInMilliseconds":10000
}, "ReceivedDigits": "1234
" }, "CallDetails":{ ... } }
Handling ACTION_FAILED events
The following example shows a typical ACTION_FAILED
event.
{ "SchemaVersion": "1.0", "Sequence":2, "InvocationEventType": "ACTION_FAILED", "ActionData":{ "Type": "SpeakAndGetDigits", "Parameters": { "CallId": "
call-id-1
", "InputDigitsRegex": "^\d{2}#$
", "SpeechParameters": { "Engine": "neural
", "LanguageCode": "en-US
", "Text": "Hello World
", "TextType": "text
", "VoiceId": "Joanna
" }, "FailureSpeechParameters": { "Engine": "neural
", "LanguageCode": "en-US
", "Text": "Hello World
", "TextType": "text
", "VoiceId": "Joanna
" }, "MinNumberOfDigits":3
, "MaxNumberOfDigits":5
, "TerminatorDigits": ["#
"], "InBetweenDigitsDurationInMilliseconds":5000
, "Repeat":3
, "RepeatDurationInMilliseconds":10000
}, "ErrorType": "SystemException", "ErrorMessage": "System error while running action" }, "CallDetails":{ ... } }
Error handling
This table lists and describes the error messages thrown by the the Speak
action.
Error | Message | Reason |
---|---|---|
|
The |
The role used to make requests to Amazon Polly doesn't exist or is missing permissions. To resolve, see the steps in the Using the Amazon Chime SDK Voice Connector service-linked role section |
|
|
There was an error validating the action parameters. To review the available parameters for this action, and their options, see SynthesizeSpeech in the Amazon Polly Developer Guide. |
|
|
The action parameters must have a |
|
|
The text exceeded the character limit. |
|
System error while running action. |
A system error occurred while running the action. |
Using the Amazon Chime SDK Voice Connector service-linked role
You don't need to manually create a service-linked role for the Speak
or SpeakAndGetDigits
actions. When you create or update a SIP media
application in the Amazon Chime SDK console, the AWS Command Line Interface, or the AWS API, the Amazon Chime SDK creates the
service-linked role for you.
For more information, see Using the Amazon Chime service-linked role in the Amazon Chime SDK Administrator Guide.