Cisco JTAPI Developer Guide for Cisco CallManager 4.0(1)
Downloads: This chapterpdf (PDF - 256.0 KB) The complete bookPDF (PDF - 9.77 MB) | Feedback


Table Of Contents





New and Changed Information

Cisco CallManager Release 4.0(1)

Cisco CallManager Release 3.3

Cisco CallManager Release 3.2

Cisco CallManager Release 3.1


Related Documentation

Required Software


Obtaining Documentation

Documentation CD-ROM

Ordering Documentation

Documentation Feedback

Obtaining Technical Assistance

Developer Support

Cisco TAC Website

Opening a TAC Case

TAC Case Priority Definitions

Obtaining Additional Publications and Information


This chapter introduces Cisco JTAPI implementation, describes the purpose of this document, and outlines the required software. The chapter includes the following topics:




New and Changed Information


Related Documentation

Required Software


Obtaining Documentation

Documentation Feedback

Obtaining Technical Assistance

Obtaining Additional Publications and Information


Java Telephony Application Programming Interface (JTAPI) acts as a portable, object-oriented API for computer telephony integrated call control. The package of JTAPI interfaces located in the javax.telephony.* hierarchy, defines a programming model by which Java applications interact with telephony resources such as PBXs and telephones. The Cisco JTAPI implementation supports Java application access to Cisco Architecture for Voice, Video and Integrated Data (AVVID) communication systems according to the JTAPI v 1.2 specification. Furthermore, Cisco JTAPI exposes Cisco-specific events and methods for certain telephony resources such as calls and connections.


One of the primary goals of a standard Application Programming Interface (API) such as JTAPI is to provide an unchanging programming interface under which varied implementations may stand. Cisco's goal in implementing JTAPI for the Cisco CallManager platform is to conform as closely as possible to the JTAPI specification while providing extensions that enhance JTAPI and expose the advanced features of Cisco CallManager to applications.

As new versions of Cisco CallManager and the Cisco JTAPI implementation are released, variances in the API should be very minor and should tend in the direction of compliance. Cisco remains committed to maintaining its API extensions with the same stability and reliability, though additional extensions may be provided as new Cisco CallManager features become available.

This document outlines some basic JTAPI concepts including transfer and conference extensions. It also describes the support of extensions to the Sun JTAPI v 1.2 specification.


This document applies for telephony software developers who are developing Cisco IP Telephony applications that require JTAPI. This document assumes that the programmer is familiar with both the Java language and the Sun JTAPI v 1.2 specification.

New and Changed Information

This section describes any new features and or changes for Cisco JTAPI pertinent to the specified release of Cisco CallManager.

Cisco CallManager Release 4.0(1)

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 4.0(1):

Multiple Calls Per DN—Enables applications to have multiple calls on the same line with feature operations.

Shared Line Support—Provides applications the following abilities:

Control shared DN terminals

Hold a call on one Shared DN terminal and unhold the same call from another Shared DN terminal

Make calls between two Shared lines

Initiate a call from one Shared line terminal while there is another active call on another Shared line terminal with the same DN

Transfer and DirectTransfer—Provides the following enhancements:

Application can transfer two held calls

Application can have one held call and one connected call in any order

Application can transfer any two calls present on the line

Conference and Join—Enhanced to perform Arbitrary Conference of multiple calls

Barge, CBarge, and Privacy Event Notification—For Barge and CBarge, Cisco JTAPI supports manual feature activation on the application-controlled IP phones. Feature activation through the API is not supported. The Privacy feature provides a shared address ability to enable or disable other shared addresses to Barge into a call.

CallSelect and UnSelect Even Notification—Provides events for applications when they monitor RemoteInUse terminals. Applications can not invoke an API on the Passive or InUse TerminalConnection.

Dynamic CTIPort Registration Per Call—Enables applications to provide an ipAddress and port number for each call or whenever media gets established.

Media Termination at Route Point—Enables applications to terminate media for all active calls by specifying an ipAddress and port number for each call or whenever media gets established.

Redirect Set Original Called ID—Provides applications the ability to specify preferred original called party DN apart from the destination party information in the redirect request.

Single Step Transfer—Applications are provided the following enhancements:

A new call is not created

CiscoTransferStartEv and CiscoTransferEndEv' are not delivered to applications

The state of the original call gets retained if the transfer operation fails

Auto Update of API—Provides a facility by which an application at startup can identify itself to a web server via an HTTP request and receives a response with the version of the required JTAPI API. The application compares the version available on the server to the local version in the application classpath and determines whether an upgrade is necessary.

