Overview

This guide shows how to integrate the NCX Web SDK into your application and make full use of its services for voice, messaging, and supervisory features. The SDK simplifies working with backend services and supports updates via WebSockets. It’s compatible with JavaScript frameworks like Vue, Angular, and vanilla JS.

Installation

To begin, install the SDK via npm. For full instructions, refer to the SDK Installation Guide.

npm install @nextiva/ncx-web-sdk

SDK Setup

Once installed, create a new instance of the SDK and register it with your application.

All frameworks

import i18n, { type TOptions } from 'i18next';
import { Nextiva, type Translations, type ITranslator } from '@nextiva/ncx-web-sdk';

class Translator implements ITranslator {
  load(language: string, translations: Translations): void {
    i18n.addResourceBundle(language, 'translation', translations);
  }

  translate(key: string, options: TOptions): string {
    return i18n.t(key, options);
  }
}

const sdk = new Nextiva({
  baseURL: 'YOUR_API_BASE_URL',
  debug: true,
  language: 'en',
  translator: new Translator(),
});

Vue

createApp(App)
  .provide('ncxSdk', sdk)
  .mount('#app');

📘
Note
Angular support assumes you’re handling dependency injection and lifecycle appropriately. A shared service is usually created to wrap the SDK instance.

Authentication

Before accessing SDK services, you must log in and initialize the SDK. This ensures all services are properly configured and authorized.

Login and initialization

Logging in is the same for all frameworks.

const login = await sdk.login(username, password);

if (login?.token) {
    await ncxSdk?.init();
}

Vue

import {inject} from 'vue';
const ncxSdk = inject<Nextiva>('ncxSdk');

const login = await ncxSdk?.login(username.value, password.value)

if (login?.token) {
    await ncxSdk?.init();
}

Angular

import {inject} from 'angular';
const ncxSdk = inject<Nextiva>('ncxSdk');

const login = await ncxSdk?.login(username.value, password.value)

if (login?.token) {
    await ncxSdk?.init();
}

JavaScript

import {inject} from '';
const ncxSdk = inject<Nextiva>('ncxSdk');

const login = await ncxSdk?.login(username.value, password.value)

if (login?.token) {
    await ncxSdk?.init();
}

Making calls

Once authenticated and initialized, you can use the SDKs UserServices to place calls. The dial() method supports multiple parameters that enable calling modes.

Parameter	Description
to	destination number
campaignId	campaign ID for the call
context	context string (if needed)
workitemId	work item ID (if applicable)
force	boolean to force the dial attempt
spoofWorkitemId	optional spoofing info
option, name, etc.	additional optional params

Vue

import {inject} from 'vue';
const ncxSdk = inject<Nextiva>('ncxSdk');

    await ncxSdk?.getUserService().dial({
      campaignId,
      conferenceWorkitemId,
      contactId,
      context,
      force,
      name,
      option,
      spoofWorkitemId,
      to,
      workitemId,
    });

Angular / JavaScript example

The syntax is identical if you’ve initialized and injected the SDK correctly.

import {inject} from 'angular';
const ncxSdk = inject<Nextiva>('ncxSdk');

    await ncxSdk?.getUserService().dial({
      campaignId,
      conferenceWorkitemId,
      contactId,
      context,
      force,
      name,
      option,
      spoofWorkitemId,
      to,
      workitemId,
    });

SDK Services

The SDK exposes several services for working with NCX features like:

UserService
- Authentication, calling, presence
CampaignService
- Campaign management
CallService
- WebRTC and call control
QueueService
- Queue monitoring
NotificationService
- Real-time event handling

Troubleshooting

Ensure a valid login and configuration before calling sdk.init()
Confirm valid phone numbers are available for testing
SDK must be initialized after a successful login response containing a token
Use browser dev tools to verify WebSocket and REST network activity