How do I troubleshoot Amazon Connect CCP softphone errors?

Short description

Softphone errors occur when your Amazon Connect CCP can't communicate with one of the following required endpoints:

• Signaling endpoints
• Media endpoints
• API endpoints

Resolution

To troubleshoot softphone errors from your Amazon CCP, take the following actions:

• Check whether traffic to the endpoint domain that's in the error message is blocked. If traffic is blocked, then replace Amazon Elastic Compute Cloud (Amazon EC2) and Amazon CloudFront IP range requirements with a domain allowlist.
• Check whether the required port for the endpoint domain that's in the error message is open on your network firewall.
• If you allow IP address ranges, then check whether all IP addresses that Amazon Connect uses are on the required allowlists.
• Check whether your network connection allows the Amazon Connect CCP to maintain a connection with the required endpoints.
• Use the Amazon Connect Endpoint Test Utility to check whether the agent with the issue has a stable connection.
• Check the communication between Amazon Connect and signaling endpoints, media endpoints, and API endpoints.

Signaling endpoints

The following error messages are examples of signaling endpoint errors that you might receive:

• "softphone ERROR {your contact ID} SESSION Failed connecting to signaling server Timeout"
• "softphone ERROR Softphone error occurred : signalling_connection_failure URL {signaling endpoint URL} cannot be reached"

To communicate with signaling endpoints, add the following URLs to your allowlist through Port 443 (TCP):

• For CCP v1: rtc*.connect-telecom.REGION.amazonaws.com
• For CCP v2: *.transport.connect.REGION.amazonaws.com

For more information, see Upgrade to the latest Amazon Connect Contact Control Panel (CCP).

Media endpoints

The following error messages are examples of media endpoint errors that you might receive:

• "softphone WARN {your contact ID} SESSION ICE collection timed out"
• "softphone ERROR {your contact ID} SESSION No ICE candidate"
• "softphone INFO {your contact ID} SESSION ConnectSignalingAndIceCollectionState => FailedState"
• "softphone ERROR Softphone error occurred : ice_collection_timeout Ice collection timedout"

To communicate with media endpoints, add the TurnNlb-*.elb.REGION.amazonaws.com URL to your allowlist through Port 3478 (UDP).

API endpoints

The following error messages are examples of API endpoint errors that you might receive:

• "ccp ERROR 'acceptContact' API request failed: [object Object]"
• "ccp TRACE AWSClient: < Operation 'acceptContact' failed: {"message":"Network Failure","code":"NetworkingError","time":"....""

Note: To turn your raw CCP logs into a user-friendly format, use the CCP Log Parser. For more information, see CCP Log Parser on the GitHub website.

To communicate with API endpoints, add the following URLs to your allowlist through Port 443 (TCP):

• *.telemetry.connect.REGION.amazonaws.com
• INSTANCE_NAME.my.connect.aws/ccp-v2
• INSTANCE_NAME.my.connect.aws/api
• *.static.connect.aws
• INSTANCE_NAME.awsapps.com/connect/ccp-v2
• INSTANCE_NAME.awsapps.com/connect/api
• *.cloudfront.net

Note: Replace INSTANCE_NAME with your instance name. Replace REGION with the AWS Region where your Amazon Connect instance is located. For more information, see Set up your network to use the Amazon Connect Contact Control Panel (CCP).

Related information

Troubleshooting Issues with the Contact Control Panel (CCP)