Getting Started

Cisco BroadWorks is designed, built and operates on open standards. These include developer interfaces based on IETF, 3GPP, ETSI, and other industry RFCs as well as XML-based APIs published and supported by Cisco. BroadWorks provisioning and secure access to APIs on production or pre-production deployments are totally dependent on access granted by a hosting Service Provider.

Though not an exhaustive list of BroadWorks APIs, developers can use these most common to create value added services around BroadWorks deployments:

  • SIP Interface
  • SIPREC Interface
  • XSI Interface
  • OCI-P Interface
  • Accounting/CDR Interface
  • IMS Interface
  • Fault Management/SNMP Interface
  • UMS XMPP Interface
  • UC-One Communicator
  • UC-One USB-HID Interface

The following will provide basic information around each interface with links to more detailed developer documentation.

SIP Interface

BroadWorks systems are generally deployed with an “access” IP interface for subscribers’ devices and applications and a back-office “network” IP interface for communication between the Service Provider’s various application and network servers. BroadWorks uses SIP (RFC 3261) signaling protocol for communication in both access interfaces and network interface elements.

SIP access interface - The BroadWorks access interface, in contrast with the network interface, provides access from devices on customer networks or the public Internet and are usually considered untrusted. Developers create SIP compliant access devices include IP telephones, calling apps (PC, mobile), attendant consoles apps, analog terminal adapters, IP media gateways, IP PBX, edge Session Border Controllers (eSBC), and call recording applications to name a few.

SIP network interface - The BroadWorks network interface is used to communicate between BroadWorks servers and Service Provider network elements. Developers create SIP compliant network services, including application servers, soft-switches, network servers, SIP proxies, and so on. The network-side elements are assumed to be trusted and protected by security protocols, firewalls, and other security measures.

BroadWorks:

  • is implemented as a back-to-back user agent (B2BUA), redirect server, and a registrar.
  • interworks with user agents, redirect servers, and proxy servers.
  • does not support the register mechanism with network devices but does support the register mechanism with access devices (that is, phone, soft clients, and so on).
  • does not support authentication with network devices but does support authentication with access devices.
  • supports both UDP and TCP transports.
  • can be configured to support IPv4 only, IPv6 only, or both IPv4 and IPv6 simultaneously.
  • is considered a trusted node in the network and is assumed to have secure connections to other network devices.
  • access interface is considered untrusted by default. However, specific access devices may be configured as trusted devices.
  • supports receiving SIP URIs and TEL URIs.
  • does not tandem/proxy calls (all calls received by BroadWorks must be destined for a BroadWorks user).
  • rejects calls not destined for a BroadWorks user, by returning a 404 (User Not Found) response.

Developers should refer to the BroadWorks Device Management Config and Tag Reference Guides, SIP Access Interface and SIP Network Interface Interworking Guides for specifications, highlights and clarifications on how these are RFCs supported by BroadWorks in applications and devices.

SIPREC Interface

The Call Recording Service on the BroadWorks Application Server is a user assignable service that allows user recording of calls using the SIPREC signaling protocol. The SIPREC interface allows a BroadWorks deployment to record calls via a Third-Party Call Recording (3PCR) application. The interface is based on the specifications of the IETF SIPREC working group. Developers can also leverage the BroadWorks XSI Actions interface to create on-demand recording applications.

The developer’s call recording application is responsible for the media storage and management call recording media. BroadWorks provides the media streams of a call being recorded and information about the parties in the call.

This Call Recording Service can be assigned to BroadWorks users and the hosted Private Branch Exchange (PBX) and Business Connectivity applications, in particular:

  • Call Center
  • Route Point
  • Attendant Console

The Call Recording Service supports:

  • Start, Stop, Pause, and Resume
  • Video
  • End User Notification of Recording
  • Voice Mail Recording
  • User Control for IP Phones
  • Visual Security Classification for Active Call

Developers should refer to the BroadWorks Call Recording Interface Guide for specifications, highlights and clarifications on how IETF specifications for SIPREC are supported by BroadWorks.

XSI Interface

Service providers offer a BroadWorks-based calling service normally consisting of connectivity, features, phone numbers and usage or minutes. The service provider or third-party developers can provide enhanced functionality above the basic service offering through the use of the eXtended Services Interface (XSI).

