Overview

A workitem is an object representing a unit of work or interaction within the Nextiva platform, such as a call, message, email, or other communication channel event that needs to be managed, processed, or tracked. In technical terms, a workitem typically contains:

A unique identifier (workItemId)
Information about its current state and actions (e.g., active, on hold, in conference)
Metadata about the communication (such as participants, time events, and priority)
Channel type (voice, chat, email, etc.)

Workitems are central to handling customer interactions, enabling features like call control, conferencing, transfers, voicemails, and tracking the lifecycle of each interaction within the platform.

This service enables developers to manage workitems such as calls, messages, and conferences. You'll be able to receive notifications coming from the server, and can link to the system notification. This service also enables developers to handle WorkitemStateChange events.

Key features

The WorkitemsService class provides methods for managing and manipulating workitems in Nextiva. The class has the following key features:

Call management
1. Put on hold, retrieve
Message handling
1. transfer
Conference management
Notification processing
1. Receive notifications from the server
Contact association
Survey management

Basic usage

At the basic level, the WorkitemsService class can be used to fetch workitems, get a specific workitem, or handle a call.

Possible actions for a call

Answering a call
Putting a call on hold

// Fetch workitems
const workitems = await workitemsService.fetchWorkitems();

// Get a specific workitem
const workitem = await workitemsService.fetchWorkitem('workitem-id');

// Handle a call
await workitemsService.active(workitem);
await workitemsService.hold(workitem);
await workitemsService.hangUp(workitem);

API reference

Call management

active(model: Workitem | string)

Activates a call for a given workitem. Can use the workitem or workitem ID as a parameter.

// Using the workitem object
await workitemsService.active(workitem);

// Using the workitem ID
await workitemsService.active('workitem-123');

Parameters

Can use the workitem or workitem ID as a parameter.

workitem object
The workitem object.

workitem ID string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

hold(model: Workitem | string)

Puts a call on hold. Can use the workitem or workitem ID as a parameter.

await workitemsService.hold(workitem);

Parameters

Can use the workitem or workitem ID as a parameter.

workitem object
The workitem object.

workitem ID string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

hangUp(model: Workitem | string)

Ends a call. Can use the workitem or workitem ID as a parameter.

await workitemsService.hangUp(workitem);

Can use the workitem or workitem ID as a parameter.

workitem object
The workitem object.

workitem ID string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

mute

Mutes the workitem sent in the payload.

await workitemsService.mute(workitem)

Parameters

workitem object
The workitem object.

Returns

A promise of a workitem with a mute property of 1 that means it’s muted.

unmute

Unmutes the workitem sent in the payload.

await workitemsService.unMute(workitem)

Parameters

workitem object
The workitem object.

Returns

A promise of a workitem with a mute property of 0 that means it’s unmuted. Promise<Workitem>

Voicemail

Sends a predefined voicemail message to a specific user’s call ID.

await workitemsService.voicemail(workitem)

Parameters

workitem object
The workitem object.

Returns

A promise of a workitem with voicemailFile property with the signedUrl that has the link to the audio file and transcriptionMessage property. Promise<Workitem>

voicemailPlayed

Marks a voicemail as read or unread based on the played parameter, the voicemail audio file doesn’t have to be played to change the voicemail status.

await workitemsService.voicemailPlayed(workitem)

Parameters

workitem object
The workitem object.
played boolean
Indicates whether the voicemail was played or not. If the value is TRUE, the voicemail has been played.

Returns

A promise of a workitem with a vmStatus of 1 or 0, 1 being played and 0 being not played. Promise<Workitem>

changePriority

Changes the priority of a workitem with a given value.

await workitemsService.changePriority(workitem)

Parameters

workitemID string
The unique identifier of the workitem associated with the call.
priority
export const WorkItemPriorities = { High: 4, Highest: 5, Low: 2, Lowest: 1, Standard: 3, } as const;
- The priority of the workitem. A number between 1 and 5, the higher the number, the higher the priority.
  Highest: 5, High: 4, Standard: 3, Low: 2, Lowest: 1

Returns

A promise of a workitem. Promise<Workitem>

fetchWorkitem

Fetches a workitem.

await workitemsService.fetchWorkitem(workitemId)

Parameters

workitemId string
The unique identifier of the workitem being fetched.

Returns

A promise of a workitem. Promise<Workitem>

fetchWorkitems

If you lost connectivity to the network, even for a fraction of a second, you need to re-sync with the server to see if you received a call, voicemail, SMS.

Fetches all workitems.

await workitemsService.fetchWorkitems(workitem)

Parameters

payload SchemaTypeSearchPayload
- q string
  The string to query from
- queryParams Record<string, unknown>;
  Property you want to query from. Could be the queue, the id of the
workitem
- rows number
  The number of workitems returned.
- start number
  How many items to skip for pagination

Returns

export interface FetchWorkitemsResponseBody {
 count: number;
 objects?: Workitem[];
 total: number;
}

missCallDialed

Marks a missed call as read or unread based on the played parameter.

