Diagnosing an agent's softphone problem: a worked example
An agent says calls "ring but there's no audio" or "drop after a few seconds", and the CTR only shows a normal disconnect. The answer is usually in the agent's CCP log, which records what the browser, the WebRTC stack and the Connect backend were doing on that agent's machine.
Step 1: Collect the log straight after the problem
Ask the agent to download the log from the CCP Settings panel (Download logs) as soon as the issue happens, and to note the approximate time. The log is a rolling buffer, so a log taken hours later may no longer contain the failed call. If you run a custom CCP built on Amazon Connect Streams, make sure your page exposes the same download option, for example with connect.getLog().download().
Step 2: Load it and go to the failing call
Drop the file here. The parser groups entries by severity and shows API calls, agent state snapshots and softphone events on one timeline. Filter to ERROR and WARN, then go to the reported time.
Step 3: Match the error to a cause
Softphone failures are reported with specific error types. The most common ones and what they usually mean:
- MICROPHONE_NOT_SHARED: the browser has no microphone permission, or another application holds the device. Check site permissions and the default input device.
- ICE_COLLECTION_TIMEOUT: the browser could not gather network candidates in time. This almost always means a firewall, VPN or proxy is blocking UDP media. Compare the rules against the Allowlist Auditor.
- SIGNALLING_CONNECTION_FAILURE or SIGNALLING_HANDSHAKE_FAILURE: the secure WebSocket used for call setup was blocked or interrupted, often by a proxy doing TLS inspection.
- WEBRTC_ERROR or REALTIME_COMMUNICATION_ERROR: media failed after setup. Look for network changes (Wi-Fi roaming, VPN reconnect) just before.
- UNSUPPORTED_BROWSER: an outdated or unsupported browser version.
Step 4: Check skew and latency
A large clock skew between the agent's PC and AWS can break authentication and make timestamps misleading, so fix the PC's time sync. Consistently high API latency points at the agent's network path rather than Connect itself.
Patterns to recognise
- "Ringing then dropped" with an ICE timeout: media ports blocked. Usually affects every agent on the same site or VPN.
- One agent only, with microphone errors: a local device or permission issue. Re-select the headset, check the browser's site settings, and close other softphone apps.
- Random drops with state flapping between Available and Offline: an unstable connection or the browser throttling a background tab. Keep the CCP in its own window rather than a hidden tab.
- Problems only on VDI: audio is going through the virtual desktop instead of being optimised. See the VDI Compatibility Tester.
Before escalating to AWS Support
Gather the CCP log, the ContactId of an affected call, the agent's browser version, the network path (office, home, VPN, VDI) and the result of the Agent Workstation Validator. With that, Support can usually skip the first round of questions.