​

Debug Data & Call Quality Analysis

​

Data Collection Methods

​

Method 1: Call Reports (Production)

const client = new TelnyxRTC({
  login_token: jwt,
  enableCallReports: true,
  callReportInterval: 5000,
});

​

Method 2: Debug Reports (Deep Troubleshooting)

const client = new TelnyxRTC({
  login_token: jwt,
  enableCallReports: true,  // Collect call stats
  debug: true,              // Enable debug mode
  debugOutput: 'file',      // Write debug data to a file
});

• Full ICE candidate list with timestamps
• DTLS handshake state
• SDP offer/answer with codec negotiation
• Packet-level stats (bytes, packets, loss per direction)
• Audio level measurements

​

Accessing debug data

curl "http://voice-sdk-call-report-stats.query.prod.telnyx.io:4000/api/v1/calls/{user_id}/{call_id}"

​

Interpreting debug data

​

Method 3: Console Debug (Development)

const client = new TelnyxRTC({
  login_token: jwt,
  debug: true,
});

​

Method 4: Debug Visualizer

const client = new TelnyxRTC({
  login_token: jwt,
  debug: true,
  debugOutput: 'socket',  // Send to visualizer
});

• Call timeline with state transitions
• ICE candidate gathering progress
• DTLS handshake status
• Audio quality graphs (RTT, jitter, packet loss)
• Media flow direction

​

Common Issues & Diagnosis

​

One-Way Audio

1. Is DTLS connected? → ice_data.transport.dtls_state === "connected"
2. Is audio being sent? → Check bytesSent in stats
3. Is audio being received? → Check bytesReceived in stats
4. Which candidate type? → ice_data.selected_pair shows host/srflx/relay

• Asymmetric TURN relay (two nominated candidate pairs, one sending and one receiving)
• Firewall blocks media in one direction
• VPN interferes with ICE candidates

If dtls_state: "connecting" and ice_state: "connected"
→ DTLS handshake failing. Check for multiple NICs or asymmetric routing.

If bytesSent > 0 but bytesReceived = 0
→ Audio is being sent but not received. Check remote firewall.

If bytesSent = 0 and bytesReceived > 0
→ Audio is being received but not sent. Check local microphone permissions.

​

Call Doesn’t Connect

1. WebSocket state → client.connection.connected
2. ICE state → ice_data.transport.ice_state
3. STUN accessibility → Any srflx candidates?

• Firewall blocks rtc.telnyx.com:443 (signaling)
• Firewall blocks stun.telnyx.com:3478 (STUN)
• Firewall blocks turn.telnyx.com:3478 (TURN over UDP/TCP)
• Firewall blocks turn2.telnyx.com:443 (TURNS — TURN over TLS, last-resort fallback)
• No relay candidates and symmetric NAT

​

Choppy Audio

1. Jitter → stats.jitter > 50ms is poor
2. Packet loss → stats.packetLoss > 3% is poor
3. RTT → stats.rtt > 300ms is poor

• WiFi congestion (high jitter)
• Network congestion (high packet loss)
• Long routing path (high RTT)
• VPN adding latency

​

Echo

• Built-in speakers + mic without echo cancellation
• Two audio elements playing the same stream
• Headset echo cancellation not working

• Recommend headphones
• Ensure only one audio element is active per call
• Check browser echo cancellation settings

​

Quick Diagnostic Script

(async () => {
  const client = window.__telnyxClient; // Your client instance
  const calls = client.calls;

  console.log('=== Telnyx Call Diagnostic ===');
  console.log(`Active calls: ${calls.length}`);
  console.log(`Connected: ${client.connection.connected}`);

  for (const call of calls) {
    console.log(`
Call ${call.id}: state=${call.state}, direction=${call.direction}`);
    console.log(`  Remote: ${call.remotePartyNumber}`);

    const pc = call.peerConnection;
    if (pc) {
      const stats = await pc.getStats();
      stats.forEach(report => {
        if (report.type === 'candidate-pair' && report.nominated) {
          console.log(`  ICE: state=${report.state}, RTT=${report.currentRoundTripTime * 1000}ms`);
        }
        if (report.type === 'inbound-rtp' && report.kind === 'audio') {
          console.log(`  Audio In: packets=${report.packetsReceived}, lost=${report.packetsLost}, jitter=${report.jitter}`);
        }
        if (report.type === 'outbound-rtp' && report.kind === 'audio') {
          console.log(`  Audio Out: packets=${report.packetsSent}`);
        }
      });
    }
  }
})();

​

See Also

• Call Report Stats — Full stats API reference
• Error Handling — Error and warning codes
• Network Requirements — Firewall and connectivity
• IClientOptions — debug, debugOutput
• Best Practices — Quality monitoring