Set up click to dial and click to transfer

This information is primarily for administrators and/or people who manage Zylinc solutions

Click to dial or click to transfer is an API within Zylinc Client Manager that's useful when you want to integrate Zylinc call handling functions with a third-party system. For example, you can create buttons in a program or on a website to do the following:

  • Initiate an outgoing call to a phone number, without the need for the user to touch the keypad on the phone (also known as: Click-to-dial, Click-2-dial or Click2Dial).
  • Initiate a transfer of a user’s active call to a voice queue, to another agent (who’s online), or to an internal or external phone number (also known as: Click-to-transfer, Click-2-transfer or Click2Transfer).

The API is designed to be run within a secure network zone of your organization. Because of that, you don't need a user name or password, or any authentication procedures to use the API.

What's Client Manager?Closed It's a Tomcat service that handles all client-related business logic on the Zylinc solution, for example the state of agents, queues, incoming calls, wrapup time, and callbacks. Because Client Manager handles this logic, the clients themselves, for example ZyDesk, almost entirely consist of user interfaces.

You can use the function that initiates an outgoing call without the need to set up additional integrations between the third-party system and Zylinc, as long as you know the e-mail address of the user to initiate the call for, and the number to call.

This method requires that the user is currently logged in to a Zylinc client as an agent. Because of that, a Zylinc license that supports agents and voice queues must be available to the user.

For ZyDesk, the user can be logged in with one of the following profiles: Attendant Console, Contact Center, or Service Center.

Other Zylinc client types will also work, as long as the user is logged in as an agent, and the client type supports voice queues. For example, the user can log in as a voice queue member (clientless login) or log in to Zylinc Mobile as an agent.

When you use this method to initiate an outgoing call, the following events will occur:

  1. The Zylinc solution checks whether an agent with the e-mail address specified in the user parameter is currently logged in. If that’s not the case, the method will fail.
  2. The Zylinc solution's Media Server initiates a call to the phone number that's registered to the agent as agent device
  3. The moment the agent answers the call, the Media Server initiates a new outgoing call to the phone number specified in the target parameter, and then the Media Server connects (bridges) the outgoing call to the agent with the outgoing call to the target number.

URL: http://<Windows application server>:8080/ClientManager/dial?user={user}&target={target}&type=zycall

Method: GET

Query Parameters:

  • user: The e-mail address of an agent who's currently logged in.
  • target: The phone number to call. If the number contains a + character, and you use the method from within a hyperlink, substitute the + character with %2B. If you use the method from an HTML form, don't substitute; the web browser will take care of the substitution.
  • type: zycall

Example URL for method 1

Initiate an “outgoing” call from the phone (agent device) that's registered to the agent who's currently logged in as agent@email.domain, to phone number +4512345678.

http://<Windows application server>:8080/ClientManager/dial?user=agent@email.domain&target=%2B4512345678&type=zycall

This method doesn't require that the user is logged in to a Zylinc client as an agent. Because of that, you can use this method together with Zylinc Team Center, and a license that supports agents and voice queues isn't needed.

The user must use either a BroadWorks or Cisco desktop phone or softphone as their operator device, and call control must work.

If your organization uses Cisco phones that don’t support CTI (Computer Telephony Integration), for example Cisco 3905, call control will not work, in which case you can't use this method.

When you use this method to initiate an outgoing call, the following events will occur:

  1. The Zylinc solution checks if the e-mail address specified in the user parameter can be mapped to a desktop phone or softphone. If that’s not the case, the method will fail.
  2. The Zylinc solution uses its Cisco User Proxy or BroadWorks User Proxy to initiate a connection directly to the phone or softphone. If a connection can't be established, the method will fail.
  3. The Zylinc solution uses the connection to send an instruction to the phone or softphone to initiate an outgoing call to the phone number specified in the target parameter.

URL: http://<Windows application server>:8080/ClientManager/dial?user={user}&target={target}&type=phone

Method: GET

