Overview

The BaseUserService class provides methods for managing user-related operations in Nextiva's contact center and customer service applications. It covers authentication, session management, call controls, messaging, supervisor functions, and more.

Summary

A user is an agent, supervisor, or administrator who interacts with the contact center system. Users have unique identifiers, credentials, roles, and may be associated with devices, phone numbers, and permissions.

This service enables developers to authenticate users, manage sessions, retrieve user information, and perform user-related operations such as login, logout, and ACD (Automatic Call Distribution) actions.

For more details on user state transitions, see State Service Documentation.

Key terms

User
- An individual with access to the system, identified by a unique user ID and associated credentials.
Session
- An authenticated period during which a user interacts with the system.
ACD (Automatic Call Distribution)
- System that routes workitems (calls, messages, etc.) to users/agents.

Basic usage

At the basic level, the BaseUserService class can be used to log in a user, initialize a session, and check login status.

// Log in a user
const tokenResponse = await userService.login('username', 'password');

// Initialize a session
const session = await userService.initSession({ deviceToken: 'token', platform: 'web' });

// Check if user is logged in
const isLoggedIn = userService.isLoggedIn();

// Log in to ACD
await userService.loginToAcd({
  channels: { voice: { ... }, chat: { ... } },
  queues: ['queue-1', 'queue-2'],
  status: { status: 1, statusId: 'available' }
});

Main features

Authentication and session management

Login

Logs in the user with a username and password.

this.UserService.login(username: string, password: string)

Parameters

username (REQUIRED, string)\
The username of the user logging in.
password (REQUIRED, string)\
The password of the user logging in.

Returns

A token response. Promise\<TokenResponse>

export interface TokenResponse {
 location: string;
 token: string;
}

Session initialization

this.UserService.initSession({ deviceToken, platform }: {
  deviceToken?: string;
  platform: Platform;
})

Parameters

deviceToken (string)\
A token they get from the login.
platform (REQUIRED object)\
Possible Values: web | android | ios; The platform the session is being initialized on.

Returns

Promise\<Device | UserSession>

export interface UserSession {
  [key: string]: unknown;
  _id: string;
  acdAutoAccept: boolean;
  acdAutoLogin: boolean;
  acdLoginAt: number;
  activeChannels: unknown;
  allowAcdChanges: boolean;
  authorities: Authority[];
  azureUserIdentity?: {
    accessToken: string;
    azureUserId: string;
    tokenExpiration: number;
  };
  callFailedNotification: boolean;
  createdAt: number;
  createdBy: string;
  credentialsNonExpired: boolean;
  defaultAcdLoginStatus: string;
  deletedAt: number;
  deviceInfo: string;
  devices?: Record<string, MultiloginDevice>;
  dialConfirmation: boolean;
  directory: {
    queues: unknown[];
    topics: string[];
    users: string[];
  };
  disableDisposition: string;
  disableEmailNotification: boolean;
  disableStartRecording: boolean;
  disableStopRecording: boolean;
  disableVMNotication: boolean;
  dispositionId: string;
  dispositionNotification: boolean;
  enabled: boolean;
  firstName: string;
  hideInCompanyDirectory: boolean;
  hideInDirectory: boolean;
  idleStartedAt: number;
  inConference: boolean;
  inMute: boolean;
  inRecording: boolean;
  language: string;
  languageId: string;
  lastName: string;
  lastSearchRange: {
    type: string;
  };
  lastTimeOfOutboundCall: number;
  location: string;
  loginAt: number;
  modifiedAt: number;
  modifiedBy: string;
  name: string;
  oAuthProfileAssignmentFromExternalRole: boolean;
  objectType: string;
  outboundMode: OutboundMode;
  password: string;
  passwordModifiedAt: number;
  pseudonym: string;
  queues: string[];
  recordingAnalysisPercentage: number;
  regionId: string;
  reminderTime: number;
  ringOnLogout: boolean;
  ringPhoneOnOffer: boolean;
  ringbackURL: string;
  role?: string;
  scrubOnDial: boolean;
  settings: Settings;
  skills: unknown[];
  status: StatusType;
  statusId: string;
  statusStartedAt: number;
  telephony: TelephonyConfig;
  tenantId: string;
  tenantName: string;
  timezone: string;
  token: string;
  useReactWorkitemLayout: string;
  useSideBarHeader: string;
  userClientSettings: {
    _id: string;
    createdAt: number;
    createdBy: string;
    deletedAt: number;
    modifiedAt: number;
    modifiedBy: string;
    objectType: string;
    tenantId: string;
  };
  userClientSettingsId: string;
  userId: string;
  userProfile: {
    _id: string;
    authoritySetId: string;
    autoDispositionId: string;
    callCompleteNotification: boolean;
    callRingingNotification: boolean;
    createdAt: number;
    createdBy: string;
    deletedAt: number;
    disableDisposition: boolean;
    label: string;
    localizations: {
      description: LocalizationEntry;
      name: LocalizationEntry;
    };
    modifiedAt: number;
    modifiedBy: string;
    objectType: string;
    recordingAnalysisPercentage: number;
    tenantId: string;
    userprofileId: string;
  };
  userProfileId: string;
  username: string;
  verifyConsentOnDial: boolean;
  verifyConsentOnSMS: boolean;
  voiceState: PhoneState;
  voicemailFunctionId: string;
  voicemailGreetingFunctionId: string;
  workingOn: string;
}

