Initialization and Authentication

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(), the SDK performs the following initialization sequence:

The SDK validates that endpointUrl is provided.
The SDK checks that the current environment supports WebRTC (via isWebRTCSupported()).
The SDK sets up its internal components and event handlers.
The SDK returns the client. Then you can call connect() or connectAndCall().

createWebRTCClient() doesn’t make network requests. The SDK fetches the SIP configuration later, when you call connect() or connectAndCall().

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.

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

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() triggers the full connection sequence:

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.
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.
SIP User Agent creation. The SDK creates a JsSIP User Agent using the retrieved SIP credentials and WebSocket URI.
WebSocket connection. The SDK opens a WebSocket connection to the SIP server.
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.
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 event. After the configuration fetch, the process has a 15-second timeout.

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() 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.

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, point the endpointUrl to your production Cognigy environment. Use HTTPS and make sure 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.

Overview

Tutorials

Click To Call SDK

Initialization Steps

Authentication

Endpoint-Based Authentication

User Identification

Connection and Registration

Handling Initialization Errors

Environment Configuration

More Information

​Initialization Steps

​Authentication

​Endpoint-Based Authentication

​User Identification

​Connection and Registration

​Handling Initialization Errors

​Environment Configuration

​More Information

Initialization Steps

Authentication

Endpoint-Based Authentication

User Identification

Connection and Registration

Handling Initialization Errors

Environment Configuration

More Information