Getting Started with Click To Call SDK

By the end of this guide, you will have a working web application that uses the Cognigy Click To Call SDK to establish a SIP-based voice call from the browser. You will install the SDK, verify browser compatibility, configure a client, and make your first call. The code examples in this guide use TypeScript. If you use plain JavaScript, remove the type annotations.

Prerequisites

A modern web browser with WebRTC support. For more information, refer to Supported Browsers.
Node.js version 18 or later.
A web application where you can install npm packages.
- The web application must be served over HTTPS or from localhost. WebSocket and UDP traffic must be allowed for SIP signaling and media transport.
A Cognigy.AI Flow with a configured Voice Gateway Endpoint.

Install the SDK

Install the SDK in your web application project using npm:
npm install @cognigy/click-to-call-sdk
Verify the installation:
npm list @cognigy/click-to-call-sdk

Configure the Client

Import the SDK, verify browser support, and create a client instance:

import { createWebRTCClient, checkWebRTCSupport } from '@cognigy/click-to-call-sdk';

const support = checkWebRTCSupport();
if (!support.supported) {
  console.error('WebRTC not supported. Missing features:', support.missing);
  throw new Error('Browser does not support WebRTC');
}

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

The endpointUrl parameter must point to a valid Cognigy Voice Gateway Endpoint:

In the Configuration section of the Voice Gateway Endpoint, copy the URL from the Endpoint URL field.

Replace wss:// with https:// and remove /voiceGateway from the path. For example, if your Endpoint URL is:

wss://endpoint-trial.cognigy.ai/d17711ad79bc73f9da03865066201d744386d78cf11651a3377ae35085902268/voiceGateway

Then your endpointUrl will be:

https://endpoint-trial.cognigy.ai/d17711ad79bc73f9da03865066201d744386d78cf11651a3377ae35085902268

The SDK fetches SIP credentials and server details from this URL automatically.

(Optional) Configure Custom STUN/TURN Servers

For advanced use cases, such as specifying custom STUN or TURN servers, provide a pcConfig object when creating the client. Use pcConfig only if your application requires custom NAT traversal or TURN servers. Otherwise, the SDK uses default servers automatically.

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

Register Event Listeners

Set up event listeners before making any calls:

// Connection events
client.on('connecting', () => console.log('Connecting to SIP server...'));
client.on('registered', () => console.log('SIP client registered'));
client.on('disconnected', () => console.log('Disconnected from SIP server'));

// Call events
client.on('answered', (session) => console.log('Call answered. Session ID:', session.id));
client.on('ended', (session, endInfo) => console.log('Call ended. Cause:', endInfo.cause));
client.on('failed', (session, endInfo) => console.error('Call failed. Cause:', endInfo.cause));

// Error handling
client.on('error', (error) => console.error('WebRTC SDK error:', error.message));

Audio playback is automatic. You don’t need to add an <audio> element to your HTML. For advanced use cases, such as custom audio processing or visualization, refer to Custom Audio.

Start and End a Call

With the client configured and events registered, start a voice call:

// Connect and start the call in one step
await client.connectAndCall();

To end the call and clean up:

await client.endCall();
await client.disconnect();

Instead of calling endCall() and disconnect() separately, you can call client.destroy() to end the call, disconnect, and release all resources in one step.

Run and Verify

Combine the code from the previous sections into a single function and bind it to a button click in your web application. A call must be initiated by a user gesture, for example, a button click, because browsers block audio autoplay without user interaction. Refer to the Complete Example.
Start your application and open it in a supported browser.
Open the browser developer console.
Click the button that triggers the call. You should see the following messages in the console:
- Connecting to SIP server... — the SDK is establishing a connection.
- SIP client registered — registration succeeded.
- Call answered. Session ID: ... — the call is active and audio should be playing.

If you don’t hear audio or the call fails to connect, refer to Troubleshooting.

Complete Example

import { createWebRTCClient, checkWebRTCSupport } from '@cognigy/click-to-call-sdk';

async function main() {
  const support = checkWebRTCSupport();
  if (!support.supported) {
    console.error('WebRTC not supported:', support.missing);
    return;
  }

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

  // Connection events
  client.on('connecting', () => console.log('Connecting to SIP server...'));
  client.on('registered', () => console.log('SIP client registered'));
  client.on('disconnected', () => console.log('Disconnected from SIP server'));

  // Call events
  client.on('answered', (session) => console.log('Call answered:', session.id));
  client.on('ended', (session, endInfo) => console.log('Call ended:', endInfo.cause));
  client.on('failed', (session, endInfo) => console.error('Call failed:', endInfo.cause));
  client.on('error', (error) => console.error('Error:', error.message));

  await client.connectAndCall();

  // Clean up when the page unloads.
  // destroy() disconnects the SIP client, ends any active call, and releases all resources.
  window.addEventListener('beforeunload', () => {
    void client.destroy().catch(() => {
    });
  });
}

main();

Overview

Tutorials

Click To Call SDK

Getting Started with Click To Call SDK

Prerequisites

Install the SDK

Configure the Client

(Optional) Configure Custom STUN/TURN Servers

Register Event Listeners

Start and End a Call

Run and Verify

Complete Example

Next Steps

​Prerequisites

​Install the SDK

​Configure the Client

​(Optional) Configure Custom STUN/TURN Servers

​Register Event Listeners

​Start and End a Call

​Run and Verify

​Complete Example

​Next Steps

Prerequisites

Install the SDK

Configure the Client

(Optional) Configure Custom STUN/TURN Servers

Register Event Listeners

Start and End a Call

Run and Verify

Complete Example

Next Steps