Query Parameters:

  • user: The e-mail address of a Zylinc user who uses a Cisco or BroadWorks desktop phone (or softphone) that supports call control. For example, a user of Zylinc Employee Assistant (previously known as Operator).
  • target: The phone number to call. If the number contains a + character, and you use the method from within a hyperlink, substitute the + character with %2B. If you use the method from a HTML form, don't substitute; the web browser will take care of the substitution.
  • type: phone

Example URL for method 2

Instruct the phone or softphone that belongs to agent@email.domain to initiate an outgoing call to phone number +4512345678

http://<Windows application server>:8080/ClientManager/dial?user=agent@email.domain&target=%2B4512345678&type=phone

If you're going to demonstrate the click to dial concept, or if you need to create a prototype for a third-party integration that uses click to dial, you can easily set up an HTML page to use as a working prototype or for concept demonstration.

When you open the HTML page in a browser, you’ll see buttons and links that'll call a specified phone number from a specified agent's phone device.

  1. In a folder on your computer, for example on your desktop, create a new text file.

  2. In Windows explorer, in the View ribbon, in the Show/hide section, make sure that File name extensions is selected.

  3. Rename the file to Click-to-dial-demo.htm

  4. Open Click-to-dial-demo.htm in Notepad or a similar text editor

  5. Copy the HTML code from this file Click-to-dial-HTML-code-example.txt to the text editor window.

  6. In the text editor, use the search and replace function to replace all instances of the following texts:

    • Replace winappserver.domain.local:8080 with the hostname or IP address of your Zylinc Windows Application Server, and the port number for the HTTP connector of the Tomcat instance, for example: winappserver:8080

    • Replace administrator@zylinc.com with the e-mail address of the agent you want to use click to dial for

      For method 1, the agent must be logged in to a Zylinc client for the function to work.

    • Replace 4512345678 with the phone number that you want to call.

      The %2B in the beginning of the number inside the hyperlink represents a URL encoded + character. If you don’t need the + prefix, remove %2B or + from the beginning of the number. This if useful if you want to use an internal phone number, or if you need another prefix than a + character, for example 00.

      If you use an HTML form, the web browser will automatically encode + to %2B.

      If you use a hyperlink, you must manually replace any + characters with %2B.

  7. Save the file.

  1. In a browser, open the HTML page.
  2. Make sure that the agent is logged in to a Zylinc client.
  3. For method 1, test that the button and the link work. A call should be initiated when you click the button or link.

To test method 2, the user doesn’t need to be an agent, and doesn’t need to be logged in to a Zylinc client. However, method 2 requires that the user uses either a BroadWorks or a Cisco desktop phone or softphone, and that call control is supported.

If that’s the case, you can test method 2:

  1. For method 2, test that the button and the link work. A call should be initiated when you click the button or link.

To use the API methods that initiate a transfer of an active call, you’ll need to know the system ID (zytag) of the active call that you want to transfer, and which queue, agent, or phone number that you want to transfer to.

You’ll also need the e-mail address of the agent (agentemail) that currently handles the call.

For the third-party system to become aware of the values of the zytag and agentemail parameters, so that it can pass them to the API, you can set up a call lookup that passes the parameters from Zylinc to the third-party system.

You can view how to set up such a call lookup in the example in the following. However, before that, we’ll describe the functions of the API that transfers the agent’s active call.

The methods require that the user is currently logged in to a Zylinc client as an agent. Because of that, a Zylinc license that supports agents and voice queues must be available to the user.

For ZyDesk, the user can be logged in with one of the following profiles: Attendant Console, Contact Center, or Service Center.

Other Zylinc client types will also work, as long as the user is logged in as an agent, and the client type supports voice queues. For example, the user can log in as a voice queue member (clientless login) or log in to Zylinc Mobile as an agent.

This method transfers the active call of an agent to a specific voice queue.

Parameters

URL: http://<windows application server>:8080/ClientManager/dial?user={user}&zytag={zytag}&target={voice_queue_name}&type=queuetransfer

Method: GET

Query parameters:

  • user: E-mail address of the agent that currently handles the call. To get that parameter, see the call lookup example in the following.
  • zytag: The system ID (zytag) of the call. To get that parameter, see the call lookup example in the following.
  • target: The name of the voice queue that you want to transfer the call to. Keep in mind that queue names for this purpose are case sensitive.
  • type: Specify queuetransfer as the value for this parameter