Session status

Checks if a user is logged in.

this.userService.isLoggedIn()

ACD (Automatic Call Distribution) operations

Login to ACD

Logs the user into the ACD to start receiving workitems.

this.userService.loginToAcd(payload)

Parameters

payload: LoginToACDPayload

export interface LoginToACDPayload {
 channels?: Record<string, LoginToACDChannel>;
 queues?: string[];
 status?: {
   status: number;
   statusId: string;
 };
}

channels Record\<string, LoginToACDChannel>;

export interface LoginToACDChannel {
 enabled: boolean;
 limit: number;
 multitasking: boolean;
 priority: number;
}

enabled boolean\\
limit number
multitasking boolean
priority number
queues an array of strings\
The queues the user is a part of.
status object\
Holds the status of the user and the status ID.
status number The status of the user when they login to the ACD
statusID number\
The unique identifier of the status of the user when they login to the ACD

Returns

A promise of an object. Promise\<\{ loginAt: number }>

Auto-Login Configuration

Automatically logs a user in to the ACD.

this.userService.autoLoginToAcd()

Returns

A promise of an object. Promise<{ loginAt: number }>.If auto login to ACD is not enabled for the user, the return will be undefined.

Call control operations

Basic call controls

connectToServer

Connects a user to the server by having the server call the phone number configured in their settings.

this.userService.connectToServer() {
}

disconnectFromServer

Disconnects the user from the server. Any calls in process will also be terminated.

this.userService.disconnectFromServer() {
  }

mute

Mutes the user's phone.

this.userService.mute() {
}

unmute

Unmutes the user's phone.

this.userService.unMute() {
}

Conference controls

enterConference

Sends a request for the user to enter a conference call.

this.userService.enterConference() {
}

exitConference

Allows the user to exit a conference call.

this.userService.exitConference() {
}

Outbound Dialing

typescript
this.userService.dial({
  campaignId,
  conferenceWorkitemId,
  contactId,
  context,
  conversationId,
  force,
  name,
  option,
  spoofWorkitemId,
  ticketId,
  to,
  workitemId,
}: DialPayload): Promise<DialResponse>

Parameters

campaignId string\
The unique identifier of the campaign being used for outbound dialing.
conferenceWorkitemId string\
The unique identifier of the conference workitem.
contactId string\
The unique identifier of the contact.
context string\
Context you want to send to the workitem. Will be available in the workitem
conversationId string\
The unique identifier of the conversation.
force string\
When a user has some compliance flag and he tries to make a call somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to call anyway (force) or cancel.
name string\
The name of the person being called.
option string
spoofWorkitemId string
ticketId string
to string\
The phone number being called.
workitemId string\
The unique identifier of the worktitem.

Returns

Promise\<DialResponse>

Messaging

this.userService.email(payload: BaseSendEmailPayload)

Parameters

payload: BaseSendEmailPayload REQUIRED
campaignId: string
The unique identifier of the campaign the email is being sent from.
contactId: string
The id of the contact being sent an email.
file: TFile
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: BaseSendMessagePayload)

Parameters

payload: BaseSendMessagePayload REQUIRED
campaignId: string
The unique identifier of the campaign the email is being sent from.
contactId: string
The id of the contact being sent an email.
file: TFile
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 a message somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to send the message 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: BaseSendMessagePayload)

Parameters

payload: BaseSendMessagePayload REQUIRED
campaignId: string
The unique identifier of the campaign the email is being sent from.
contactId: string
The id of the contact being sent an email.
file: TFile
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 a message somewhere that is outside of the...that says you are calling outside of the allowed hours. They then can decide to send the message 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.

Supervisor functions

Call monitoring

listen

Listens to updates for a specified user.

this.userService.listen(userId: string)

Parameters

userId REQUIRED string\
The unique identifier of the user to be listened to.

join