await workitemsService.missedCallDialed(workitem, played)

Parameters

model workitem
The complete workitem
played boolean
Indicates whether the missed call was played or not. If the value is TRUE, the missed call has been played.

Returns

A promise of a workitem. Promise<Workitem>

warmTransfer

Performs a warm transfer.

📘
Note
To do a Warm transfer, you first have to create a Conference with the transfering agent and the client.

[Cold Transfer][#TransferToAgent]

The original agent transfers the call (workitem) to another agent or destination without speaking to the receiving party first. The call is immediately routed to the new agent, and the original agent disconnects from the call.
The receiving agent picks up the call without any prior context or introduction from the transferring agent.

✍️
Use case
Fast handoff when context is not needed or when the receiving agent is expected to handle the call from scratch.

[Warm Transfer]

The original agent first speaks with the receiving agent before completing the transfer. The agent can provide context, introduce the caller, and ensure the receiving agent is ready to take over. Once the receiving agent is prepared, the call is transferred, and the original agent can optionally stay on the line briefly (consultative transfer) or disconnect.

✍️
Use case
Ensures a smooth handoff, provides context, and improves customer experience.

await workitemsService.warmTransfer(workitem)

Parameters

payload 
WarmTransferPayload {
dispositionId?: string;
 	eventName?: string;
 	extendedWork?: boolean;
 	recording?: WorkitemRecordingOption;
 	surveyResult?: unknown;
 	workitemIds?: string[];
}

Returns

A promise of a workitem. `Promise<Workitem>

Recording

startRecording(model: Workitem)

Starts recording a call. The recording property is called record: number;

await workitemsService.startRecording(workitem);

Parameters

workitem object
The workitem.

Returns

void

stopRecording(model: Workitem)

Stops recording a call.

await workitemsService.stopRecording(workitem);

Parameters

workitem object
The workitem.

Returns

void

Conference management

createConference()

Creates a new conference (two or more users in a call).

await workitemsService.createConference();

Returns

A promise of a workitem. Promise<Workitem>

createConferenceWithWorkitems(payload: CreateConferenceWithWorkitemsPayload)

Creates a conference with specified workitems where you can decide to add yourself to the conference or not (the addMe parameter).

await workitemsService.createConferenceWithWorkitems({
  addMe: true,
  workitemIds: ['workitem-1', 'workitem-2']
});

Parameters

addMe boolean
Whether the user wants to be added to the conference or not.
workitemIds array
An array of unique identifiers of the workitems that will be added to the conference.

Returns

A promise of a workitem. Promise<Workitem>

addToConference(workitemId: string)

Adds a workitem to an existing conference.

await workitemsService.addToConference('workitem-123');

Parameters

workitemID string
The unique identifier of the workitem associated with the conference call.
options AddToConferenceOptions
- beep: boolean;
  If you want the beep played before the conference.
- music: boolean;
  If set to true music will be played before the caller joins the conference.
- musicURL: string;
  The URL of the music to be played.
- muted: boolean;
  If you want the caller who’s joining the conference to be muted when they join.
- record: boolean;
  If you want to record the conference call

Returns

A promise of a workitem. Promise<Workitem>

removeFromConference(payload: RemoveFromConferencePayload)

Removes a workitem from a conference. Actions can be hold, active, or hangup.

await workitemsService.removeFromConference({
  action: 'hold',
  workitemId: 'workitem-123'
});

Parameters

action string
Possible Values: ’hold’, active, hangup Whether the conference call was put on hold, made active or, hung up.

Workitem ID string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

Transfers

transferToAgent(payload: TransferToAgentPayload)

Transfers a workitem to another agent.

await workitemsService.transferToAgent({
  eventName: 'Transfer to Agent',
  recording: true,
  survey: 'survey-1',
  userId: 'agent-123',
  workitemId: 'workitem-456'
});

Paramters

eventName string
The name given to the transfer.
recording
Possible Values: ’keepCurrent’, startRecording, stopRecording Whether the transfer was recorded or not.
survey string
The unique identifier of the survey associated with the workitem. Don’t have survey yet.
userID REQUIRED string
The unique identifier of the user associated with the workitem.
workitemID REQUIRED string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

transferToInbox(payload: TransferToInboxPayload)

Transfers a workitem to an inbox.

What is an inbox?

An inbox refers to a logical grouping or queue of workitems (such as calls, messages, or tasks) that is assigned to a specific team, department, or group of agents. Inbox is not the same as a personal email inbox. Instead, it represents a shared queue in a contact center environment. Workitems can be transferred to an inbox, making them available for any agent assigned to that inbox to pick up and handle.

This is useful for distributing workload, managing overflow, or routing interactions to specialized teams (e.g., Billing Inbox, Support Inbox).
In the SDK, there are payloads and methods such as TransferToInboxPayload and transferToInbox that facilitate moving a workitem from an individual agent or another queue into a designated inbox.

✍️
Use case
If an agent receives a call but determines it should be handled by the billing department, they can transfer the workitem to the Billing Inbox. Any available agent in that inbox can then take ownership of the call.

await workitemsService.transferToInbox({
  eventName: 'Transfer to Inbox',
  inboxId: 'inbox-123',
  recording: true,
  survey: 'survey-1',
  workitemId: 'workitem-456'
});

Parameters

eventName string
The name of the transfer
inboxID REQUIRED string
The ID of the inbox the workitem was transferred to.
recording
Possible Values: ’keepCurrent’, startRecording, stopRecording Whether the transfer was recorded or not.
survey string
The unique identifier of the survey associated with the call.
WorkitemID REQUIRED string
The unique identifier of the workitem associated with the call.

Returns

A promise of a workitem. Promise<Workitem>

transferToExternal(payload: TransferToExternalPayload)

Transfers a workitem to an external system and the workitem/call is released from the SDK.

await workitemsService.transferToExternal({
  extendedWork: true,
  workitemId: 'workitem-123',
  // Additional transfer parameters
});

Parameters

eventName string
The name of the transfer
extendedWork boolean
Keeps the workitem active on the agent screen.
campaignID string
The unique identifier of the campaign the workitem was transferred to.
dispositionID string
The unique identifier of the disposition of the workitem.
number REQUIRED string
The number associated with the workitem.
recording WorkitemRecordingOption
Possible Values: keepCurrent, startRecording, stopRecording Whether the transfer was recorded or not.
surveyResult
Record<string, unknown>
WorkitemID REQUIRED string
The unique identifier of the workitem that was transferred.

Returns

A promise of a workitem. Promise<Workitem>

Message handling

sendEmailResponse(workitemId: string, properties: SendEmailResponsePayload)

Sends an email response for a workitem.

await workitemsService.sendEmailResponse('workitem-123', {
  body: 'Email response body',
  subject: 'Response subject',
  to: '[email protected]'
});

Parameters

WorkitemID string
The unique identifier of the workitem associated with the email.
SendEmailResponsePayload
- bccAddresses an array of strings
  Any email addresses blind copied in the email.
- bodyParts record
  The body parts of an email
body string
The body of the email response.
ccAddresses an array of strings
Any email addresses copied in the email response.
createdAt number
The time the email was created.
from string
The email address sending the email sending the email response.
subject string
The subject of the email response.
to string
The email address the email response will be sent to, if being sent to one email address.
toAddresses an array of strings
The email addresses the email response will be sent to, if sending to multiple email addresses.

Returns

A promise of a workitem. Promise<Workitem>

Survey management

saveSurveyResult(payload: SaveSurveyResultPayload)

Saves the results of surveys associated with a workitem.

await workitemsService.saveSurveyResult({
  workitemId: 'workitem-123',
  ticketId: 'ticket-456', // Optional
  data: {
    currentSurveyId: 'survey-789',
    'survey-789': {
      // Survey result data
      question1: 'answer1',
      rating: 5
    }
  }
});

Parameters

SaveSurveyResultPayload

WorkitemID REQUIRED string
The unique identifier of the workitem associated with the survey.
ticketID string
The unique identifier of any ticket associated with the survey.
data object
Contains the data within the survey
- SurveyId REQUIRED string
  Key value pairs where the ID of the survey
- currentySurveyId REQUIRED string
  The ID of the survey associated with the workitem.
- data object
  Record<string, unknown>
- fromSurveyId string
  The ID of the survey associated with the workitem.

Returns

A promise of an object. Record<string, unknown>

DTMF handling

What is DTMF and Why Attach It to a Workitem?

DTMF (Dual-Tone Multi-Frequency) refers to the tones generated when you press keys on a telephone keypad. In the context of the WorkitemsService, you can send DTMF tones as an action associated with a specific workitem (such as an active call).

Why attach DTMF to a workitem?
Attaching DTMF to a workitem allows you to send keypad tones within the context of a specific call or interaction. For example, if you are using NCX to call your bank and need to navigate their automated phone menu (IVR), you can use the DTMF action with the workitem ID of your call. This ensures the tones are sent to the correct call session, enabling you to enter account numbers, PINs, or menu selections as required by the IVR.

✍️
Use case
You call your bank’s customer service using NCX. The bank’s IVR asks you to “Press 1 for account information.” By sending a DTMF action with the workitem ID of your call and the digit ‘1’, you can interact with the IVR and access the information you need.

dtmf(workitemId: string, digit: string)

Sends DTMF tones during a call. Takes the workitem ID and a dialpad number.

await workitemsService.dtmf('workitem-123', '5');

Parameters

workitemID string
The unique identifier of the workitem associated with the survey.
digit
Any value in the dialpad

Returns

A promise of a workitem. Promise<Workitem>

Best Practices

Always handle errors appropriately using try-catch blocks.
Use TypeScript interfaces for better type safety.
Implement proper cleanup when ending calls or conferences.
Monitor and log important events using the provided logging system.
Follow the event-driven architecture pattern when handling notifications.