CiscoTerminal Filter and ButtonPressedEvents—Enables applications to receive the CiscoTermButtonPressedEv when a digit gets pressed on the phone.

Modifying Calling Number—Enables applications to modify the calling party in the select route API from a route point.

AutoAccept support for CTIPort and RoutePoint—Provides applications the ability to enable or disable AutoAccept for the addresses on the CTIPort and RoutePoint. When changes occur to AutoAccept on the address, the application receives CiscoAddrAutoAcceptStatusChangedEv on AddressObservers.

CiscoTermRegistrationFailed event—Provides the applications with an event when CiscoMediaTerminal or CiscoRouteTerminal registration asynchronously fails.

SelectRoute Interface Enhancement—Enhances the SelectRoute interface to take the parameters "PreferedOriginalCalledNumber" and "PreferedOriginalCalledOption", which enables applications to reset the OriginalCalled value to a specified "PreferedOriginalCalledNumber" when the call gets routed.

Presentation Indicator (PI) for the Call—Provides applications with the ability to hide or reveal Calling/Called/CurrentCalling/CurrentCalled/LastRedirecting parties name and number to the end user.

Cisco CallManager Release 3.3

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.3:

CallParkRequest, CallParkResponse, and Parked DN Monitoring—Defines new extensions to allow applications to park a call or unpark a call.

XSI Object Pass Through—Allows application to pass an XML object through a Cisco JTAPI or CTI interface to an IP phone.

VG248 and ATA 186 Analog Phone Gateways—Supports control of analog phones that are connected to these gateways.

Cisco JTAPI Installation Internationalization—Supports multiple languages for the Cisco JTAPI installation and the user preference user interface. Refer to the Cisco CallManager 3.3 JTAPI Installation Guide for more information.

Enable or Disable Ringer—Supports application control of ringer settings for each address on a device.

Clear Calls Interface—Provides a clearCallConnections interface that allows applications to remove phantom calls without removing the call observer.

Display Name Interface—Extends the CiscoCall interface to provide methods to get name displays of the calling party and the called party in a call. Applications can use getCurrentCallingPartyDisplayName() to get the display name of the calling party.

SetMessageWaiting Interface—Provides a method for applications to set the message waiting lamp or indicator for an address.

Quite Clear—Provides QuiteClear at the other end when two parties are on a call and one address goes OutOfService because of a network outage, the Cisco CallManager goes down, application controlling CTIPort goes down, or CTIManager goes down.

GetCallInfo Interface—Provides applications with the ability to query CallInfo on an address. A query returns the CiscoAddressCallInfo object, which contains information about the number of active or held calls, maximum number of active or held calls, and the Call object for current calls on the address. This interface also provides information regarding what calls are at a specific address at a specific time.

DeleteCall Interface—Provides applications with the ability to delete a call that was created using the createCall interface. This method accepts a call and throws an InvalidStateException if a provider is not in service or if the call is not in the IDLE state. DeleteCall moves the call to the INVALID state.

GetGCID—Provides an interface on the CiscoCallID to get the nodeID and the GCID of the call, which exposes the GCID information that is available in the internal call object.

GetCallID in RTP Events—Provides an interface on RTP events to access any call information, so applications can link RTP events with the calls.

Cisco CallManager Release 3.2

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.2:

Call Park—Cisco JTAPI supports user interactions with Call Park and reports appropriate events to the applications.

Super Provider—Supports static control of devices and the ability to query for devices.

Reconnect Logic—Connects Cisco JTAPI applications to the secondary CTIManager after waiting for a random time, so all Cisco JTAPI applications do not connect to the secondary CTIManager at the same time.

Cisco CallManager Release 3.1

The following list provides the features or changes for Cisco JTAPI in Cisco CallManager release 3.1:

CTIManager component—Allows a JTAPI application to control devices on another Cisco CallManager in a cluster. It supports multiple Cisco CallManagers and CTI managers during failover and recovery and supports automatic device recovery during a failover.

Directory Change Notification—Allows asynchronous directory change notification.

Transfer and Conference Enhancement—Allows enhancements to Transferring & Conferencing.

Call Forward Setting—Allows Cisco JTAPI implementation for supporting Call Forwarding.

CiscoJtapiExceptions—Allows CiscoJtapiException handling modifications.

Redirect—Allows a Cisco JTAPI Redirect request.

Alarm Services—Allows Cisco JTAPI support for Alarm Services.

Application Control of JTAPI Parameters—Allows control of the parameters within jtapi.ini.

