Overview

This guide shows how to integrate the NCX React SDK into your application and make full use of its hooks for voice, messaging, and supervisory features.

Setup

Install the SDK

Install the React SDK package and its peer dependencies. For full instructions, refer to the SDK Installation Guide.

Wrap your app in the provider

The NcxSdkProvider uses React’s Context API to expose the SDK instance throughout your app. First, create a new instance of the SDK, then pass it to the provider at the root of your application.

import { Nextiva, NcxSdkProvider } from '@nextiva/ncx-react-sdk';

const sdk = new Nextiva();

<NcxSdkProvider ncxSdk={ sdk }>
	<App />
<NcxSdkProvider>

Access the SDK

Use the useNcxSdk() hook to access the SDK instance in any component.

const sdk = useNcxSdk();

const makeACall =() => {
	sdk.getUserService().dial({ number: '1234567890' });
};

Hooks overview

The SDK provides event hooks and state hooks to integrate seamlessly with your React component lifecycle.

What are hooks?

Hooks allow your React components to subscribe to SDK data, react to real-time events, or access local session state. Event hooks use RxJS under the hood to emit updates. State hooks expose local values managed within the SDK.

Event hooks

Event hooks respond to real-time events emitted by the SDK, like incoming calls, ticket updates, and workitem changes. All event hooks are built on top of the base useSubscription{(...)} hook. These hooks do not store nor return local state. Instead, they execute callbacks when events occur.

Base hook: useSubscription

Subscribes to any SDK event.

import { useSubscription } from '@nextiva/ncx-react-sdk';
useSubscription({
	event: 'WorkitemSummaryNotification',
	subscriptionFn: (summaryNotification) => {
  	Logger.log(summaryNotification);
  	if (
    	summaryNotification.state === 'started' &&
    	activeWorkItem?.workitemId === summaryNotification.workitemId
  	) {
    	setSummaryInProgress(true);
    	// you could display a notification that BE is working on the summary.
    	// block disposition.
  	} else if (summaryNotification.state === 'ended') {
    	// you could display a notification that BE is done working on the summary.
    	// unblock disposition.
    	setSummaryInProgress(false);
  	} else if (summaryNotification.state === 'failed') {
    	setSummaryInProgress(false);
  	}
	},
  });

Prebuilt event hooks

State hooks

State hooks provide access to local SDK-managed session values. These values are reactive. If a value changes (e.g. available devices, user status) the hook will trigger a re-render.

Session and ACD state

User and status

Supervisor and wallboard hooks

Summary

Use these hooks to create responsive UI components that react to calls, workitems, and system statuses without writing your own WebSocket handles or managing complex state.

React-specific user services

file: File
The attachment in the email, if there’s an attachment in the email. force: boolean When a user has some compliance flag and he tries to send an email somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to send the email anyway (force) or cancel. message: string The text of the email. name: string REQUIRED The name of the receiver of the email. option: string

to: string
The email address of the receiver. workitemId: string The unique identifier of the email workitem.

this.userService.sms(payload: SendMessagePayload)

Email

file: File
The attachment in the email, if there’s an attachment in the email. force: boolean When a user has some compliance flag and he tries to send an email somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to send the email anyway (force) or cancel. message: string The text of the email. name: string REQUIRED The name of the receiver of the email. option: string

to: string
The email address of the receiver. workitemId: string The unique identifier of the email workitem.

this.userService.email(payload: SendMessagePayload)

Fax

file: File
The attachment in the email, if there’s an attachment in the email. force: boolean When a user has some compliance flag and he tries to send an email somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to send the email anyway (force) or cancel. message: string The text of the email. name: string REQUIRED The name of the receiver of the email. option: string

to: string
The email address of the receiver. workitemId: string The unique identifier of the email workitem.

this.userService.fax(payload: SendMessagePayload)

this.userService.fax(payload: SendMessagePayload)