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

# Initialization and Authentication

> Learn how the Click To Call SDK initializes, authenticates, and exchanges SIP credentials with the Cognigy backend.

This page explains how the Cognigy Click To Call SDK connects to the Cognigy backend. It also covers authentication, credential exchange, and how to configure initialization for different environments.

## Initialization Steps

When you call [`createWebRTCClient()`](https://docs-classic.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 sets up its internal components and event handlers.
4. The SDK returns the client. Then you can call [`connect()`](https://docs-classic.cognigy.com/click-to-call/sdk/api-reference/connect) or [`connectAndCall()`](https://docs-classic.cognigy.com/click-to-call/sdk/api-reference/connect-and-call).

> [!NOTE]
>
> `createWebRTCClient()` doesn't make network requests. The SDK fetches the SIP configuration later, when you call `connect()` or `connectAndCall()`.

```typescript theme={null}
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 you call `connect()`, the SDK sends a request to this URL and receives the SIP server address and the information it needs to connect. The response must contain an active Click To Call widget configuration.

The SDK uses this information internally. Your application code doesn't handle SIP credentials.

### User Identification

The optional `userId` parameter identifies the user in the SIP session. The SDK doesn't send it with the configuration request. If you don't provide a `userId`, the SDK generates one.

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

> [!NOTE]
>
> The `userId` is used to identify the session 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-classic.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`. The request retrieves 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, the SDK throws an error.
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 WebSocket connection to the SIP server.
5. **SIP REGISTER**. If the endpoint requires registration, the SDK sends a SIP REGISTER request. Some endpoints don't require registration, and the SDK skips this step for them.
6. **Connection confirmed**. `connect()` resolves once the WebSocket connection is established. If the endpoint requires registration, it resolves only after the SIP registration also succeeds. In that case, the SDK emits the [`registered`](https://docs-classic.cognigy.com/click-to-call/sdk/event-reference/registered) event. After the configuration fetch, the process has a 15-second timeout.

```typescript theme={null}
client.on('connecting', () => console.log('Opening WebSocket connection...'));
client.on('connected', () => console.log('WebSocket connected'));
client.on('registered', () => console.log('SIP registration complete')); // Only for endpoints that require registration

await client.connect();
```

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

## 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`, or a non-successful HTTP response | `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. `connect()` fails with the timeout error after 15 seconds. |
| 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. |
| `connect()` called after `destroy()` | `connect()` | Create a new client with `createWebRTCClient()`. The error is `Client has been destroyed`. |

The errors from `connect()` start with `Failed to connect:`, except `Client has been destroyed`. For example, `Failed to connect: Operation timed out after 15000ms`.

```typescript theme={null}
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

> [accordion] Production
>
> In production, point the `endpointUrl` to your production Cognigy environment. Use HTTPS and make sure the network allows WSS and UDP traffic.

> [accordion] Development and Testing
>
> For local development, you can use `localhost` without HTTPS. Point the `endpointUrl` to a development or staging Cognigy environment.

## More Information

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


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