Joins a user to another workitem.

this.userService.join(userId: string)

Parameters

userId REQUIRED string\
The unique identifier of the user to be joined to another workitem.

coach

Assigns a coach to a user.

this.userService.coach(userId: string)

Parameters

userId REQUIRED string\
The unique identifier of the user to be coached.

User management

changeStatus

Changes the status of a user logged in to the ACD.

this.userService,changeStatus(userId: string, statusId?: string)

Parameters

userId REQUIRED string\
The unique identifier of the user.
statusId string\
The unique identifier of the status of the user.

Returns

A promise of an object. Promise\<\{ loginAt: number }>

forceLogout

Forces an agent to logout.

async forceLogout(userId: string)

Parameters

userId REQUIRED string\
The unique identifier of the user.

Returns

void

forceLogoutAndDisable

Forces a user to logout and disables that user. The disabled user will not be able to login again.

this.userService.forceLogoutAndDisable(userId: string)

Parameters

userId REQUIRED string\
The unique identifier of the user.

Returns

void

terminateWorkitem

Terminates an active workitem of another user. (Mainly for supervisors)

this.userService.terminateWorkitem(workitemId: string)

Parameters

workitemId REQUIRED string\
The unique identifier of the workitem to be terminated.

Voice settings management

Update Voice Settings

updateUserCallForwardingVoiceSetting

Updates call forwarding settings for a specified user.

this.userService.updateUserCallForwardingVoiceSetting(userId: string, setting: CallForwardingSettings)

Parameters

