Workitems

Summary

The Workitem Schema Type is a core data structure in the Nextiva SDK, representing a single, trackable unit of work. Workitems can be inbound or outbound calls, emails, chats, SMS messages, or other channel interactions. This document provides a comprehensive overview of the Workitem schema, its structure, and the primary methods for interacting with it.

Unlike simpler schemas that use a purely generic client, Workitems are managed through a dedicated Workitems Service (sdk.getWorkitemsService()) for most actions, which in turn utilizes the generic SchemaTypeClient for searching and querying.

What is a Workitem?

A Workitem is an object that encapsulates a customer interaction from start to finish. It contains all relevant data, such as the contact involved, the channel of communication, its current status (e.g., inqueue, active, terminated), and a timeline of events.

Typical use cases include:

• Tracking an inbound phone call from the moment it enters a queue to when it is dispositioned.
• Managing an email conversation with a customer.
• Representing a chat session with an agent.
• Handling state changes, such as placing a call on hold or transferring it to another agent.

Structure of a Workitem

A Workitem object is composed of many fields that define its identity, state, and context. Below is a summary of some of the most important fields.

Field summary

Key states and types

The behavior of a workitem is heavily dependent on its state, type, and channelType. These are defined as enums in the SDK.

• Workitem States (WorkitemState):
  • inqueue: Waiting to be assigned to an agent.
  • offered: Being offered to an agent.
  • accepted: Accepted by an agent, but not yet active.
  • active: The agent is actively engaged with the workitem.
  • hold: The workitem is on hold.
  • conference: The workitem is part of a conference.
  • terminated: The interaction has ended but is not yet dispositioned.
  • dispositioned: The workitem has been completed and dispositioned by the agent.
• Workitem Types (WorkitemType):
  • InboundCall, OutboundCall, PredictiveCall
  • InboundEmail, OutboundEmail
  • InboundSMS, OutboundSMS
  • Chat, Facebook, Instagram, Twitter, Whatsapp
• Channel Types (ChannelType):
  • voice, email, sms, chat, videoMeeting

Example object

import { Workitem, WorkitemStates, WorkitemTypes, ChannelTypes } from '@ncx/ncx-core-sdk';

const exampleWorkitem: Workitem = {
  _id: "60c72b2f9b1e8e0007c8e8e9",
  workitemId: "wi_12345",
  tenantId: "t_abcde",
  channelType: ChannelTypes.VOICE,
  type: WorkitemTypes.InboundCall,
  state: WorkitemStates.Active,
  currentStateName: "active",
  priority: 3,
  contactId: "ct_67890",
  agentUsername: "jason.fontenot",
  selectedQueue: "q_support",
  createdAt: 1678982400000,
  assignedAt: 1678982460000,
  terminatedAt: 0,
  from: "+18005551212",
  to: "+18005559999",
  actions: ["hold", "hangup", "transfer"],
  timeEvents: [
    { type: "answered", timestamp: 1678982460000, userId: "jason.fontenot" }
  ],
  // ...many other fields
};

Interacting with Workitems

The primary entry point for managing workitems is the Workitems Service, which provides specialized methods for fetching data and changing state.

Get the Workitems service

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

const sdk = new Nextiva({ /* ...configuration */ });
const workitemsService = sdk.getWorkitemsService();

Fetch Workitems

To retrieve a single workitem by its ID:

const workitem: Workitem = await workitemsService.fetchWorkitem("wi_12345");
To search for a list of workitems, use fetchWorkitems. This method uses the generic SchemaTypeClient’s search functionality under the hood, so the payload is a standard search query.
import { FetchWorkitemsResponseBody } from '@ncx/ncx-core-sdk/types/workitem';

const searchResults: FetchWorkitemsResponseBody = await workitemsService.fetchWorkitems({
  q: "state:active AND channelType:voice", // Search query
  rows: 25,
  start: 0,
});

console.log(`Found ${searchResults.total} active voice workitems.`);

State management and actions

The WorkitemsService provides specific methods for performing actions on a workitem, which often result in a state change.

Place a Workitem on hold

await workitemsService.hold({
  workitemId: "wi_12345",
  hold: true, // true to hold, false to unhold
});

End a Workitem (hanging up)

await workitemsService.hangUp({
  workitemId: "wi_12345",
});

Transfer a Workitem to a queue

await workitemsService.transferToQueue({
  workitemId: "wi_12345",
  queueId: "q_another_queue",
});

Permissions

Workitem permissions follow the standard model, ensuring users can only perform actions they are authorized for.