Disposition

Summary

The Disposition Schema Type defines standardized result codes or categories that describe the outcome of a call, message, case, or other customer interaction within the Nextiva SDK. Dispositions provide a consistent way to categorize how an interaction ended, facilitating reporting, automation, and workflow management. This document outlines the structure of the Disposition schema, its fields, and how to interact with disposition definitions and apply dispositions to workitems.

What is a Disposition?

A Disposition is a classification applied to an interaction (like a Workitem) to record its final state or outcome. Examples include “Resolved,” “Voicemail,” or “Follow-up Required.” They are crucial for:

Categorizing Outcomes: Providing a clear, standardized label for how an interaction was handled.
Reporting: Enabling analytics on interaction outcomes and agent performance.
Automation: Triggering follow-up actions based on the disposition (e.g., sending a survey after a “Resolved” disposition).

Structure of a Disposition

A Disposition object defines the properties of a specific disposition entry within the system’s catalog.

Field summary

Field	Type	Description
_id	string	Internal unique identifier (MongoDB ID).
dispositionId	string	Public unique identifier for the disposition (e.g., `disp_resolved`).
name	string	The default, non-localized human-readable name of the disposition.
localizations	object	Localized names for the disposition across languages (e.g., `{ name: { EN: "Resolved", ES: "Resuelto" } }`).
action	DispositionActionOption	An optional action associated with the disposition, such as `connectedCallback`.
blockNumber	boolean	Indicates if applying this disposition should block the associated phone number.
callbackDate	number	Unix timestamp (ms) for a scheduled callback date.
callbackTime	number	Unix timestamp (ms) for a scheduled callback time.
connectAgain	boolean	Indicates if the system should attempt to connect again after this disposition.
createdAt	number	Unix timestamp (ms) when the disposition was created.
createdBy	string	Identifier of the user who created the disposition.
deletedAt	number	Unix timestamp (ms) when the disposition was deleted.
forceContactAssignment	boolean	Forces assignment of a contact to the workitem.
forceSurveyValidation	boolean	Forces survey validation on disposition.
mediaType	string	The media type (e.g., `voice`, `chat`) this disposition applies to.
modifiedAt	number	Unix timestamp (ms) when the disposition was last modified.
modifiedBy	string	Identifier of the user who last modified the disposition.
note	string	An internal note or description for the disposition.
phoneNumber	string	A phone number associated with the disposition, typically for callbacks.
queues	string[]	A list of queue IDs this disposition is associated with.
resolveTicket	boolean	Indicates if applying this disposition should resolve an associated ticket.
resolved	boolean	Indicates if this disposition marks an interaction as resolved.
skills	string[]	A list of skill IDs associated with the disposition.
summary	unknown	Summary information for the disposition.
survey	unknown	Survey information for the disposition.
useCampaignIdForDNC	boolean	Uses campaign ID for Do Not Call (DNC) list handling.
workitemType	WorkitemType[]	Workitem types (e.g., `InboundCall`, `OutboundEmail`) this disposition applies to.

Example object

import { Disposition, WorkitemTypes, DispositionActions } from '@ncx/ncx-core-sdk';
import { LanguageCode } from '@ncx/ncx-core-sdk/types/language'; // Assuming LanguageCode is imported

const exampleDisposition: Disposition = {
  _id: "60c72b2f9b1e8e0007c8e8e1",
  dispositionId: "disp_callback",
  name: "Callback Scheduled",
  localizations: {
    name: {
      [LanguageCode.EN]: "Callback Scheduled",
      [LanguageCode.ES]: "Llamada de Vuelta Programada"
    }
  },
  action: DispositionActions.ConnectedCallback,
  blockNumber: false,
  callbackDate: Date.now() + 86400000, // Tomorrow
  connectAgain: true,
  createdAt: 1678886400000,
  createdBy: "user_admin",
  deletedAt: 0,
  forceContactAssignment: false,
  forceSurveyValidation: false,
  mediaType: "voice",
  modifiedAt: 1678886400000,
  modifiedBy: "user_admin",
  note: "Customer requested a callback tomorrow morning.",
  phoneNumber: "+14805551234",
  queues: ["q_sales"],
  resolveTicket: false,
  resolved: false,
  skills: ["sales", "english"],
  workitemType: [WorkitemTypes.InboundCall, WorkitemTypes.OutboundCall],
  // ... other optional fields
};

Interacting with Dispositions

Interactions with Dispositions are twofold: managing the disposition definitions themselves and applying dispositions to workitems.