userId REQUIRED string\
The unique identifier of the user updating their call forwarding voice settings.
always object\
An object that holds the default call forwarding voice settings, including the destination number and whether the settings should be enabled. If the user’s status is Busy the destination number and enabled can be changed. If the status is Unreachable, Unanswered or Busy, it will always have these values.
`destinationNumber string\
The number the call forwarding is going to.
enabled boolean\
If enabled, the settings are on.

Returns

User Voice Settings Promise\<UserVoiceSettings>

export interface UserVoiceSettings {
 _id: string;
 callForwardingSettings: CallForwardingSettings;
 callWaitingSettings: CallWaitingSettings;
 createdAt: number;
 createdBy: string;
 deletedAt: number;
 modifiedAt: number;
 modifiedBy: string;
 objectType: string;
 referenceType: string;
 tenantId: string;
 voicemailSettings: VoicemailSettings;
}

_id string\
The identifier of the settings.
createdAt: number\
The time the settings were created at.
createdBy: string;\
The user that created the settings.
deletedAt: number;\
The time the settings were deleted at.
modifiedAt: number;\
The time the settings were last modified.
modifiedBy: string;\
The user that last modified the settings.
objectType: string;
referenceType: string;
tenantId: string;\
The unique identifier of the tenant the user belongs to.

updateUserCallWaitingVoiceSetting

Updates call waiting settings for a specified user.

this.userService.updateUserCallWaitingVoiceSetting(userId: string, setting: CallWaitingSettings)

Parameters

userId REQUIRED string\
The unique identifier of the user.
setting: CallWaitingSettings export interface CallWaitingSettings \{ enabled?: boolean; }
enabled boolean\
If enabled, the settings are on. Pass true or false depending on whether you want the settings enabled or not

Returns

User Voice Settings Promise\<UserVoiceSettings>

export interface UserVoiceSettings {
 _id: string;
 callForwardingSettings: CallForwardingSettings;
 callWaitingSettings: CallWaitingSettings;
 createdAt: number;
 createdBy: string;
 deletedAt: number;
 modifiedAt: number;
 modifiedBy: string;
 objectType: string;
 referenceType: string;
 tenantId: string;
 voicemailSettings: VoicemailSettings;
}

_id string\
The identifier of the settings.
createdAt: number\
The time the settings were created at.
createdBy: string;\
The user that created the settings.
deletedAt: number;\
The time the settings were deleted at.
modifiedAt: number;\
The time the settings were last modified.
modifiedBy: string;\
The user that last modified the settings.
objectType: string;
referenceType: string;
tenantId: string;\
The unique identifier of the tenant the user belongs to.
voicemailSettings: object;\
enabled boolean If the Voicemail Settings are enabled or disabled. Pass true or false.

updateUserVoicemailVoiceSetting

Updates voicemail settings for a specified user.

this.userService.updateUserVoicemailVoiceSetting(userId: string, setting: VoicemailSettings)

Parameters

userId REQUIRED string
setting: VoicemailSettings export interface VoicemailSettings \{ enabled: boolean; }
enabled boolean
If enabled, the settings are on. Pass true or false depending on whether you want the settings enabled or not

Returns

User Voice Settings Promise\<UserVoiceSettings>

export interface UserVoiceSettings {
 _id: string;
 callForwardingSettings: CallForwardingSettings;
 callWaitingSettings: CallWaitingSettings;
 createdAt: number;
 createdBy: string;
 deletedAt: number;
 modifiedAt: number;
 modifiedBy: string;
 objectType: string;
 referenceType: string;
 tenantId: string;
 voicemailSettings: VoicemailSettings;
}

_id string\
The identifier of the settings.
createdAt: number\
The time the settings were created at.
createdBy: string;\
The user that created the settings.
deletedAt: number;\
The time the settings were deleted at.
modifiedAt: number;\
The time the settings were last modified.
modifiedBy: string;\
The user that last modified the settings.
objectType: string;
referenceType: string;
tenantId: string;\
The unique identifier of the tenant the user belongs to.
voicemailSettings: object;\
enabled boolean If the Voicemail Settings are enabled or disabled. Pass true or false.

Voicemail Management

this.userService.convertTextToSpeech({
  languageCode,
  text,
  userId,
  voiceGender,
  voiceName,
}: TextToSpeechPayload): Promise<VoiceMailGreeting>

Parameters

languageCode string\
The code of the language the voicemail greeting is in.
text string\
The text of the voicemail greeting.
userId string\
The unique identifier of the user using the voicemail greeting.
voiceGender string\
The gender of the voice of the voicemail greeting. Male or Female
voiceName string\
The name of the voice of the voicemail greeting.

Returns

Promise\<VoiceMailGreeting>

export interface VoiceMailGreeting {
 contentType: string;
 signedURL: string;
}

contentType string

signedURL string\
The URL for the recording of the voicemail greeting.

History and data access

History Retrieval

gethistory

Gets workitem history for a user from a specified date range.

this.userService.getHistory(rangeType: RangeType)

Parameters

rangeType
The rangeType must be one of these values: export const RangeTypes = { DataRange: 'daterange', Not supported

Last30Days: 'last30days',\
The last 30 days.

Last3Days: 'last3days',\
The last 3 days.

Last7Days: 'last7days',\
The last 7 days from the call.

LastMonth: 'lastmonth',\
The last month.

LastWeek: 'lastweek',\
The last week.

ThisMonth: 'thismonth',\
This month.

ThisWeek: 'thisweek',\
Monday to Sunday of the current week. Today: 'today', Today.

Yesterday: 'yesterday',\
Yesterday.

} as const;

Returns

A promise of an array of workitems. \<Promise\<Workitem[]>

getHistoryByContactId

this.userService.getHistoryByContactId({
  contactId,
  dateRange,
  mergeProperties,
  q,
  rangeType,
  rows,
  start,
})

Parameters

contactId\
The unique identifier of the contact,

dateRange,\
The date range for the history. To date The date the range begins.

From date\
The date the range ends.

mergeProperties
export const DefaultMergeProperties = { Default: [ 'workitemId', The unique identifier of the workitem. 'type', Default 'createdAt', The time the workitem was created at. 'ownedBy', The user who handled the workitem. 'to', The destination number of the workitem. 'from', The origination number of the workitem.

'type'\
The properties of the workitem to be merged from the properties of the workitem. ], InboundCall: [ 'workitemId', The unique identifier of the workitem. 'type', Inbound Call 'createdAt', The time the workitem was created at. 'ownedBy', The user who handled the workitem. 'to', The destination number of the workitem. 'from', The number making the call.

'type',

'voicemailFile',\
A file containing the voicemail ], OutboundSMS: [ 'workitemId', The unique identifier of the workitem. 'type', Default 'createdAt', The time the workitem was created at. 'ownedBy', The user who handled the workitem. 'to', The destination number of the workitem. 'from', The origination number of the workitem.

'type'],\
InboundSMS: [ 'workitemId', The unique identifier of the workitem. 'type', Default 'createdAt', The time the workitem was created at. 'ownedBy', The user who handled the workitem. 'to', The destination number of the workitem. 'from', The origination number of the workitem.

'type'],\
};

q\
The query

rangeType
The rangeType must be one of these values: export const RangeTypes = { DataRange: 'daterange',

Last30Days: 'last30days',\
The last 30 days.

Last3Days: 'last3days',\
The last 3 days.

Last7Days: 'last7days',\
The last 7 days from the call.

LastMonth: 'lastmonth',\
The last month.

LastWeek: 'lastweek',\
The last week.

ThisMonth: 'thismonth',\
This month.

ThisWeek: 'thisweek',\
Monday to Sunday of the current week. Today: 'today', Today.

Yesterday: 'yesterday',\
Yesterday.

} as const;

rows number\
If doing pagination, the amount of items at a time want from the search

start number\
If doing pagination, this is where you want to start on the array when searching.

Returns

A promise of a history. Promise\<History>

export interface History {
 count: number;
 objects: Workitem[];
}

count: number

objects: Workitem[]

User Data

fetchUsers

this.userServicefetchUsers(payload?: SchemaTypeSearchPayload):

Parameters

payload SchemaTypeSearchPayload
export interface SchemaTypeSearchPayload {
 q?: string;
 queryParams?: Record<string, unknown>;
 rows?: number;
 start?: number;
}

q string\
The query

queryParams Record<string, unknown>

rows number\
If doing pagination, the amount of items at a time want from the search

start number\
If doing pagination, this is where you want to start on the array when searching.

Returns

count number

next string

objects User

previous string

total number

fetchUser

this.userService.fetchUser(id: string):

Parameters

id string\
The unique identifier of the user.

Returns

Promise<UserDetails>
export interface UserDetails { [key: string]: unknown; _id: string; acdAutoAccept: boolean; acdAutoLogin: boolean; allowAcdChanges: boolean; allowClientTracing: boolean; allowServerTracing: boolean; alwaysDurationWebNotification: boolean; alwaysHoldWebNotification: boolean; avatar?: string; callFailedNotification: boolean; chatDurationNotification: boolean; confirmDisposition: string; createdAt: number; createdBy: string; credentialsNonExpired: boolean; defaultAcdLoginStatus: string; deletedAt: number; deletedBy?: string; dialConfirmation: boolean; dialpadMode: string; directory: { queues: unknown[]; topics: string[]; users: string[]; }; disableDisposition: 'on' | 'off' | 'userProfile' | boolean | null | undefined; disableEmailNotification: boolean; disableStartRecording: boolean; disableStopRecording: boolean; dispositionNotification: boolean; edgeId?: string; enableDurationWebNotification: boolean; enableHoldWebNotification: boolean; enableRealtimeTranscription: string; enabled: boolean; expansions?: { languageId?: UserLanguageSettings; networkregionId?: UserNetworkRegionSettings; personalInboxCampaignId?: UserPersonalInboxCampaignSettings; voiceSettingsId?: UserVoiceSettings; }; files: Record< string, { contentType: string; fileType?: string; label: string; name: string; }> ;

firstName: string;
hideInCompanyDirectory: boolean; hideInDirectory: boolean; hometabs: HomeTabs; inboundCallDurationNotification: boolean; inboundCallHoldNotification: boolean; inboundEmailDurationNotification: boolean; inboundExtensionCallDurationNotification: boolean; inboundSMSDurationNotification: boolean; languageId: string; lastName: string; mSTeamsEnabled?: boolean; modifiedAt: number; modifiedBy: string; name: string; oAuthProfileAssignmentFromExternalRole: boolean; outboundCallDurationNotification: boolean; outboundCallHoldNotification: boolean; outboundEmailDurationNotification: boolean; outboundExtensionCallDurationNotification: boolean; outboundSMSDurationNotification: boolean; passwordModifiedAt: number; personalInboxCampaignId?: string; predictiveCallDurationNotification: boolean; predictiveSMSDurationNotification: boolean; progressiveCallDurationNotification: boolean; pseudonym: string; queues: Queues; recordingAnalysisPercentage: number; ringOnLogout: boolean; ringPhoneOnOffer: boolean; scrubOnDial: boolean; sendToVoicemailOnBusy?: boolean; settings: Settings; showWebrtcNotification: boolean; socialDurationNotification: boolean; status?: number; statusId?: string; telephony: TelephonyConfig; tenantId: string; timezone: string; useReactWorkitemLayout: string; useSideBarHeader: string; userClientSettingsId: string; userId: string; userProfileId: string; username: string; verifyConsentOnDial: boolean; verifyConsentOnSMS: boolean; }

Usage examples

Basic authentication flow

// Login
await userService.login(username, password);

// Initialize session
await userService.initSession({
  platform: {
    // platform details
  }
});

// Login to ACD
await userService.loginToAcd({
  // ACD login details
});

Call management

// Start a call
await userService.dial({
  to: phoneNumber,
  campaignId: 'campaign-123',
  name: 'John Doe'
});

// Handle conference
await userService.enterConference();
// ... call operations
await userService.exitConference();

Supervisor operations

// Monitor an agent
await userService.listen(agentId);

// Force logout an agent
await userService.forceLogout(agentId);

// Change agent status
await userService.changeStatus(agentId, newStatusId);