BroadWorks XSI application programming interfaces support the integration of BroadWorks functions to create Web Applications. By adding a public web service interface, the BroadWorks-based voice services can be integrated with Internet services - outside of BroadWorks.

The Xtended Services are a set of RESTful APIs that allows resources to be defined and addressed over HTTP with simple XML. This approach requires less client-side software to be written than other approaches and is the overwhelming choice for developers to create Web Applications.

XSI is very scalable and designed to be used securely over multiple protocols by different types of applications. The XSI interface informs external applications when BroadWorks subscriber activity occurs. The notifications occur when an application subscribes for one or more events from a set of available event packages.

The following parts of the XSI interface are designed to work together to allow developers to create rich web applications:

XSI-Actions

XSI-Actions are a set of RESTful APIs that allow access to resources on BroadWorks. All actions are initiated by the clients on a resource and a response is returned from the server. The action may be a modification or retrieval of data. XSI-Actions expose a broad spectrum of functionality to support a variety of web applications.

The areas exposed are:

Call Management – Exposes real-time call control primitives, such as Click To Dial, Answer, Hold, Transfer, and so on.

Call Status – Exposes the real-time abilities to retrieve the list of active calls and determine the call state of those calls.

Call Lists – Exposes the commonly accessed lists, such as placed, received, and missed call logs, as well as enterprise, group, and personal directories.

Service Management – Exposes the ability to retrieve and configure services managed by the BroadWorks Application Server.

XSI-Events

XSI-Events is a web application which allows third parties to subscribe to BroadWorks for particular event packages via HTTP. When events occur that have been subscribed to, BroadWorks sends a notification via HTTP to the address specified in the subscription. This allows web applications to receive notifications when resources change state on BroadWorks by another mechanism.

There are two main areas that are exposed:

Call Events – Allows notification of real-time call information on active calls. Notifications are sent when calls are ringing, answered, transferred, and so on.

Service Events – Allows notification when service configuration has changed.

Media

The BroadWorks Media Server complies with VoiceXML 2.0, VoiceXML 2.1, CCXML 1.0, and draft-ietf-mediactrl-vxml.

VoiceXML is a standard defined by the World Wide Web Consortium (W3C) that provides a scripting language optimized for building interactive voice response (IVR) dialogs. Specifically, VoiceXML can:

  • Play and record audio and video prompts
  • Handle dual-tone multi-frequency (DTMF) tones
  • Say phrases using a text-to-speech server
  • Detect spoken words using a speech recognition server
  • Transfer calls

CCXML is a standard defined by the World Wide Web Consortium (W3C) that provides a high-level scripting language for call control. Media services such as Calling Cards, Voice Mail, Video Auto-Attendant, and Meet-Me Conferencing can be built in CCXML. CCXML is a call control environment that can:

  • Originate calls
  • Handle incoming calls: accept calls, redirect calls, and reject calls
  • Transfer calls
  • Establish and control conferences

CCXML and VoiceXML scripts can be combined to control these functions:

  • Play back of audio and video prompts
  • Record audio and video messages
  • Detection of DTMF tones
  • Conference ports
  • Text-to-speech
  • Speech recognition

Finally, CCXML scripts can also act as Hypertext Transfer Protocol (HTTP) clients and HTTP servers, allowing CCXML scripts to interact with commercial third-party application servers such as BEA WebLogic and IBM WebSphere.

Components of VoiceXML and CCXML Solution

The components and their functions are:

Media Server (also known as Media Resource Function), which is responsible for:

  • Fetching VoiceXML and CCXML scripts from an external web server
  • Executing VoiceXML and CCXML scripts
  • Receiving and originating calls using the SIP protocol
  • Playing and recording audio and video prompts
  • Communicating with text-to-speech and speech recognition servers

Web Server, which is responsible for:

  • Hosting VoiceXML and CCXML scripts
  • Hosting audio and video files
  • Communicating with an external database

SIP Proxy, which is responsible for:

  • Proxying SIP messages to and from external SIP devices, such as SIP phones

External Database, which contains application-specific data such as subscribers and their profiles
Speech recognition Server, which recognizes unique words from speech spoken by callers
Text-to-Speech Server, which transforms text into spoken words