Example URL

Transfer the active call, for which we know that the zytag is mediaserver-1540543819.113 and the e-mail address of the agent who currently handles the call is test@email.domain, to the voice queue with the (case sensitive) name TestQueue1000:

http://<Windows application server>:8080/ClientManager/dial?user=test@email.domain&zytag=mediaserver-1540543819.113&target=TestQueue1000&type=queuetransfer

This method transfers the active call of an agent to another specific agent.

Parameters

URL: http://<windows application server>:8080/ClientManager/dial?user={user}&zytag={zytag} &target={target}&type=agenttransfer

Method: GET

Query parameters:

  • user: E-mail address of the agent who currently handles the call. To get that parameter, see the call-lookup example in the following.
  • zytag: The system ID (zytag) of the call. To get that parameter, see the call-lookup example in the following.
  • target: The e-mail address of the other agent to transfer the call to.
  • type: Specify agenttransfer as the value for this parameter

Example URL

Transfer the active call, for which we know that the zytag is mediaserver-1540543819.113 and the e-mail address of the agent who currently handles the call is test@email.domain, to another agent with the e-mail address otheragent@email.domain:

http://<Windows application server>:8080/ClientManager/dial?user=test@email.domain&zytag=mediaserver-1540543819.113&target=otheragent@email.domain&type=agenttransfer

This method transfers the active call of an agent to an internal or external phone number.

Parameters

URL: http://<Windows application server>:8080/ClientManager/dial?user={user}&zytag={zytag}&target={phonenumber}&type=transfer

Method: GET

Query parameters:

  • user: E-mail address of the agent that currently handles the call. To get that parameter, see the call lookup example in the following.
  • zytag: Tthe system id (zytag) of the call. To get that parameter, see the call lookup example in the following.
  • target: The internal or external phone number to transfer the call to. If the number contains a + char, and you use the method from within a hyperlink, substitute the + char with %2B. If you use the method from a HTML form, don't substitute; the web browser will take care of the substitution.
  • type: Specify transfer as the value for this parameter

Example URL

Transfer the active call, for which we know that the zytag is mediaserver-1540543819.113 and the e-mail address of the agent who currently handles the call is test@email.domain, to the phone number +4512345678:

http://<Windows application server>:8080/ClientManager/dial?user=test@email.domain&zytag=mediaserver-1540543819.113&target=%2B4512345678&type=transfer

If you are going to demonstrate the click to transfer concept, or if you need to create a prototype for a third-party integration that uses click to transfer, you can easily set up a JavaServer Pages (JSP) web page on one of your existing Tomcat instances within the Zylinc solution to use as a working prototype, or for concept demonstration.

When an agent answers a call, the JSP web page opens in the agent’s web browser, and in the browser the agent can use buttons and links to transfer the active call to a queue, another agent, or an internal or external phone number.

  1. On the Windows application server, locate the webapps\root folder of the Tomcat instance for port 8080, for example: C:\Program Files\Zylinc\ApacheInstances\ZyTomcat1-8080-8443\webapps\ROOT

  2. In Windows explorer, in the View ribbon, in the Show/hide section, make sure that File name extensions is selected.

  3. In the webapps\ROOT folder, create a new text file and rename it to third-party.jsp

  4. Open third-party.jsp in Notepad or a similar text editor.

  5. Copy the JSP code from this file Click-to-transfer-JSP-code-example.txt to the text editor window.

  6. In the text editor, use the search and replace function to replace all instances of the following texts:

    • Replace winappserver.domain.local:8080 with the hostname or IP address of your Zylinc Windows Application Server, and the port number for the HTTP connector of the Tomcat instance, for example: winappserver:8080

    • Replace TestQueue1000 with the name of the queue that you want to transfer the call to, and keep in mind that queue names for this purpose are case sensitive.

    • Replace administrator@zylinc.com with the e-mail address of the agent you want to transfer to.

      The agent must be logged in to a Zylinc client for the function to work.

    • Replace 4512345678 with the phone number that you want to transfer the call to.

      The %2B in the beginning of the number inside the hyperlink represents an URL encoded + sign. If you don’t need the + prefix, remove %2B or + from the beginning of the number. This if useful if you want to use an internal phone number, or if you need another prefix than a + character, for example 00.

      If you use an HTML form, the web browser will automatically encode + to %2B.

      If you use a hyperlink, you must manually replace any + characters with %2B.

  7. Save the file.

  1. In a browser, open an URL like: http://winappserver.domain.local:8080/third-party.jsp?zytag=TESTZYTAG&agentemail=test@email.domain&target=%2B4512345678

    Replace winappserver.domain.local:8080 with the hostname or IP address of your Zylinc Windows Application Server, and the port number for the HTTP connector of the Tomcat instance, for example: winappserver:8080

  2. In the browser window you should see a text like:

    This server-side JSP script has received the following parameters from your Call-Lookup:

    zytag = TESTZYTAG
    agentemail = test@email.domain
    target = +4512345678