Dynamic Trace Enabling Using Jtprefs—Allows dynamic enabling of traces from the Jtprefs application.


The following table provides an outline of this document organization.


Chapter 1, "Overview"

This chapter introduces the major concepts with which you need to be familiar before creating JTAPI applications for Cisco IP Telephony Solutions.

Chapter 2, "Cisco JTAPI Implementation"

This chapter describes the interfaces and classes that are available.

Chapter 3, "JTAPI Examples"

This chapter provides the source code for makecall, which is the Cisco JTAPI program that is used to test the JTAPI installation.

Appendix A, "Message Sequence Charts"

This appendix contains message flow diagrams.

Appendix B, "Cisco JTAPI Classes and Interfaces"

This appendix contains a listing of all the classes and interfaces that are available in the Cisco JTAPI implementation for Cisco CallManager.

Appendix C, "Troubleshooting CiscoJTAPI"

This appendix contains CTI Error Codes, CiscoEvent IDs, and other information to assist with troubleshooting efforts.

Related Documentation

The companion document Cisco JTAPI Developer Reference (JTAPI v 1.2 Specification) contains the Sun JTAPI specification for the supported interfaces and classes and their respective methods. This document set includes the specification downloaded from the Sun JTAPI web site, as a convenience to Cisco JTAPI programmers. The writing style in that book conforms to the Sun specification; it does not conform to the Cisco writing style.

To obtain the very latest version of the JTAPI specification files, go directly to the web site at:

The Sun Microsystems Inc. JTAPI v 1.2 specification

Required Software

The following table lists software requirements for the following applications: JTAPI applications, JTPREFS, and sample code.


Required Software

JTAPI applications

Any JDK 1.1 compliant java environment

Microsoft Internet Explorer 4.01 or later

Sun JDK 1.1, 1.2, or 1.3


Microsoft Internet Explorer 4.01 or later


Sample code

Microsoft Internet Explorer 4.01 or later



This document uses the following conventions:


boldface font

Commands and keywords are in boldface.

italic font

Arguments for which you supply values are in italics.

[   ]

Elements in square brackets are optional.

{ x | y | z }

Alternative keywords are grouped in braces and separated by vertical bars.

[ x | y | z ]

Optional alternative keywords are grouped in brackets and separated by vertical bars.


A nonquoted set of characters. Do not use quotation marks around the string or the string will include the quotation marks.

screen font

Terminal sessions and information the system displays are in screen font.

boldface screen font

Information you must enter is in boldface screen font.

italic screen font

Arguments for which you supply values are in italic screen font.


This pointer highlights an important line of text in an example.


The symbol ^ represents the key labeled Control—for example, the key combination ^D in a screen display means hold down the Control key while you press the D key.

<   >

Nonprinting characters, such as passwords are in angle brackets.

Notes use the following conventions:

Note Means reader take note. Notes contain helpful suggestions or references to material not covered in the publication.

Obtaining Documentation

Cisco provides several ways to obtain documentation, technical assistance, and other technical resources. These sections explain how to obtain technical information from Cisco Systems.

You can access the most current Cisco documentation on the World Wide Web at this URL:

You can access the Cisco website at this URL:

International Cisco websites can be accessed from this URL:

Documentation CD-ROM

Cisco documentation and additional literature are available in a Cisco Documentation CD-ROM package, which may have shipped with your product. The Documentation CD-ROM is updated regularly and may be more current than printed documentation. The CD-ROM package is available as a single unit or through an annual or quarterly subscription.

Registered users can order a single Documentation CD-ROM (product number DOC-CONDOCCD=) through the Cisco Ordering tool:

All users can order annual or quarterly subscriptions through the online Subscription Store:

Click Subscriptions & Promotional Materials in the left navigation bar.

Ordering Documentation

You can find instructions for ordering documentation at this URL:

You can order Cisco documentation in these ways:

Registered users (Cisco direct customers) can order Cisco product documentation from the Networking Products MarketPlace:

Nonregistered users can order documentation through a local account representative by calling Cisco Systems Corporate Headquarters (California, USA) at 408 526-7208 or, elsewhere in North America, by calling 800 553-NETS (6387).

Documentation Feedback

You can submit e-mail comments about technical documentation to

You can submit comments by using the response card (if present) behind the front cover of your document or by writing to the following address:

Cisco Systems
Attn: Customer Document Ordering
170 West Tasman Drive
San Jose, CA 95134-9883

We appreciate your comments.

Obtaining Technical Assistance

