Knowlege base

Enabling Contact Manager Directories for Cisco Finesse Agents

Article ID: 670
Last updated: 20 Mar, 2023

Applies to:

Imagicle UC Suite ver. 2019.3.1 or newer


This article has been prepared in order to describe how Imagicle Contact Manager solution can be implemented in a Cisco UCCX-based and a generic contact center environment, where operators are equipped with CTI-enabled Cisco IP Phones and Cisco Finesse agent’s bar, or other third-party web-enabled CRM/ERP applications/agent’s bar.


  • Imagicle UC Suite Server must be reachable through a FQDN
  • The UCCX/UCCE and the Imagicle UC Suite servers must be on the same site, this means that the         domain’s name’s suffix must be the same. For example, if the UCCX/UCCE’s domain is, the Imagicle server’s domain must be and not If the UCCX/UCCE and the Imagicle servers don’t respect this rule, the authentication of Call Recording gadget won't properly work.
  • A valid Digital Certificate must be available


Application and Scope

Imagicle Contact Manager is the solution that centralizes and synchronizes company directories, providing fast searches, click to call and caller ID on phone, web, mobile and Cisco Jabber.

When a Cisco UCCX contact center solution is in place, it could happen that relevant operators need to access to above directories and services.

Integration of Imagicle Contact Manager gadget into Finesse gives the users the possibility to place a call, perform a transfer / blind transfer via Contact Manager gadget (Finesse supported versions are from 11.6.1 up to 12.5) directly within Finesse.

Note: For UCCX 12.5 you need to install Imagicle UC Suite Winter 2021 or following

Integration and allowed operations

Placing a Call

When there is no active and no call is being activated, it is possible to start a new call from contacts, as in picture below:

It is possible to also start a call from a contact, as in picture below:

Transferring a Call

During an active call, is possible to perform a consultation/blind transfer from contacts, as in picture below:

Similarly, during an active call, is also possible to perform a consultation/blind transfer directly from a specific contact, as in the following picture:

NOTE: Blind Transfer

Blind transfer is only available for from UCCX version 11.6.1 or newer.

In the previous versions, the icon is enabled by default and can be optionally disabled with a proper configuration

Dialed number

Actual dialed number, both when calling and transferring, differs from the displayed number and is generated (by Imagicle Application Suite) according to Jabber. As a result, the Outgoing Prefix is included according to the option "Use prefix for calls made through Cisco Jabber Desktop" value, reported in picture below.

Cisco/Imagicle Architecture

Calls from/to Cisco agents are routed through UCCX distribution engine, using preferred algorithm. Finesse web client is configured with a specific internal “Workflow” which is triggered upon call answering. This workflow invokes itself an “Action” item in charge of sending an HTTP POST message (REST API) to Imagicle server, including agent’s extension number and agent ID (agent ID currently not supported). When Imagicle server receives HTTP message, it immediately triggers BiB Call Recording on agent’s phone and relevant RTP/sRTP streams are generated toward Imagicle server.

Configuring Finesse for Contact Manager Directories

Configuration on Cisco Finesse: adding Contact Manager Gadget

To add Contact Manager gadget into Cisco Finesse agents panel, it is required to access to Cisco Finesse administrative page and head to “Desktop Layout”, in XML editing window, and locate <tabs> node. Here, it is required to add a child <tab> node, as follows:


Replace following placeholder:

  • {un-id-senza-spazi}
  • {ias-fqdn}: FQDN (and not IP ADDRESS) used by Finesse to reach Imagice Server. Please mind that this should be coherent with the certificate loaded on IAS IIS.
  • {label-gadget}: this is the string visible into Finesse Operators’ navbar. 

Configuration on IAS

By default in Cisco Finesse environment, Contact Manager gadget enables the following capabilities: call, consultation and blind transfer.  It is possible to configure such allowed capabilities into the Apps/ApplicationSuite/Settings/Finesse.ini config file:


It is possible to configure gadget title, specifying it into Apps/ApplicationSuite/Settings/Finesse.ini, configuration file; by default its title is “Imagicle Contacts”:

SpeedyGadgetTitle=Contatti ACME

It is possible to configure query string sent to Contact Manager gadget in Apps/ApplicationSuite/Settings/Finesse.ini configuraton file. Query string specified in settings is appended to ?AppMode=Finesse&Capabilities=MAKE_CALL, TRANSFER,TRANSFER_SST. By default, setting is “&HideLocalContacts=0”:


Contact Manager gadget must be accessible via HTTPS, using a trusted certificate.


Any modification to the above parameters requires Finesse cache to be cleared, as specified in next paragraph.

Known Limitations

  1. In the time frame (usually very short) between the click for an action (makeCall / transfer) and the reception of the telephone status change, buttons are not disabled. So, in case of slowdowns, user could be led to click multiple times (and each action could fail);
  2. In UCCX versions prior to 11.6.1, blind transfer is not available (this must be disabled manually from config file)
  3. Phones used by Finesse operators must be able to dial the same numbers as Jabber Clients.


Gadget not reachable

In case of the following error:

Check and make sure that:

  • IIS is started
  • Contact Manager (https://{ias-url}/gadgets/contactmanager) gadget is:
    • reachable from client PC where Finesse is open;
    • accessible via HTTPS and that certificate is valid and trusted;
  • Workaround: from client PC, open the link in a browser and accept the certificate.
  • If still can't load the page, press F12 or right-click on Reload browser button and select "empty cache and hard reload”

Issues with Finesse cache

In order to clear cache, please login to Finesse and press F12 to realod page and clean cache.

Then display source code of Finesse web page by hitting <CTRL> + U or other browser-specific hotkey. You will get a page similar to below screenshot:

Seek for "finesse_gadget_n" including Contact Manager and copy the URL available into "gadgets" folder.

Open another browser tab and paste above URL, replacing "nocache=0" with "nocache=1". Then hit Enter to execute the URL.

Gadget debug from client side

It is possible to perform debug for the Finesse API and Contact Manager gadget integration, by using developing tools in the browser used for  Finesse Contact Manager gadget.

  • Open browser developer tools;
  • head to console;
  • to filter only logs related to the Finesse - Contact Manager gadget communications, apply the following filter: 

Article ID: 670
Last updated: 20 Mar, 2023
Revision: 9
Views: 3008
Print Export to PDF Subscribe Share
This article was:  
Prev   Next
Troubleshooting     User Guides