VoiceFocus

Enables you to apply Amazon Voice Focus noise suppression to inbound and outbound call legs on a public switched telephony network (PSTN) call. When you apply Amazon Voice Focus, it reduces background noise without impacting human speech. This can make the current speaker easier to hear.

To create inbound call legs, you use a SIP rule that invokes an AWS Lambda function with a NewInboundCall event. You can create outbound call legs by using the CallAndBridge action, or by using a CreateSIPMediaApplicationCall API operation. For more information about Amazon Voice Focus, see How the Amazon Chime SDK's noise cancellation works.

Amazon Voice Focus reduces unwanted, non-speech noises, including:

• Environment noises—wind, fans, running water

• Background noises—lawnmowers, barking dogs

• Foreground noises—typing, paper shuffling

Note

When you use Amazon Voice Focus, AWS bills you for the active call minutes of each call leg and for each minute of SIP media application usage.

This example shows a typical VoiceFocus action.

{
    "SchemaVersion": "1.0",
    "Actions":[
        {
            "Type": "VoiceFocus",
            "Parameters": {
                "Enable": True|False,            // required
                "CallId": "call-id-1",           // required    
            }
        }
    ]
}

Enable

Description – Enables or disables Amazon Voice Focus

Allowed values – True | False

Required – Yes

Default value – None

CallId

Description – CallId of participant in the CallDetails of the AWS Lambda function invocation

Allowed values – A valid call ID

Required – Yes

Default value – None

This example shows a successful ACTION_SUCCESSFUL event for the VoiceFocus action.

{
   "SchemaVersion": "1.0",
   "Sequence": 3,
   "InvocationEventType": "ACTION_SUCCESSFUL",
   "ActionData": {
      "Type": "VoiceFocus",
      "Parameters": {
         "Enable": True,
         "CallId": "call-id-1"
      }
   },
   "CallDetails":{
      .....
      .....
      "Participants":[
         {
            "CallId": "call-id-of-caller",
            .....   
            "Status": "Connected"
         },
         {
            "CallId": "call-id-of-callee",
            .....
            "Status": "Connected"
         }
      ]
   }
}

This example shows a typical ACTION_FAILED event for the VoiceFocus action.

{
   "SchemaVersion": "1.0",
   "Sequence":2,
   "InvocationEventType": "ACTION_FAILED",
      "ActionData":{
      "Type": "VoiceFocus",
      "Parameters": {
         "Enable": True,
         "CallId": "call-id-1"
      }
      },
      "ErrorType": "SystemException",
      "ErrorMessage": "System error while running action"
   },
   "CallDetails":{
      .....
      .....
      "Participants":[
         {
            "CallId": "call-id-of-caller",
            .....   
         }
      ]
   }
}

Error handling

For security reasons, the PSTN Audio actions have a limit of 5 call requests per second, per customer account (CPS). When call requests exceed the 5 CPS limit, the action returns an error message. This table lists the error messages returned by the VoiceFocus action.

Error	Message	Reason
ActionExecutionThrottled	Failed to run action. The maximum number of actions per second has been reached.	The number of Voice Focus action requests per second exceeded the system limit.
MissingRequiredActionParameter	Missing required action parameter.	Missing one or more of the required parameters while running the action.
SystemException	System error while running action.	A system error occurred while running the action.

Call flows

This diagram shows the call flow for enabling and disabling Amazon Voice Focus for a CallAndBridge action between two PSTN calls.