To use the API methods that initiate a transfer of an active call, you’ll need to know the system ID (zytag) of the active call that you want to transfer, and which queue, agent, or phone number that you want to transfer to.

You’ll also need the e-mail address of the agent (agentemail) that currently handles the call.

To get the zytag and agentemail parameters, you can set up a call lookup that's automatically activated when the agent answers a call.

The call lookup opens a new browser window within the agent’s user session and passes the two parameters $zytag$ and $agentemail$ from the Zylinc client to the third-party system as query parameters within the URL.

The agent can now use the (web based) third-party system in the new browser window, and the third-party system can now, for example make use of command buttons or links that transfer the agent’s active call to a specific queue, another specific agent, or to a predefined phone number.

If the third-party system isn’t web based, you can use other methods, for example, Command (Windows executable) or Custom DLL call, to pass the parameters. When that's the case, you don’t need to open a browser window, but the concept of passing the zytag and agentemail parameters remains the same. For more information, see Invoke third-party systems and pass parameters (CRM lookup).

  1. In the Administration Portal menu, select INSTALL > Portal Configuration

  2. Make sure that Call Lookup and Queue Advanced are selected

  3. In the Administration Portal menu, select SYSTEM > Call-Lookup

  4. In Configuration Name, enter a name for the call lookup configuration, for example: Pass parameters to third-party.jsp

  5. In Method, select Link Call

  6. In Call Answer/ Click, enter http://winappserver.domain.local:8080/third-party.jsp?zytag=$zytag$&agentemail=$agentemail$&optional-numeric-code-entered-on-callers-phone-keypad=$ivrdigits$

    Replace winappserver.domain.local:8080 with the hostname or IP address of your Zylinc Windows Application Server, and the port number for the HTTP connector of the Tomcat instance, for example: winappserver:8080

  7. Click Save

  1. In the Administration Portal, select QUEUES > Voice Queues

  2. Click the queue that you want to use the concept of click to transfer for

  3. Click ADVANCED (in the top-right corner)

  4. In Call Lookup, select the Call-Lookup you previously created (for example: Pass parameters to third-party.jsp)

  5. Normally it is not necessary to restart any backend services, but if you make changes to the parameters within an existing call lookup, you may need to restart Client Manager (or the Tomcat service that hosts Client Manager) for the changes to become active

    To avoid restart of Client Manager, you can create a new call lookup with a new name, instead of making changes to the parameters of an existing call lookup.

  1. If ZyDesk is running, close the program
  2. Log in to ZyDesk as an administrator
  3. In the ZyDesk menu, select File > Settings
  4. In Interface > Switch > Lookup, select Automatically perform lookup on incoming call
  5. Click Apply
  6. Right-click Interface > Switch > Lookup, and select Access level > Administrator
  7. Right-click Interface > Switch > Lookup, and select Configuration level > Database
  8. Click OK
  9. Close ZyDesk
  1. Log in to ZyDesk as an agent
  2. From a phone that doesn't belong to the agent, for example a mobile phone, make a call to the voice queue that you previously set up to use the call lookup
  3. When the agent answers the incoming call, a new browser window should open, and all the buttons and links to transfer the call should work