There are numerous public resources for learning more about VoiceXML and CCXML.

Developers should refer to the BroadWorks Xtended Services Interface documentation for specifications for before attempting to use the XSI interfaces. It is recommended that new developers begin with XSI-Actions to build a knowledge base. Developers only interested in IVR type applications can just look at XSI-Media, but most likely will need XSI-Actions also to create the rich applications desired.

OCI-P Interface

OCI-P is a comprehensive interface for the BroadWorks Application Server. This interface allows your application to securely connect and perform provisioning changes to the core BroadWorks system and subscriber data.

Typically, you use OCI-P when you need to integrate a BroadWorks system into the Service Provider’s VoIP network AND:

  • You are creating a web portal app for administrators and/or subscribers to access system/subscriber data
  • You have a legacy provisioning system that you want to integrate with BroadWorks data to create and modify system/subscriber data
  • You are creating a rich client application that is targeted to subscribers that are hosted on a BroadWorks VoIP network
  • You intend to authenticate and maintain a client's connection to BroadWorks.

Developers should refer to the BroadWorks OCI-P Interface documentation for specifications for before attempting to use the OCI interface. For more simple or end-user oriented applications, the Xtended Services Interface (Xsi) may provide a better and quicker interface to use.

Accounting/CDR Interface

The BroadWorks application transmission of accounting data is performed either by sending accounting files with many CDRs over FTP, or by sending CDRs one at a time, in real-time, using the Radius protocol (RFC2866 compliant).

When file output is enabled in BroadWorks, CDRs are written to files which must be transferred to an external billing application. Batch-mode FTP is supported for transmission. In this mode, CDR files are transferred via FTP periodically to the system provider’s billing system or mediation device. The CDR files can be optionally archived for a configurable number of days.

Developers should refer to the BroadWorks Accounting Call Detail Recording Interface documentation for specifications for a thorough understanding of the interface and BroadWorks setup properties.

IMS Interface

The BroadWorks Application Server (AS) and Media Server (MRF) can be deployed as standard elements within a mobile operator’s next generation IMS architecture.

AS – The BroadWorks Application Server (AS) performs call control, user database, back to back user agent, and service execution engine functions. Signaling interaction between the Application Server and other IMS components occurs via SIP. The BroadWorks AS interacts with other network elements over the ISC, Sh, Rf, and Ro interfaces.

MRF - The BroadWorks Media Server (MRF) contains both MRFC and MRFP functional components and provides conferencing resources, and IVR resources. If the BroadWorks Media Server is used, interaction occurs at the media level via RTP/Real-Time Control Protocol (RTCP).

IMS Core Architecture

Cisco BroadWorks is comprised of a family of servers that integrate seamlessly into IMS-based mobile operator networks to provide a fully integrated solution:

  • The Network Functions Manager (NFM), a core server, provides an integrated point for Fault, Configuration, Accounting, Performance, and Security (FCAPS) access to all BroadWorks servers.
  • The Xtended Services Platform provides an integrated point for service provisioning by operators with different levels of administrative privileges (system provider, service provider, group, and user).
  • The Network Server provides enhanced network translations as well as a location service that reports the Application Server assigned to a BroadWorks user.
  • The Profile Server provides a centralized file repository for use by media resources and device management.
  • The Enhanced Call Logs Repository provides for the storage and retrieval of detailed call logs, enhancing customer service and OA&M functions.

BroadWorks in an IMS Core

BroadWorks Sh Interface - The Sh interface provides communication between the BroadWorks Application Server and the HSS. It is used to access subscriber profile data, which determines the services authorized to end-users. Subscriber profile data is transferred as eXtensible Markup Language (XML) data using the Diameter protocol. Messages contain both nontransparent data for service logic (IMS/subscriber-specific) and transparent data stored and used by Application Servers (application-specific).

BroadWorks Dh Interface - The Dh interface provides communication between the BroadWorks Application Server and the Subscription Locator Function (SLF). The SLF is used when there are multiple HSS entities within the network. It is not always shown in diagrams, as most networks initially have only one HSS. In general, it should be assumed this functionality is included when describing the BroadWorks Sh interface.

