## 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:

```javascript
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`](https://docs.cognigy.com/click-to-call/sdk/event-reference/ended) or [`failed`](https://docs.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 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`](https://docs.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`**. Transcription events are only emitted when an incoming info message contains a `_transcription` property. Regular info messages are emitted via [`infoReceived`](https://docs.cognigy.com/click-to-call/sdk/event-reference/info-received) instead.

## Browser Issues

### Click To Call Not Supported

**Symptom**: [`checkWebRTCSupport()`](https://docs.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`. 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:

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

### Event-Based

Subscribe to the [`error`](https://docs.cognigy.com/click-to-call/sdk/event-reference/error) event to catch asynchronous errors during the SDK lifecycle:

```javascript
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:

```javascript
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.