> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognigy.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Diagnose and fix common connection issues, WebRTC errors, and call failures in the Cognigy Click To Call SDK.

This page covers common issues you may encounter when using the Cognigy Click To Call SDK and how to resolve them.

## Connection Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Call Issues

<AccordionGroup>
  <Accordion title="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.
  </Accordion>

  <Accordion title="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:

      ```typescript theme={null}
      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".
  </Accordion>

  <Accordion title="Call Drops Unexpectedly">
    **Symptom**: The [`ended`](/click-to-call/sdk/event-reference/ended) or [`failed`](/click-to-call/sdk/event-reference/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.
  </Accordion>
</AccordionGroup>

## Transcription Issues

<AccordionGroup>
  <Accordion title="Transcription Events Not Received">
    **Symptom**: The [`transcription`](/click-to-call/sdk/event-reference/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`](/click-to-call/sdk/event-reference/info-received) instead.
  </Accordion>
</AccordionGroup>

## Browser Issues

<AccordionGroup>
  <Accordion title="Click To Call Not Supported">
    **Symptom**: [`checkWebRTCSupport()`](/click-to-call/sdk/api-reference/check-click-to-call-support) 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](https://developer.mozilla.org/en-US/docs/Web/Security/Secure_Contexts) such as HTTPS or `localhost`. Ensure your application is served over HTTPS.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>

## Error Handling

The SDK supports two complementary approaches for catching errors.

<AccordionGroup>
  <Accordion title="Promise-Based">
    All async methods return promises. Wrap them in the `try` and `catch` blocks:

    ```typescript theme={null}
    try {
      await client.connect();
      await client.startCall();
    } catch (error) {
      console.error('Operation failed:', error.message);
    }
    ```
  </Accordion>

  <Accordion title="Event-Based">
    Subscribe to the [`error`](/click-to-call/sdk/event-reference/error) event to catch asynchronous errors during the SDK lifecycle:

    ```typescript theme={null}
    client.on('error', (error) => {
      console.error('Click To Call SDK error:', error.message);
    });
    ```
  </Accordion>
</AccordionGroup>

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

## Debugging Tips

<AccordionGroup>
  <Accordion title="Enable Event Logging">
    Register listeners for all key events to trace the SDK lifecycle:

    ```typescript theme={null}
    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));
    ```
  </Accordion>

  <Accordion title="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.
  </Accordion>

  <Accordion title="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.
  </Accordion>
</AccordionGroup>