> ## Documentation Index
> Fetch the complete documentation index at: https://docs-classic.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 with the Cognigy Click To Call SDK and how to resolve them.

## Connection Issues

> [accordion] 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**. Make sure your network allows WebSocket connections and UDP traffic. SIP/WebRTC communication needs both. Check firewall and proxy settings.
> * **CORS issues**. If the SDK can't fetch the SIP configuration, the endpoint server might not allow cross-origin requests from your domain.

> [accordion] SIP Registration Fails
>
> **Symptom**: The `registered` event is never emitted, or the `error` event emits after connecting.
>
> > [!NOTE]
> >
> > Endpoints that don't require SIP registration never emit the `registered` event. In this case, the missing event isn't an error.
>
> **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

> [accordion] Call Not Starting
>
> **Symptom**: `startCall()` throws an error or doesn't initiate a call.
>
> **Possible Causes and Solutions**:
>
> * **Client not connected**. Call `connect()` and wait for it to finish before you call `startCall()`. If your endpoint requires registration, `connect()` finishes after the `registered` event. If you call `startCall()` before that, it fails with `Client not connected. Call connect() first.` or `SIP client not registered`. 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] 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. Start the call from a user gesture, for example, a button click. The SDK plays audio through an internal `Audio` element, but browser autoplay restrictions still apply.
> * **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] Call Control Methods Fail
>
> **Symptom**: `endCall()`, `mute()`, `sendInfo()`, or `sendDTMF()` rejects with an error that contains `No active session` or `Session not established`.
>
> **Possible Causes and Solutions**:
>
> * **Call not answered yet**. These methods work only on an answered call. While the call is ringing, they fail. Wait for the [`answered`](https://docs-classic.cognigy.com/click-to-call/sdk/event-reference/answered) event before you call them.
> * **Call already ended**. After the call ends or fails, no session is active.
>
> The errors have the following format:
>
> | Method | Error |
> | - | - |
> | `endCall()` | `Failed to end call: No active session to terminate` |
> | `mute()` | `Failed to mute call: No active session to mute` or `Failed to mute call: Session not established` |
> | `sendInfo()` | `Failed to send info: No active session to send info` |
> | `sendDTMF()` | `Failed to send DTMF: No active session to send DTMF` |
>
> The `unmute()` method does nothing if there's no answered call and doesn't throw an error.

> [accordion] Call Drops Unexpectedly
>
> **Symptom**: The [`ended`](https://docs-classic.cognigy.com/click-to-call/sdk/event-reference/ended) or [`failed`](https://docs-classic.cognigy.com/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 might have a session timeout configured. Check the `cause`, `originator`, and `description` fields of the `CallEndInfo` object. You get this object in the `ended` or `failed` event callback.

## Transcription Issues

> [accordion] Transcription Events Not Received
>
> **Symptom**: The [`transcription`](https://docs-classic.cognigy.com/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`**. The SDK emits a `transcription` event only when an incoming info message contains a `_transcription` property. Regular info messages are emitted via [`infoReceived`](https://docs-classic.cognigy.com/click-to-call/sdk/event-reference/info-received) instead.

## Browser Issues

> [accordion] Click To Call Not Supported
>
> **Symptom**: [`checkWebRTCSupport()`](https://docs-classic.cognigy.com/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`. Serve your application over HTTPS.

> [accordion] 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 the user denies it, the browser blocks access to the local audio stream.
> * **Permission previously blocked**. If the user blocked microphone access before, they must reset the permission manually in the browser's site settings.

## Error Handling

The SDK supports two complementary approaches for catching errors.

> [accordion] 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] Event-Based
>
> Subscribe to the [`error`](https://docs-classic.cognigy.com/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);
> });
> ```

> [!TIP]
>
> Combine both approaches. The `try` and `catch` blocks capture errors from direct calls, while the `error` event handles asynchronous errors.

## Debugging Tips

> [accordion] 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] Inspect WebRTC Internals
>
> In Chrome, open `chrome://webrtc-internals/`. The page shows active WebRTC connections, including ICE candidates, codec negotiation, and media statistics.

> [accordion] Check Network Traffic
>
> Use the **Network** tab in the browser's DevTools. Inspect the WebSocket connections to check that the SIP signaling messages are exchanged correctly.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.