PhoneOS xAPI Release Notes

The PhoneOS xAPI provides programmatic access to Cisco IP Phone devices, enabling developers to monitor, configure, and control phone operations through a standardized API interface.

PhoneOS 3.6 Release

Release Date: November 2025

Overview

PhoneOS 3.6 enhances xAPI capabilities by introducing expanded network statistics, LED status monitoring, detailed per-call metrics, and device operational status. This update offers deeper insights into phone performance and call quality metrics.

New Features

1. Network Statistics and Monitoring

Support: MPP and On-Prem

Enhanced network monitoring capabilities for both Ethernet and port-level statistics.

xStatus Additions:

Network Statistics Ethernet - Ethernet interface statistics
Network Statistics Port [1-2] - Individual port statistics for monitoring network performance

2. ThousandEyes Integration Status

Support: MPP and On-Prem

Monitor the status and version of ThousandEyes agent running on the device.

xStatus Additions:

ThousandEyes Status - Current status of ThousandEyes agent
ThousandEyes Version - ThousandEyes agent version information

3. LED Status Monitoring

Support: MPP and On-Prem

Comprehensive LED status information for all device indicators including headset, speaker, mute, MWI, and line indicators.

xStatus Additions:

LEDStatus HeadsetLEDCadence - Headset LED blink pattern
LEDStatus HeadsetLEDColor - Headset LED color
LEDStatus Line [n] LEDCadence - Per-line LED blink pattern
LEDStatus Line [n] LEDColor - Per-line LED color
LEDStatus MuteLEDCadence - Mute button LED blink pattern
LEDStatus MuteLEDColor - Mute button LED color
LEDStatus MwiLEDCadence - Message Waiting Indicator LED blink pattern
LEDStatus MwiLEDColor - Message Waiting Indicator LED color
LEDStatus SpeakerLEDCadence - Speaker LED blink pattern
LEDStatus SpeakerLEDColor - Speaker LED color

4. Phone Operational Status

Support: MPP and On-Prem

More detailed statistics for phone status, including timing, VLAN, and port configuration.

xStatus Additions:

PhoneStatus CurrentTime - Current time on the device
PhoneStatus ElapsedTime - Time elapsed since last boot
PhoneStatus OperationalVLANID - Active VLAN identifier
PhoneStatus PCPort - PC port status
PhoneStatus PCPortConfig - PC port configuration
PhoneStatus SWPort - Switch port status
PhoneStatus SWPortConfig - Switch port configuration

5. Bookings Status

Support: MPP and On-Prem

Real-time booking and availability status for workspace management.

xStatus Additions:

Bookings Availability Status - Current device availability status
Bookings Availability TimeStamp - Timestamp of the latest availability update
Bookings Current Id - Current booking identifier
Bookings Current MeetingId - Current meeting identifier

6. Download and Provisioning Status

Support: MPP Only (Subscription not yet supported)

The status of firmware upgrades, provisioning, certificates, and file downloads.

xStatus Additions:

DownloadStatus CustomCAStatus Info - Custom CA certificate information
DownloadStatus CustomCAStatus ProvisioningStatus - Custom CA provisioning status
DownloadStatus FirmwareUpgradeStatus [1-3] Status - Firmware upgrade status for up to 3 slots
DownloadStatus ProvisioningStatus [1-3] Status - Provisioning status for up to 3 slots
DownloadStatus ScreenStatus CustomWallpaperDownload [1-20] - Custom wallpaper download status (supports up to 20 wallpapers)
DownloadStatus ScreenStatus LogoDownloadStatus - Logo download status
DownloadedLocalePackage LocaleDownloadStatus - Locale package download status
DownloadedLocalePackage LocaleDownloadURL - Locale package download URL

7. Device Management Status

Support: MPP Only

The status of problem reports, SIP statistics, security logging, and SCEP.

xStatus Additions:

PRTStatus PRTGenerationStatus - Problem Report generation status
PRTStatus PRTUploadStatus - Problem Report upload status
PhoneStatus ExternalIP - External IP address
PhoneStatus SIPBytesRecv - SIP bytes received counter
PhoneStatus SIPBytesSent - SIP bytes sent counter
PhoneStatus SIPMessageRecv - SIP messages received counter
PhoneStatus SIPMessageSent - SIP messages sent counter
Security LastFailedAdminLogin - Timestamp of the latest failed admin login attempt
Security LastSuccessfulAdminLogin - Timestamp of the latest successful admin login
Security SCEPStatus [1-3] DownloadStatus - SCEP certificate download status

8. Per-Call Statistics and Metrics

Support: MPP Only

Comprehensive per-call quality metrics and statistics for active calls on each line.

xStatus Additions:

