Skip to main content
This page explains how the Cognigy Click To Call SDK initializes a connection with 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(), 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() or connectAndCall().
No network requests are made during createWebRTCClient(). The SIP configuration is fetched 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 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.
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() triggers the full connection sequence:
  1. Configuration fetch. The SDK sends an HTTPS GET request to the endpointUrl to retrieve SIP connection parameters (server address, credentials, 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 event. The entire 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 — ready to call'));

await client.connect();
The connectAndCall() 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:
ErrorError SourceRecommended Action
Missing endpointUrlcreateWebRTCClient()Provide a valid endpoint URL.
WebRTC not supportedcreateWebRTCClient()Ensure the browser supports WebRTC. Use checkWebRTCSupport() to verify.
Invalid or unreachable endpointUrlconnect()Verify the URL is correct and accessible over HTTPS.
Backend returns invalid SIP configconnect()Contact your Cognigy administrator.
Click To Call widget not activeconnect()Enable the Click To Call widget in the endpoint configuration.
SIP server unreachableconnect()Check network and firewall settings.
SIP registration rejectedconnect()Verify SIP credentials via the Cognigy backend.
Connection timeout (15 seconds)connect()Check network connectivity and SIP server availability.
CORS error on config fetchconnect()Ensure the backend allows cross-origin requests from your domain.
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

In production, the endpointUrl should point to your production Cognigy environment. Ensure HTTPS is used and the network allows WSS and UDP traffic.
For local development, you can use localhost without HTTPS. Point the endpointUrl to a development or staging Cognigy environment.
If your environment requires specific STUN or TURN servers for NAT traversal, configure them via the pcConfig option during initialization:
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.

​
More Information