BroadWorks ISC Interface - The IMS Service Control (ISC) interface provides communication between an IMS-compliant application server, such as the BroadWorks Application Server, and the S-CSCF. It allows SIP requests to be routed from terminal devices to an application server and supports application server-initiated SIP requests to the S-CSCF. SIP signaling is used, extended by several private headers (P-Headers) to meet telephony needs. P-Headers are extensions to SIP, defined by 3GPP in TS 24.229 (see also 3GPP2 X.P0013.4).

BroadWorks Mr Interface - The Mr interface provides communication between the MRFC/MRFP (for example, the BroadWorks Media Server) and the Application Server. It allows for SIP signaling to be used as the “control” protocol for the Media Server (MRFC). This includes Media Server Control Markup Language (MSCML), used for IVR functions, and NETwork ANNouncments (NETANN), used to differentiate interactive voice response (IVR), conferencing, fax, and conferencing control. It also serves as the means for the Application Server to establish a dedicated control channel with the MRF. This control channel is formally designated the Cr interface. Typically, the BroadWorks Application Server maintains a list of available BroadWorks Media Servers. Media Server addressing should not need a public address (that is, it should not use an HSS entry).

NOTE: The Mr interface serves the same purpose as the Mr interface, the difference being that the Mr interface connects the Application Server and the MRF directly, whereas the Mr interface connects the Application Server and the MRF via the S-CSCF and the ISC interface. The BroadWorks Application Server sends SIP messages directly to the Media Server via the Mr interface, rather than routing them through the S-CSCF and the ISC and Mr interfaces.

BroadWorks Cr Interface - The Cr interface defines a dedicated control channel between an Application Server and an MRF. In a BroadWorks deployment, the BroadWorks Application Server and the BroadWorks Media Server interact for various services, such as conference mixing or call recording, using the Cr interface.

BroadWorks Rf Interface - The Rf interface provides communication between the Application Server and the IMS Charging Data Function (CDF). It is used to support an offline charging model (that is, postpaid/contract charging). Data is transferred using Diameter Accounting-Request (ACR) and Accounting-Answer (ACA) messages. Charging information is stored and extracted in the following IMS-based P-headers: P-Charging-Vector and P-ChargingFunction-Addresses.

BroadWorks Ro Interface - The Ro interface provides communication between the Application Server and the IMS Online Charging System (OCS). The Application Server uses the OCS to reserve and/or debit credits at call setup time, as well as at other times during a call, for the Prepaid service. Additionally, it may query the OCS for rate information to support the Advice of Charge service.

Configuring BroadWorks for use in IMS architecture is a straightforward task. Although IMS offers the comfort of standard, well-defined interfaces, the format and interpretation of messages exchanged over these interfaces must be well understood.

Developers and IMS architects should refer to the various BroadWorks IMS Interface documentation for specifications for thorough understanding of these interfaces.

Fault Management /SNMP Interface

BroadWorks supports SNMP v2c and v3. Service Providers are provided a set of comprehensive CLI commands to manage the SNMP trap redirection. Note that BroadWorks also acts as an SNMP proxy agent for a Solaris platform agent.

By default, BroadWorks listens on port 8001 to service SNMP get requests. Compared to other typical SNMP agents, the BroadWorks agent cannot listen on port 161.

Note that the community strings apply only for v2c requests. For a system with multiple network interfaces, the operator can also choose the interface to use to send SNMP traps.

The SNMP reporting level allows an operator to automate the generation of an operational measurements report, which is sent to remote servers. The report (in XML format) contains a header and a value for each SNMP counter and gauge. The report is sent to remote servers via FTP put commands.

Developers should become familiar with BroadWorks SNMP Interface and Performance Measurement Interface documentation for before attempting to create or interface with your management applications.

UC-One Communicator App Interface

The UC-One Communicator app includes an API based on HTTP/websocket, useful for developing various types of CRM enablement (plug-ins), USB headset controls, or other creative applications. The HTTP-based API supports both web and traditional application and is available starting with UC-One release 21. Release 22.5.0 added support for WebTabs.

The WebSocket backend inside UC-One Communicator employs keepalives using standard WebSocket pings. The WebSocket implementation used by latest browsers responds to server-initiated pings. When using a WebSocket implementation that does not respond in this way, and there is no activity on the channel for some time, the connections are disconnected by UC-One Communicator.

