Speak

You can play speech on any call leg by providing text. You can use plain text or Speech Synthesis Markup Language (SSML). SSML provides more control over how the Amazon Chime SDK generates speech by adding pauses, emphasizing certain words, or changing the speaking style.

The Amazon Chime SDK uses the Amazon Polly service to convert text-to-speech. Amazon Polly allows you to choose between either the standard or neural engine for improved speech quality. Amazon Polly supports more than 20 languages and 60 voices to customize your application's user experience. The Amazon Chime SDK provides speech features at no charge, but you do pay for using Amazon Polly. See the Amazon Polly pricing page or your billing dashboard for pricing information.

Using the Speak action

The following example shows a typical use of the Speak action.

{
    "SchemaVersion": "1.0",
    "Actions":[
        {
            "Type": "Speak",
            "Parameters": {
                "Text": "Hello, World!",        // required
                "CallId": "call-id-1",          // required
                "Engine": "neural",             // optional. Defaults to standard
                "LanguageCode": "en-US",        // optional
                "TextType": "text",             // optional
                "VoiceId": "Joanna"             // optional. Defaults to Joanna
            }
        }
    ]
}

Handling ACTION_SUCCESSFUL events

The following example shows a typical ACTION_SUCCESSFUL event for an action which synthesizes the text "Hello World" into speech, in English, using the Amazon Polly's Joanna voice.

{
    "SchemaVersion": "1.0",
    "Sequence": 3,
    "InvocationEventType": "ACTION_SUCCESSFUL",
    "ActionData": {
       "Type": "Speak",
       "Parameters": {
          "CallId": "call-id-1",          
          "Engine":  "neural",             
          "LanguageCode":  "en-US",        
          "Text": "Hello World",          
          "TextType":  "text",             
          "VoiceId":  "Joanna"        
       }
    },
    "CallDetails":{       
       ...
    }
}

Handling ACTION_FAILED events

The following example shows a typical ACTION_FAILED event for the same event used in the previous example.

{
    "SchemaVersion": "1.0",
    "Sequence":2,
    "InvocationEventType": "ACTION_FAILED",
    "ActionData":{
       "Type": "Speak",
       "Parameters": {
          "CallId": "call-id-1",          
          "Engine":  "neural",             
          "LanguageCode":  "en-US",        
          "Text": "Hello  World",          
          "TextType":  "text",             
          "VoiceId":  "Joanna"        
       },
       "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.

Program flows

The following diagram shows the program flow that enables the Speak action for a caller. In this example, the caller hears text that

In the diagram

Using a soft phone, a caller enters a number registered to a SIP media application. The application uses the SIP INVITE method and sends the caller a Trying (100) response. That indicates that the next-hop server received the call request. The SIP application then uses INVITE to contact the endpoint. Once the connection is established, the applications sends Ringing (180) response to the caller, and alerting begins.

The SIP media application then sends a NEW_INBOUND_CALL event to the Lambda function, which responds with a Speak action that includes the caller's ID and the text that you want to convert into speech. The SIP application then sends a 200 (OK) response to indicate that the call was answered. The protocol also enables the media.

If the Speak action succeeds and converts the text to speech, it returns an ACTION_SUCCESSFUL event to the SIP media application, which returns the next set of actions. If the action fails, the SIP media application sends an ACTION_FAILED event to the Lambda function, which responds with a set of Hangup actions. The application hangs up the caller and returns a HANGUP event to the Lambda function, which takes no further actions.

The following diagram shows the program flow than enables the Speak action for a callee.

In the diagram

A caller enters a number registered to a SIP media application, and the application responds as described for the previous diagram. When the Lambda function receives the NEW_INBOUND_CALL event, it returns the CallAndBridge action to the SIP application. The application then uses the SIP INVITE method to send the Trying (100) and Ringing (180) responses to the callee.

If the callee answers, the SIP media application recieves a 200 (OK) response, and it sends the same response to the caller. That establishes media, and the SIP application sends an ACTION_SUCCESSFUL event for the CallAndBridge action to the Lambda function. The function then returns the Speak action and data to the SIP application, which converts