For all customers, partners, resellers, and distributors who hold valid Cisco service contracts, the Cisco Technical Assistance Center (TAC) provides 24-hour-a-day, award-winning technical support services, online and over the phone. features the Cisco TAC website as an online starting point for technical assistance. If you do not hold a valid Cisco service contract, please contact your reseller.

Developer Support

The Developer Support Program provides formalized support for Cisco Systems interfaces to enable developers, customers, and partners in the Cisco Service Provider solutions Ecosystem and Cisco AVVID Partner programs to accelerate their delivery of compatible solutions.

The Developer Support Engineers are an extension of the product technology engineering teams. They have direct access to the resources necessary to provide expert support in a timely manner.

For additional information on this program, refer to the Developer Support Program Web Site at support/.

Developers using the Cisco JTAPI Developer Guide for Cisco CallManager 4.0(1) are encouraged to join the Cisco Developer Support Program. This new program provides a consistent level of support while leveraging Cisco interfaces in development projects.

Note Cisco Technical Assistance Center (TAC) support does not include Cisco JTAPI Developer support and is limited to Cisco AVVID installation/configuration and Cisco-developed applications. For more information about the Developer Support Program, please contact Cisco at

Cisco TAC Website

The Cisco TAC website provides online documents and tools for troubleshooting and resolving technical issues with Cisco products and technologies. The Cisco TAC website is available 24 hours a day, 365 days a year. The Cisco TAC website is located at this URL:

Accessing all the tools on the Cisco TAC website requires a user ID and password. If you have a valid service contract but do not have a login ID or password, register at this URL:

Opening a TAC Case

Using the online TAC Case Open Tool is the fastest way to open P3 and P4 cases. (P3 and P4 cases are those in which your network is minimally impaired or for which you require product information.) After you describe your situation, the TAC Case Open Tool automatically recommends resources for an immediate solution. If your issue is not resolved using the recommended resources, your case will be assigned to a Cisco TAC engineer. The online TAC Case Open Tool is located at this URL:

For P1 or P2 cases (P1 and P2 cases are those in which your production network is down or severely degraded) or if you do not have Internet access, contact Cisco TAC by telephone. Cisco TAC engineers are assigned immediately to P1 and P2 cases to help keep your business operations running smoothly.

To open a case by telephone, use one of the following numbers:

Asia-Pacific: +61 2 8446 7411 (Australia: 1 800 805 227)
EMEA: +32 2 704 55 55
USA: 1 800 553-2447

For a complete listing of Cisco TAC contacts, go to this URL:

TAC Case Priority Definitions

To ensure that all cases are reported in a standard format, Cisco has established case priority definitions.

Priority 1 (P1)—Your network is "down" or there is a critical impact to your business operations. You and Cisco will commit all necessary resources around the clock to resolve the situation.

Priority 2 (P2)—Operation of an existing network is severely degraded, or significant aspects of your business operation are negatively affected by inadequate performance of Cisco products. You and Cisco will commit full-time resources during normal business hours to resolve the situation.

Priority 3 (P3)—Operational performance of your network is impaired, but most business operations remain functional. You and Cisco will commit resources during normal business hours to restore service to satisfactory levels.

Priority 4 (P4)—You require information or assistance with Cisco product capabilities, installation, or configuration. There is little or no effect on your business operations.

Obtaining Additional Publications and Information

Information about Cisco products, technologies, and network solutions is available from various online and printed sources.

The Cisco Product Catalog describes the networking products offered by Cisco Systems, as well as ordering and customer support services. Access the Cisco Product Catalog at this URL:

Cisco Press publishes a wide range of general networking, training and certification titles. Both new and experienced users will benefit from these publications. For current Cisco Press titles and other information, go to Cisco Press online at this URL:

Packet magazine is the Cisco quarterly publication that provides the latest networking trends, technology breakthroughs, and Cisco products and solutions to help industry professionals get the most from their networking investment. Included are networking deployment and troubleshooting tips, configuration examples, customer case studies, tutorials and training, certification information, and links to numerous in-depth online resources. You can access Packet magazine at this URL:

iQ Magazine is the Cisco bimonthly publication that delivers the latest information about Internet business strategies for executives. You can access iQ Magazine at this URL:

Internet Protocol Journal is a quarterly journal published by Cisco Systems for engineering professionals involved in designing, developing, and operating public and private internets and intranets. You can access the Internet Protocol Journal at this URL:

Training—Cisco offers world-class networking training. Current offerings in network training are listed at this URL: