ai-docs

Imported from webex/webex-js-sdk (packages/calling/src/Voicemail/ai-docs/AGENTS.md). Install upstream with npx skills add webex/webex-js-sdk --skill ai-docs. Copyright stays with the author.

Voicemail Module

Canonical SDD target: src/Voicemail/ai-docs/voicemail-spec.md. This legacy document is retained as migration source; use the canonical target for current lifecycle work.

AI Agent Routing Instructions

If you are an AI assistant or automated tool:

Do not use this file as your only entry point for reasoning or code generation.

• How to proceed:
  • For changes within the Voicemail/ directory, use this file as your primary reference.
  • For WXC-specific logic, refer to WxCallBackendConnector.ts.
  • For Broadworks-specific logic, refer to BroadworksBackendConnector.ts.
  • For UCM-specific logic, refer to UcmBackendConnector.ts.
  • For metric submission integration, refer to Metrics/types.ts and Metrics/index.ts.
• Important: Load this module-specific doc first, then drill into backend connector source files as needed.

Overview

The Voicemail module provides APIs for managing voicemail messages across multiple calling backends. It supports listing voicemails, retrieving voicemail content and transcripts, marking messages as read/unread, deleting messages, fetching voicemail summaries, and resolving caller contact information. The module uses a strategy pattern to delegate operations to backend-specific connectors (WXC, Broadworks, UCM) and automatically submits metrics for all operations.

Package: @webex/calling

Entry point: packages/calling/src/Voicemail/Voicemail.ts

Factory: createVoicemailClient(webex, logger) -> IVoicemail

Key Capabilities

Public API

IVoicemail Interface

Key Types

VoicemailResponseEvent

type VoicemailResponseEvent = {
  statusCode: number;
  data: {
    voicemailList?: MessageInfo[];
    voicemailContent?: { type: string | null; content: string | null };
    voicemailSummary?: SummaryInfo;
    voicemailTranscript?: string | null;
    error?: string;
  };
  message: string | null;
};

SummaryInfo

type SummaryInfo = {
  newMessages: number;
  oldMessages: number;
  newUrgentMessages: number;
  oldUrgentMessages: number;
};

MessageInfo (voicemail list item)

type ResponseString$ = { $: string };
type ResponseNumber$ = { $: number };

type MessageInfo = {
  duration: ResponseString$;
  callingPartyInfo: CallingPartyInfo;
  time: ResponseNumber$;
  messageId: ResponseString$;
  read: ResponseString$ | object;  // empty object {} means read=true (UCM convention)
};

Note: Fields use ResponseString$/ResponseNumber$ wrapper types with a $ property to match the XSI JSON format. Access values as message.messageId.$, message.time.$, etc.

CallingPartyInfo

type CallingPartyInfo = {
  name: ResponseString$;
  userId?: ResponseString$;
  address: ResponseString$;
  userExternalId?: ResponseString$;
};

Backend Feature Matrix

Configuration

Examples and Use Cases

Create and Initialize Voicemail Client

import {createVoicemailClient, SORT} from '@webex/calling';

const voicemail = createVoicemailClient(webex, {level: 'info'});
await voicemail.init();

Fetch Voicemail List

const response = await voicemail.getVoicemailList(0, 10, SORT.DESC, true);
if (response.statusCode === 200) {
  console.log('Voicemails:', response.data.voicemailList);
}

Get Voicemail Content

const content = await voicemail.getVoicemailContent(messageId);
console.log('Type:', content.data.voicemailContent?.type);
console.log('Content:', content.data.voicemailContent?.content);

Mark as Read and Delete

await voicemail.voicemailMarkAsRead(messageId);
await voicemail.deleteVoicemail(messageId);

Get Summary and Transcript

const summary = await voicemail.getVoicemailSummary();
console.log('New messages:', summary?.data.voicemailSummary?.newMessages);

const transcript = await voicemail.getVMTranscript(messageId);
console.log('Transcript:', transcript?.data.voicemailTranscript);

Implementation Notes

HTTP Client Usage

WXC and UCM use this.webex.request(). Broadworks voicemail operations (getVoicemailList, getVoicemailContent, mark read/unread, delete) use browser fetch with Authorization: Bearer {bwtoken} headers, while Broadworks bootstrap/auth discovery still uses this.webex.request().

WXC messageId Path Convention

In WXC/BWRKS, the messageId returned from getVoicemailList is a full XSI path (e.g., /v2.0/user/{userId}/VoiceMessagingMessages/{id}). Operations concatenate it directly to xsiEndpoint:

// Content:  {xsiEndpoint}{messageId}
// Mark read: {xsiEndpoint}{messageId}/MarkAsRead
// Delete:   {xsiEndpoint}{messageId} (DELETE method)
// Transcript: {xsiEndpoint}{messageId}/transcript

WXC Pagination (Client-Side Caching)

WXC fetches the entire voicemail list from XSI on refresh=true, sorts it, and stores it in sessionStorage (base64-encoded) keyed by a random context string. Subsequent calls paginate from this session-scoped cache using fetchVoicemailList(context, offset, limit). The list response returns status 204 whenever there are no additional pages (moreVMAvailable=false), including cases where the current page still contains messages.

UCM Pagination (Server-Side)

UCM passes offset, limit, and sortOrder as query parameters to the VG Gateway, which handles pagination server-side.

Metrics Integration

The facade submits metrics for every operation via MetricManager:

• Success (2xx): METRIC_EVENT.VOICEMAIL with METRIC_TYPE.BEHAVIORAL
• Failure (non-2xx): METRIC_EVENT.VOICEMAIL_ERROR with status code and error message

Metric actions: get_voicemails, get_voicemail_content, get_voicemail_summary, mark_read, mark_unread, delete, transcript

Dependencies

Runtime Dependencies

Internal Dependencies

Related Documentation

• Architecture — Component overview, data flows, sequence diagrams