Users

Summary

The User Schema Type defines the structure and behavior of individual users or service identities within the Nextiva SDK. Users represent agents, administrators, or automated accounts that interact with the system, providing a consistent model for authentication, authorization, and ownership across various SDK resources.

This document outlines the complex structure of the User schema and the primary methods for interacting with user profiles and settings, highlighting the hybrid approach of a dedicated User Service and the generic SchemaTypeClient.

What is a user?

A User represents a person or a service identity that can authenticate and perform actions within the SDK or API. A User object encapsulates profile information, role memberships, and contextual data necessary for system interaction.

Typical use cases for the User schema include:

• Managing agent and administrative profiles.
• Assigning Workitems, calls, or campaigns to specific users.
• Enforcing granular permissions and access controls across the platform.
• Representing system-level identities for bots or integrations.
• Updating user-specific settings like telephony configurations, personal inbox numbers, and notification preferences.

Structure of a user

The User schema is rich and comprehensive, often encompassing not just basic profile data but also intricate settings, permissions, and session-related information. The primary interfaces are User (for core profile data) and UserDetails (a more extensive view, typically for the logged-in user or detailed profiles).

Field summary (core user interface)

This table focuses on key fields from the User interface, which represents the core profile of a user. Many other fields exist in UserDetails and related interfaces.

Key related types

The User schema frequently interacts with or embeds other complex types:

• UserDetails: An extended interface containing more comprehensive user data, including sessions, devices, queues, and detailed settings. Often returned for the currently authenticated user or when fetching detailed profiles.
• Authority: Defines roles and permissions associated with a user.
• Settings: Various configuration settings for ACD, devices, dialing, and workitem notifications.
• TelephonyConfig: Detailed telephony setup for the user (e.g., SIP, PSTN, WebRTC configurations).
• UserSession: Represents an active user session, containing runtime data.
• UserProfileSettings: Defines user-specific profile settings.
• StatusType: (from constants.ts) An enum defining possible user statuses (e.g., Available, Busy, DoNotDisturb, OnCall, Logout).

Example object (UserDetails)

import { UserDetails, StatusType } from '@ncx/ncx-core-sdk';

const exampleUserDetails: UserDetails = {
  _id: "60c72b2f9b1e8e0007c8e8e2",
  userId: "user_12345",
  username: "avery.morgan",
  name: "Avery Morgan",
  firstName: "Avery",
  lastName: "Morgan",
  tenantId: "t_abcde",
  createdAt: 1672531200000, // Jan 1, 2023
  createdBy: "system_admin",
  modifiedAt: 1678886400000, // March 15, 2023
  modifiedBy: "user_manager",
  email: "[email protected]",
  status: StatusType.Available,
  enabled: true,
  telephony: {
    address: "sip:[email protected]",
    type: "SIP",
    useSipEndpoint: true,
    workOffHook: false,
  },
  timezone: "America/Phoenix",
  acdAutoAccept: true,
  acdAutoLogin: true,
  // ... many other fields from UserDetails interface
  expansions: {
    userProfileId: {
      userprofileId: "profile_1",
      label: "Agent Profile",
      // ... other UserProfileSettings fields
    }
  },
  settings: {
    general: {
      defaultCampaignId: "camp_123",
    },
    workitem: {
      alwaysVoiceWebNotification: true,
      enableVoiceWebNotification: true
    }
  },
  directory: {
    queues: [], // Populated in UserSession
    topics: [],
    users: []
  },
  hometabs: {
    count: 0,
    objects: [],
    total: 0
  },
};

Interacting with users

User interactions typically involve a hybrid approach: the BaseUserService (accessed via sdk.getUsersService()) handles most specific user actions, while the generic SchemaTypeClient handles general profile data retrieval and updates.

📘

Note: Direct user creation is usually handled by administrative APIs and not typically exposed as a direct SDK client method.

Access user services

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

const sdk = new Nextiva({ /* ...configuration */ });
const userService = sdk.getUsersService(); // Dedicated service for many user actions
const schemaTypeClient = sdk.getSchemaTypeClient(); // Generic client for schema-level CRUD

Retrieve user profiles (read operations)

Fetch a single user by ID

import { UserDetails } from '@ncx/ncx-core-sdk';

const userIdToRetrieve = "user_12345";
const userProfile: UserDetails = await userService.fetchUser(userIdToRetrieve);

console.log("Retrieved User Profile:", userProfile.name, userProfile.status);

Search for users (by status, name, etc.)

import { FetchUsersResponseBody } from '@ncx/ncx-core-sdk';

const searchResults: FetchUsersResponseBody = await userService.fetchUsers({
  q: "status:Available", // Search query for available users
  rows: 25,
  start: 0,
});

console.log(`Found ${searchResults.total} available users.`);

Update user data (profile info)

For general updates to user profile fields (e.g., name, email, timezone), the SchemaTypeClient can be used.
import { User } from '@ncx/ncx-core-sdk';

const userIdToUpdate = "user_12345";
const updatedUser: User = await schemaTypeClient.update("user", {
  id: userIdToUpdate,
  data: {
    firstName: "Avery",
    name: "Avery Jane Morgan",
    modifiedAt: Date.now(),
    modifiedBy: "user_self",
  }
});

console.log("Updated User Profile:", updatedUser.name);

User-specific actions via BaseUserService

The BaseUserService provides numerous methods for specific user actions that often go beyond simple CRUD:

Change user status

import { StatusType } from '@ncx/ncx-core-sdk';

const userId = "user_12345";
await userService.changeStatus(userId, StatusType.Busy);
console.log(`User ${userId} status set to Busy.`);

Supervisor actions (listen, join, coach)

// To listen to an agent's call
await userService.listen("agent_userId", "workitem_id_of_call");

// To join an agent's call (escalation)
await userService.join("agent_userId", "workitem_id_of_call");

Force logout a user

await userService.forceLogout("user_tologout_id");
console.log("User force logged out.");

User creation and deletion

• Creation: Direct user creation is typically handled through administrative APIs or external user management systems, not directly via BaseUserService in the SDK for end-user operations.
• Deletion/Deactivation: Users are often soft-deleted or deactivated. BaseUserService provides methods like forceLogoutAndDisable or terminate (for a user’s session/workitem), but full user record deletion is usually an administrative function.

Relationships

Users are fundamental to many SDK relationships:

• Workitems: Users are assigned to Workitems (as agents or owners).
• Queues: Users are members of Queues.
• User Sessions: A User can have multiple UserSessions across devices.
• User Profiles: Users are linked to UserProfileSettings.
• Permissions: Authority objects define permissions granted to users.

Permissions

User-related permissions control who can view, modify, and manage user accounts and their associated settings.

Validation rules

• username and tenantId are required.
• username must be unique within a tenant.
• status must be a valid StatusType enum value.
• email (if provided) should be a valid email format.
• firstName and lastName are required for most profile operations.