## Documentation Index

Fetch the complete documentation index at: [/llms.txt](https://docs.cognigy.com/llms.txt)

Use this file to discover all available pages before exploring further.

This page explains how the Cognigy Click To Call SDK initializes a connection to the Cognigy backend, how authentication and credential exchange work, and how to configure the initialization flow for different environments.

## Initialization Steps

When you call [`createWebRTCClient()`](https://docs.cognigy.com/click-to-call/sdk/api-reference/create-click-to-call-client), the SDK performs the following initialization sequence:

1. The SDK validates that `endpointUrl` is provided.
2. The SDK checks that the current environment supports WebRTC (via `isWebRTCSupported()`).
3. The SDK creates internal managers (`ConfigManager`, `SipManager`, `SessionManager`, `AudioManager`) and wires up event handlers.
4. The client is returned, ready to call [`connect()`](https://docs.cognigy.com/click-to-call/sdk/api-reference/connect) or [`connectAndCall()`](https://docs.cognigy.com/click-to-call/sdk/api-reference/connect-and-call).

No network requests are made during `createWebRTCClient()`. The SIP configuration is fetched later when you call `connect()` or `connectAndCall()`.

```javascript
import { createWebRTCClient } from '@cognigy/click-to-call-sdk';

// Step 1–3 happen inside createWebRTCClient()
const client = await createWebRTCClient({
  endpointUrl: 'https://your-cognigy-environment.com/token',
  userId: 'user-123',
});
```

## Authentication

### Endpoint-Based Authentication

The SDK authenticates with the Cognigy backend through the `endpointUrl`. When the SDK fetches the SIP configuration, the Cognigy backend:

1. Validates the endpoint configuration.
2. Generates short-lived SIP credentials scoped to the session.
3. Returns the credentials along with the SIP server address.

The SDK manages these credentials internally — they are never exposed to your application code.

### User Identification

The optional `userId` parameter is sent to the Cognigy backend as part of the configuration request. It allows the backend to:

- Associate the Click To Call session with a specific user in Cognigy.AI.
- Correlate call data with user sessions in Cognigy Insights.
- Route calls to the correct AI Agent Flow.

```javascript
const client = await createWebRTCClient({
  endpointUrl: 'https://your-cognigy-environment.com/token',
  userId: 'user-123', // Identifies the user in the Cognigy session
});
```

The `userId` is used for session identification only. Don’t pass sensitive information such as passwords, tokens, or personally identifiable information (PII) as the `userId`.

## Connection and Registration

After initialization, calling [`connect()`](https://docs.cognigy.com/click-to-call/sdk/api-reference/connect) triggers the full connection sequence:

1. **Configuration fetch**. The SDK sends an HTTPS `GET` request to the `endpointUrl` to retrieve SIP connection parameters such as server address, credentials, and application SID. The request has a 10-second timeout.
2. **Widget validation**. The SDK verifies that the Click To Call widget is active in the endpoint configuration. If it’s not active, an error is thrown.
3. **SIP User Agent creation**. The SDK creates a JsSIP User Agent using the retrieved SIP credentials and WebSocket URI.
4. **WebSocket connection**. The SDK opens a WSS (WebSocket Secure) connection to the SIP server.
5. **SIP REGISTER**. The SDK sends a SIP REGISTER request using the credentials obtained from the endpoint.
6. **Registration confirmed**. Once both the WebSocket connection is established and SIP registration succeeds, the SDK emits the [`registered`](https://docs.cognigy.com/click-to-call/sdk/event-reference/registered) event. The entire process has a 15-second timeout.

```javascript
client.on('connecting', () => console.log('Opening WebSocket connection...'));
client.on('connected', () => console.log('WebSocket connected'));
client.on('registered', () => console.log('SIP registration complete — ready to call'));

await client.connect();
```

The [`connectAndCall()`](https://docs.cognigy.com/click-to-call/sdk/api-reference/connect-and-call) convenience method performs the same sequence and immediately starts a call after registration.

## Handling Initialization Errors

If initialization or authentication fails, the SDK throws an error from `createWebRTCClient()` or `connect()`. Common errors include:

| Error | Error Source | Recommended Action |
| --- | --- | --- |
| Missing `endpointUrl` | `createWebRTCClient()` | Provide a valid endpoint URL. |
| WebRTC not supported | `createWebRTCClient()` | Ensure the browser supports WebRTC. Use `checkWebRTCSupport()` to verify. |
| Invalid or unreachable `endpointUrl` | `connect()` | Verify the URL is correct and accessible over HTTPS. |
| Backend returns invalid SIP config | `connect()` | Contact your Cognigy administrator. |
| Click To Call widget not active | `connect()` | Enable the Click To Call widget in the endpoint configuration. |
| SIP server unreachable | `connect()` | Check network and firewall settings. |
| SIP registration rejected | `connect()` | Verify SIP credentials via the Cognigy backend. |
| Connection timeout (15 seconds) | `connect()` | Check network connectivity and SIP server availability. |
| CORS error on config fetch | `connect()` | Ensure the backend allows cross-origin requests from your domain. |

```javascript
try {
  const client = await createWebRTCClient({
    endpointUrl: 'https://your-cognigy-environment.com/token',
    userId: 'user-123',
  });
  await client.connect();
} catch (error) {
  console.error('Initialization failed:', error.message);
}
```

## Environment Configuration

**Production**

In production, the `endpointUrl` should point to your production Cognigy environment. Ensure HTTPS is used and the network allows WSS and UDP traffic.

**Development and Testing**

For local development, you can use `localhost` without HTTPS. Point the `endpointUrl` to a development or staging Cognigy environment.

**Custom ICE Servers**

If your environment requires specific STUN or TURN servers for NAT traversal, configure them via the `pcConfig` option during initialization:

```javascript
const client = await createWebRTCClient({
  endpointUrl: 'https://your-cognigy-environment.com/token',
  userId: 'user-123',
  pcConfig: {
    iceServers: [
      { urls: 'stun:stun.l.google.com:19302' },
      {
        urls: 'turn:your-turn-server.com:3478',
        username: 'user',
        credential: 'password'
      }
    ]
  }
});
```

For more details on ICE or TURN configuration, refer to [Security — Network Security](https://docs.cognigy.com/click-to-call/sdk/security#network-security).

## More Information

- [createWebRTCClient](https://docs.cognigy.com/click-to-call/sdk/api-reference/create-click-to-call-client)
- [connect](https://docs.cognigy.com/click-to-call/sdk/api-reference/connect)
- [Security](https://docs.cognigy.com/click-to-call/sdk/security)
- [Troubleshooting](https://docs.cognigy.com/click-to-call/sdk/troubleshooting)