Manage Disposition definitions

Disposition definitions are managed using the generic SchemaTypeClient.

Create a new Disposition definition

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Disposition, WorkitemTypes } from '@ncx/ncx-core-sdk';
import { LanguageCode } from '@ncx/ncx-core-sdk/types/language';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const newDispositionData = {
  name: "Resolved Issue",
  localizations: {
    name: {
      [LanguageCode.EN]: "Resolved Issue",
      [LanguageCode.ES]: "Problema Resuelto"
    }
  },
  workitemType: [WorkitemTypes.InboundCall, WorkitemTypes.OutboundEmail],
  resolveTicket: true,
  resolved: true,
  tenantId: "t_abcde",
  createdAt: Date.now(),
  createdBy: "user_admin",
  objectType: "disposition"
};

const newDisposition: Disposition = await schemaTypeClient.create("disposition", {
  data: newDispositionData
});

console.log("Created Disposition Definition:", newDisposition);

Retrieve Disposition definitions

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

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const dispositionIdToRetrieve = "disp_resolved";
const retrievedDisposition: Disposition = await schemaTypeClient.retrieve("disposition", {
  id: dispositionIdToRetrieve,
});

console.log("Retrieved Disposition Definition:", retrievedDisposition);

Update a Disposition definition

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Disposition } from '@ncx/ncx-core-sdk';
import { LanguageCode } from '@ncx/ncx-core-sdk/types/language';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const dispositionIdToUpdate = "disp_resolved";
const updatedDispositionData = {
  localizations: {
    name: {
      [LanguageCode.EN]: "Issue Completely Resolved"
    }
  },
  modifiedAt: Date.now(),
  modifiedBy: "user_admin"
};

const updatedDisposition: Disposition = await schemaTypeClient.update("disposition", {
  id: dispositionIdToUpdate,
  data: updatedDispositionData
});

console.log("Updated Disposition Definition:", updatedDisposition);

Search a Disposition definition

import { Nextiva } from '@nextiva/ncx-web-sdk';
import { Disposition, FetchDispositionsResponse } from '@ncx/ncx-core-sdk';

const sdk = new Nextiva({ /* ...configuration */ });
const schemaTypeClient = sdk.getSchemaTypeClient();

const searchResults: FetchDispositionsResponse = await schemaTypeClient.search("disposition", {
  q: "name:Resolved*",
  rows: 10,
  start: 0,
});

console.log("Found Dispositions:", searchResults.list);

Fetch available Dispositions

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

const sdk = new Nextiva({ /* ...configuration */ });
const dispositionService = sdk.getDispositionService(); // Assuming this service exists

const availableDispositions: FetchDispositionsResponse = await dispositionService.fetchDispositions();

console.log("Available Dispositions:", availableDispositions.list);

Apply a Disposition to a Workitem

To apply a specific disposition to an active workitem, you use the disposition method of the DispositionService.
import { Nextiva } from '@nextiva/ncx-web-sdk';
import { DispositionOptions } from '@ncx/ncx-core-sdk';

const sdk = new Nextiva({ /* ...configuration */ });
const dispositionService = sdk.getDispositionService(); // Assuming this service exists

const workitemIdToDisposition = "wi_12345";
const dispositionOptions: DispositionOptions = {
  workitemId: workitemIdToDisposition,
  dispositionId: "disp_resolved",
  summary: "Issue successfully resolved during the call.",
  // other optional fields like callbackDate, phoneNumber etc.
};

await dispositionService.disposition(dispositionOptions);

console.log(`Disposition 'resolved' applied to workitem ${workitemIdToDisposition}.`);

Permissions

Access to manage disposition definitions and apply dispositions is controlled by the standard permissions model.

Scope	Description
dispositions:read	Allows viewing disposition definitions.
dispositions:write	Allows creating or modifying disposition definitions.
dispositions:delete	Allows deleting disposition definitions.
workitems:disposition	Allows applying a disposition to a workitem (workitem-specific permission).

Validation rules

name is required.
dispositionId must be unique across the tenant.
localizations.name should contain localized strings for relevant languages.
workitemType must reference valid WorkitemType enums.
Timestamps (createdAt, modifiedAt, callbackDate, callbackTime) must be valid Unix timestamps in milliseconds.

Relationships

Workitems: Dispositions are applied to Workitems to categorize their outcome.
Localization: Dispositions use LocalizationEntry for multilingual support.
Workitem Types: Dispositions can be scoped to specific WorkitemTypes.