Line [n] Call [n] BytesReceived - Bytes received during call
Line [n] Call [n] BytesSent - Bytes sent during call
Line [n] Call [n] CallAppearance - Call appearance identifier
Line [n] Call [n] CallState - Current call state
Line [n] Call [n] Callback - Callback number
Line [n] Call [n] DecodeLatency - Audio decode latency
Line [n] Call [n] Decoder - Audio codec used for decoding
Line [n] Call [n] Encoder - Audio codec used for encoding
Line [n] Call [n] DiscardRate - Packet discard rate
Line [n] Call [n] Duration - Call duration
Line [n] Call [n] BurstDuration - Burst duration for packet loss
Line [n] Call [n] GapDuration - Gap duration between packet losses
Line [n] Call [n] Jitter - Jitter measurement
Line [n] Call [n] LossRate - Packet loss rate
Line [n] Call [n] MOSCQ - Mean Opinion Score - Conversational Quality
Line [n] Call [n] MOSLQ - Mean Opinion Score - Listening Quality
Line [n] Call [n] MappedRtpPort - Mapped RTP port number
Line [n] Call [n] PacketsDiscarded - Number of packets discarded
Line [n] Call [n] PacketsLost - Number of packets lost
Line [n] Call [n] PacketsReceived - Number of packets received
Line [n] Call [n] PacketsSent - Number of packets sent
Line [n] Call [n] PeerName - Remote party name
Line [n] Call [n] PeerPhone - Remote party phone number
Line [n] Call [n] RemoteHold - Remote hold status
Line [n] Call [n] Rfactor - R-factor call quality metric
Line [n] Call [n] RoundTripDelay - Round-trip delay measurement
Line [n] Call [n] Type - Call type (audio/video)
Line [n] Call [n] Tone - Active tone information

PhoneOS 3.5 Release (Initial xAPI Support)

Release Date: Aug 2025

Overview

PhoneOS 3.5 introduces the initial xAPI support for Cisco IP Phones running PhoneOS, enabling powerful programmability and integration capabilities on devices. This release lays the foundation for remote monitoring, configuration, and control through a standardized API interface.

New Features

1. xAPI Admin Account Management

Support: MPP and On-Prem

Configure and manage xAPI access credentials for secure API authentication.

Configuration:

Configuration via MPP Profile or On-prem QED
Web page display of xAPI account status on both MPP and On-prem deployments

2. System and Device Status (xStatus)

Support: MPP and On-Prem

Monitor essential device information including system identity, software version, and hardware details.

xStatus Additions:

Conference SelectedCallProtocol - Currently selected call protocol
ExtStatus[n] MessageWaiting - Message waiting indicator status
ExtStatus[n] RegistrationState - Line registration state
HttpFeedback[n] URL - HTTP feedback destination URL
HttpFeedback[n] Status - HTTP feedback slot status
HttpFeedback[n] Format - HTTP feedback data format
HttpFeedback[n] Expression[n] - HTTP feedback expression filters
Network Ethernet MacAddress - Ethernet MAC address
Network IPv4 Address - IPv4 address
Network Wifi MacAddress - Wi-Fi MAC address
Standby Level - Current standby state
SystemUnit HostName - Device hostname
SystemUnit ProductId - Product model identifier
SystemUnit ProductType - Product type designation
SystemUnit Hardware Module - Hardware module information
SystemUnit Hardware Module MACAddress - Hardware module MAC address
SystemUnit Hardware Module VID - Version identifier
SystemUnit Hardware Module Version - Hardware version
SystemUnit Software - Software information container
SystemUnit Software Version - Active software version

3. Device Commands (xCommand)

Support: MPP and On-Prem

Execute commands to control device operations, manage certificates, and configure HTTP feedback.

xCommand Additions:

HTTP Feedback Management:

HttpFeedback Deregister - Unregister HTTP feedback slot
HttpFeedback Enable - Enable HTTP feedback reporting
HttpFeedback Register - Register HTTP feedback slot with expressions

Security & Certificates:

Security Certificates CA Add - Upload CA certificates to device
Security Certificates CA Delete - Remove CA certificates from device
Security Certificates CA Show - Display installed CA certificates

Call Control:

Call Dial - Initiate outbound call

System Management:

SystemUnit Boot - Reboot the device
SystemUnit FactoryReset - Reset device to factory defaults

User Interface:

Ui GetDeviceScreenshot - Capture device screen image
Ui SendKey - Send keypress event to device

4. Event Notifications (xEvent)

Support: MPP and On-Prem

Subscribe to real-time event notifications for device state changes and call events.

xEvent Additions:

BootEvent - Device boot/restart notification
Shutdown - Device shutdown notification
SipCallDisconnect - SIP call disconnection event with call metrics
SipCallSuccessful - SIP call establishment event

API Access and Authentication

Supported Deployment Models

Model	MPP	On-Prem
8875	✓	✓
9841	✓	✓
9851	✓	✓
9861	✓	✓
9871	✓	✓

User Roles

The xAPI supports the following user roles with different access levels:

ADMIN - Full access to all xAPI commands, configurations, and status
INTEGRATOR - Access to integration-specific commands and status
USER - Limited access to user-level commands and status

Usage Examples

Query System Information

xStatus SystemUnit ProductId
*s SystemUnit ProductId: "DP-9841"
** end

xStatus SystemUnit Software Version
*s SystemUnit Software Version: "PHONEOS.3-5-1-1000"
** end

Monitor Network Status

xStatus Network IPv4 Address
*s Network IPv4 Address: "192.0.2.149"
** end

xStatus Network ActiveInterface
*s Network ActiveInterface: LAN
** end

Place a Call

xCommand Call Dial Number: "5000"

OK
*r CallDialResult (status=OK):
*r CallDialResult CallId: 0
*r CallDialResult LineId: 1
** end

Migration and Compatibility

From Legacy API

Devices upgrading from legacy proprietary APIs should:

Review new xAPI authentication requirements
Update integration scripts to use xAPI syntax
Test event subscriptions with new event schema
Verify certificate management workflows

Future Compatibility

The xAPI is designed for forward compatibility. New status items, commands, and events will be added in future releases while maintaining backward compatibility with existing integrations.

Resources

For detailed API documentation, examples, and integration guides, please refer to:

Support

For technical support and questions about xAPI implementation:

Visit the Cisco Developer Portal
Review the FAQ section
Contact Cisco TAC for deployment assistance