The globally unique identifier (UUID) that UC-One Communicator uses to identify each API user software is permanent and must not change during the lifetime - including version upgrades etc. – of an API user software.

The diagram below shows the high-level architecture of API users connecting to UC-One Communicator. There are two example API user software (Web Application 1 and Web Application 2) connected to UC-One Communicator over the API. In the figure's case, Web Application 1 is additionally using the HID interface to control USB device(s).

UC-One Communicator API Architecture

Requests

All API requests are asynchronous HTTP GET requests. Incoming data arrives via websocket channel (no data is returned directly by a request).

Available requests:

  • SubscribeEvents
  • RequestContacts
  • RequestGroups
  • ShowClientWindow
  • StartCommunication
  • StopCommunication
  • SetPresence
  • RequestContactProperties
  • RequestContactPresence
  • CallHold
  • CallAnswer
  • CallHangup
  • CallVolume
  • CallMute
  • CallSendDTMF
  • NotifyButtonState
  • SendInstantMessage
  • RequestMyRoomInfo
  • SetCommunicationControls
    • ControlChat
    • ControlAudio
    • ControlVideo
    • ControlShare
    • ControlPanel
    • ControlDialInfo
    • ControlParticipantList
    • ControlContextualGadget
  • LoadWebTab
  • CloseWebTab

Notifications

Users can subscribe to different notifications. All notifications are delivered over a websocket connection in JSON format.

Event types

  • Calls
  • PresenceChanges
  • ContactChanges
  • GroupChanges
  • Voicemail
  • LanguageChange
  • InstantMessages
  • Settings
  • WebTab

Notification events

  • registration
  • APIVersion
  • ContactProperties
  • GroupDetails
  • ContactRemoved
  • GroupRemoved
  • SubscribedEvents
  • SessionCapabilities
  • SignedOut
  • Presence
  • NewCall
  • CallState
  • CallMuteState
  • VoicemailDetails
  • ApplicationLanguage
  • NewInstantMessage
  • ApplicationData
  • MyRoomInfo
  • ClearLogs
  • UCVersion
  • ApplicationSettings
  • WebTab

Developers can refer to the UC-One Communicator Desktop SDK for API request and notification specifics and examples.

UMS XMPP Interface

The BroadWorks Messaging Server (UMS) uses standard XMPP federation to federate with other Collaborate installations, standard XMPP solutions, or proprietary solutions that provide XMPP federation support.

The BroadWorks Messaging Server supports federation with the following:

  • BroadWorks Messaging Server for
    • One-on-One Chat
    • Enhanced Presence Notifications
    • File Transfer
    • Free Text
    • Group Chat
    • Location Data
    • Screen Share
    • Standard Presence Notifications
    • User Avatar
  • Standard XMPP servers for:
    • One-on-One Chat
    • File Transfer
    • Free Text
    • Group Chat (XMPP client/server restrictions could apply)
    • Standard Presence Notifications
    • User Avatar
  • Microsoft OCS 2007, Lync 2010, and Lync 2013 for:
    • One-on-One Chat

Developers can refer to the UC-One Communicator Desktop SDK for API request and notification specifics and examples.

UC-One USB-HID Interface

PC headset or audio device developers can take advantage of the USB Human Interface Device (HID) API included with the BroadWorks UC-One calling app. UC-One users can answer, mute/un-mute and hang-up on calls from controls within a USB-HID compatible headset or device. Volume control is managed by the PC volume control and not reflected in the UC-One UI.

A standard BroadWorks USB-HID Add-in is provided with the UC-One app and automatically provisioned. Headset or device developers can create your own USB-HID add-in that replaces the standard UC-One Add-in.

A new add-in should be installed with the first connection of the new USB headset or device. USB-HID Add-ins can be enabled or disabled via Preferences settings in the UC-One app.

The following is the default add-in folder location (note that it is not possible to write to this location in all systems):

  • Windows 7/Windows 8/8.1/10: C:\Program Files (x86)\BroadSoft\UC-One\connectors

Developers can refer to the UC-One User Guide for information on enabling USB-HID-Add-ons for controlling USB-HID compliant interfaces.