Troubleshooting - Cognigy Documentation

Connection Issues

Client Fails to Connect

Symptom: Calling connect() or connectAndCall() throws an error or times out.
Possible Causes and Solutions:

• Incorrect endpoint URL. Verify that the endpointUrl in your configuration is correct and accessible. The URL must point to a valid Cognigy Click To Call configuration endpoint.
• Network restrictions. Ensure that your network allows WebSocket connections and UDP traffic, both of which are required for SIP/WebRTC communication. Check firewall and proxy settings.
• CORS issues. If the SDK can’t fetch the SIP configuration, the endpoint server may not be configured to allow cross-origin requests from your domain.

SIP Registration Fails

Symptom: The registered event is never emitted, or the error event emits after connecting.
Possible Causes and Solutions:

• Invalid SIP credentials. The SIP configuration returned by the endpoint URL may contain invalid credentials. Contact your Cognigy administrator to verify the configuration.
• SIP server unreachable. Ensure that the SIP server is reachable from the client’s network. Network firewalls may block the required ports.

Call Issues

Call Not Starting

Symptom: startCall() throws an error or doesn’t initiate a call.
Possible Causes and Solutions:

• Client not connected. Ensure that connect() has been called and the registered event has been received before calling startCall(). Alternatively, use connectAndCall() to combine both steps.
• Microphone permission denied. The browser requires microphone access for Click To Call calls. Ensure that the user has granted microphone permission.

No Audio

Symptom: The call connects, but no audio is heard.
Possible Causes and Solutions:

• Autoplay policy. Modern browsers block autoplay of media with audio. Ensure that the call is initiated by a user gesture, for example, a button click. The SDK manages audio playback internally via an Audio element, but browser autoplay restrictions still apply.
• ICE/TURN configuration. If audio doesn’t work, it may be a NAT traversal issue. Configure a TURN server in the pcConfig option:

const client = await createWebRTCClient({
    endpointUrl: 'https://your-api.com/voice-connect-config',
    pcConfig: {
      iceServers: [
        { urls: 'stun:stun.l.google.com:19302' },
        {
          urls: 'turn:your-turn-server.com:3478',
          username: 'user',
          credential: 'password'
        }
      ]
    }
});

• No audio tracks in stream. The remote stream may not contain audio tracks. Check the browser developer console for warnings from the SDK such as “Stream has no audio tracks”.

Call Drops Unexpectedly

Symptom: The ended or failed event emits shortly after the call starts.
Possible Causes and Solutions:

• Network instability. Check the network connection. Click To Call is sensitive to network changes, especially on mobile devices.
• Session timeout. The SIP server may have a session timeout configuration. Check the CallEndInfo object in the ended or failed event callback for the cause, originator, and description fields.

Transcription Issues

Transcription Events Not Received

Symptom: The transcription event is never emitted during a call.
Possible Causes and Solutions:

• Transcription not enabled. Ensure that transcription is enabled in your Voice Gateway or Cognigy Flow configuration.
• Info messages without _transcription. Transcription events are only emitted when an incoming info message contains a _transcription property. Regular info messages are emitted via infoReceived instead.

Browser Issues

Click To Call Not Supported

Symptom: checkWebRTCSupport() returns { supported: false }.
Possible Causes and Solutions:

• Unsupported browser. The SDK requires a browser that supports WebRTC APIs: RTCPeerConnection, getUserMedia.
• Insecure context. WebRTC APIs are only available in secure contexts such as HTTPS or localhost. Ensure your application is served over HTTPS.

Microphone Permission Issues

Symptom: The browser prompts for microphone access but the call fails.
Possible Causes and Solutions:

• Permission denied. The user must grant microphone permission. If denied, the browser won’t allow access to the local audio stream.
• Permission previously blocked. If the user previously blocked microphone access, they need to manually reset the permission in the browser’s site settings.

Error Handling

The SDK supports two complementary approaches for catching errors.

Promise-Based

All async methods return promises. Wrap them in the try and catch blocks:

try {
  await client.connect();
  await client.startCall();
} catch (error) {
  console.error('Operation failed:', error.message);
}

Event-Based

Subscribe to the error event to catch asynchronous errors during the SDK lifecycle:

client.on('error', (error) => {
  console.error('Click To Call SDK error:', error.message);
});

Combine both approaches. The try and catch blocks capture errors from direct calls, while the error event handles asynchronous errors.

Debugging Tips

Enable Event Logging

Register listeners for all key events to trace the SDK lifecycle:

client.on('connecting', () => console.log('[WebRTC] Connecting...'));
client.on('connected', () => console.log('[WebRTC] Connected'));
client.on('registered', () => console.log('[WebRTC] Registered'));
client.on('disconnected', () => console.log('[WebRTC] Disconnected'));
client.on('answered', (s) => console.log('[WebRTC] Answered:', s.id));
client.on('ended', (s, info) => console.log('[WebRTC] Ended:', info));
client.on('failed', (s, info) => console.error('[WebRTC] Failed:', info));
client.on('error', (err) => console.error('[WebRTC] Error:', err.message));

Inspect WebRTC Internals

In Chrome, navigate to chrome://webrtc-internals/ to view detailed information about active WebRTC connections, including ICE candidates, codec negotiation, and media statistics.

Check Network Traffic

Use the browser’s DevTools Network tab to inspect WebSocket connections and verify that the SIP signaling messages are being exchanged correctly.