Overview

In this tutorial, you’ll learn how to:

Log in and initialize the Nextiva NCX SDK
Retrieve customer and contact information
Search and filter contact lists
Fetch detailed contact records by ID
Retrieve ticket data associated with contacts
Access ticket interactions and conversation history
Listen to work item events in real time

By the end, you’ll understand how to use the NCX SDK to display customer context within your application.

Prerequisites

Before starting, make sure you have:

A Nextiva developer account and API credentials
Node.js installed
A package manager (npm or yarn)
A working Nextiva tenant with call-enabled users
Browser support for WebRTC

Install the SDK

SDK Installation

List customer contacts

The getSchemaTypeClient().search() API retrieves contact records.

Without search

Used when listing all contacts without filtering by a keyword.

q (search keyword) is not required.
Pagination (rows, start), sorting, and filtering (ownerType) are optional.

With search

Used when searching for contacts by name, email, phone, etc.

q is required.
Pagination and sorting options are supported.

Feature	Without Search	With Search
`q` (search term)	❌ Not used	✅ Required
Pagination (`rows`, `start`)	✅ Optional	✅ Optional
Sorting / Filtering	✅ Optional	✅ Optional

Example

const response = await sdk.getSchemaTypeClient().search(schemaType, payload);

Parameters

schemaType (string, required) – Must be 'contact'.
payload (object, optional) – Use for pagination, filters, or search.

If you don’t need pagination or filtering:

const response = await sdk.getSchemaTypeClient().search('contact');

Advanced usage (with payload)

const payload = {
  rows: 50, // Number of records (default 100)
  start: 0, // Pagination offset (default 0)
  queryParams: {
    sort: 'c.name+asc',   // Sort by contact name ascending
    ownerType: 'tenant',  // Filter by owner type
  },
  q: '[email protected]' // Keyword search
};

const schemaType = 'contact';
const response = await sdk.getSchemaTypeClient().search(schemaType, payload);

Retrieve contact details by ID

Use the contact’s unique ID to get detailed information (name, email, notes).

Method

sdk.getSchemaTypeClient().retrieve(schemaType, payload);

Parameter	Type	Required	Description
`schemaType`	string	Yes	Use `'contact'`
`id`	string	Yes	Unique contact identifier

Example

async function getContactById(contactId) {
  try {
    const schemaType = 'contact';
    const contact = await sdk.getSchemaTypeClient().retrieve(schemaType, { id: contactId });
    return contact;
  } catch (error) {
    console.error('Failed to retrieve contact:', error);
    throw error;
  }
}

// Usage
getContactById('648c1aaad595317ad487858d')
  .then(contact => console.log(contact))
  .catch(err => console.error('Error fetching contact:', err));

Sample response

{
  "firstName": "Shikamaru",
  "lastName": "Nara",
  "contactId": "686f72b958a35402da6b9f92",
  ...
}

Retrieve tickets by contact ID

Fetch all tickets (open, in-progress, closed, etc.) associated with a contact.

Method

sdk.getSchemaTypeClient().search(schemaType, payload);

Parameter	Type	Description
`schemaType`	string	Use `'ticket'`
`payload`	object	Contains query parameters
`payload.queryParams.contactId`	string	Contact ID

Example

async function getTicketsByContactId(contactId) {
  try {
    const schemaType = 'ticket';
    const payload = {
      queryParams: { contactId },
    };

    const tickets = await sdk.getSchemaTypeClient().search(schemaType, payload);
    return tickets;
  } catch (error) {
    console.error('Failed to retrieve tickets:', error);
    throw error;
  }
}

// Usage
getTicketsByContactId('686f72b958a35402da6b9f92')
  .then(tickets => console.log(tickets))
  .catch(err => console.error('Error fetching tickets:', err));

Notes

The contactId must be valid.
Returns all tickets linked to the contact.

Sample response

{
  "total": 0,
  "objects": [
    {
      "ticketId": "DDXP-5723",
      "status": "2",
      "agentId": "671b3a9d6c0b74027cc0b50c",
      "contactId": "686f72b958a35402da6b9f92",
      ...
    }
  ],
  "count": 1
}

Retrieving Ticket Interactions and Rich Text Details by Ticket ID

To display all interactions and rich text details for a given ticket:

Schema-based request

sdk.getSchemaTypeClient().request(schemaType, schemaLink, payload);

Parameters

Name	Type	Description
`schemaType`	string	Main schema, e.g., `'ticket'`
`schemaLink`	string	Operation name, e.g., `'workticketByTicket'`
`payload`	object	Includes `replacements` key with ticket ID

Example

const schemaType = 'ticket';
const ticketId = 'DDXP-5723';
const schemaLink = 'workticketByTicket';
const payload = {
  replacements: { id: ticketId },
};

const workTicketResponse = await sdk.getSchemaTypeClient().request(
  schemaType,
  schemaLink,
  payload
);

Real-time context updates

📘
Contact updates in the NCX portal do not emit events. (Requires developer attention.)

WorkItem event notifications

The SDK emits the following event types as work items change state:

WorkitemStateChangeNotification
WorkitemRemovedNotification
EngagementDataStatusUpdateNotification
UpdateTicketNotification
WorkitemDeletedNotification
WorkitemTerminatedNotification
WorkitemProgressiveNotification
WorkitemPredictiveNotification
WorkitemConversationMessageNotification

Listening to workitem events

import { EventTypes } from '@nextiva/ncx-web-sdk';

let subscription = null;

function listenWorkItemEvents() {
  subscription = sdk.events$.subscribe((event) => {
    const eventType = event.name;

    switch (eventType) {
      case EventTypes.WorkitemStateChangeNotification:
        handleWorkitemStateChange(event.data);
        break;
      default:
        console.debug('Unhandled event type:', eventType, event.data);
        break;
    }
  });

  console.log('Subscribed to NCX SDK work item events');
}

/**
 * Handles work item state change events.
 */
function handleWorkitemStateChange(data) {
  // Add business logic here
}

function cleanupOnUnload() {
  if (subscription) {
    subscription.unsubscribe();
    console.log('Unsubscribed from NCX SDK events');
  }
}

listenWorkItemEvents();
window.addEventListener('beforeunload', cleanupOnUnload);

Notes

Initialize the SDK before subscribing to events.
Always unsubscribe on page unload to prevent leaks.
For contact updates, real-time events are not currently supported; consider submitting a feature request to the NCX API team.