Third Party Integration

Third party web application integration is possible inside the XucMgt Agent application. Upon each call, you can display a custom panel next to the agent interface:

Workflow

When a call is ringing on the agent phone, the Application will call the external web service (see Configuration below). The web service response will dictate the behaviour of the integration. For example, if the speficied action is to open the application when the call is hung up, a new panel will be created and opened inside the agent interface, showing the content specified by the web service response. (see Web Service API for available options).

When the work is complete in the integrated application, the application must post a message to terminate the third party application pane inside the agent application (see Completion).

Configuration

You need to specify the third party application web service url to integrate this application inside the XucMgt Agent interface. This can be done by giving a value to the THIRD_PARTY_URL environment variable in the /etc/docker/compose/custom.env file

...
THIRD_PARTY_URL=http://some.url.com/ws/endpoint

The speficied URL must be accessible from the client browser (i.e. the end user of the Agent application). The call wil be made from his browser.

Web Service API

The Web Service url specified in the :Configuration must conforms to the following behaviour.

The service will receive a POST request with a payload as application/json, for example:

{
  "user": {
    "userId": 54,
    "agentId": 29,
    "firstName": "James",
    "lastName": "Bond",
    "fullName": "James Bond",
    "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJsb2dpbiI6Im13ZWJydGMiLCJleHBpcmVzQXQiOjE3MjQ3NjY5NzAsImlzc3VlZEF0IjoxNzI0NzYzMzcwLCJ1c2VyVHlwZSI6ImN0aSIsImFjbHMiOlsiYWxpYXMuY3RpdXNlciJdLCJzb2Z0d2FyZVR5cGUiOiJ3ZWJCcm93c2VyIn0.EdKGjpNnV19BnQCiVXAiAfUEfirmZ6WvQhBDtEV6pQ4"
  },
  "callee": "1023",
  "caller": "1013",
  "userData": {
    "XIVO_USERID": "54",
    "SIPCALLID": "fd32a3a3-9647-457e-be04-16d7d408f271",
    "USR_XIVO_DSTNUM": "3001"
  },
  "callDataCallId": "1724763376.29",
  "queue": {
    "id": 2,
    "name": "edition",
    "displayName": "Edition",
    "number": "3001"
  }
}

user contains the connected user information
callee contains the number called
queue queue properties
callDataCallId contains the linkedId of the call
userData call data presented by Xivo

The Web service must answer with an application/json content. For example:

{
      "action": "open",
      "event": "EventReleased",
      "url": "/thirdparty/open/6bd37819-b4a6-43d3-8fa3-6eb6489bb705",
      "autopause": true,
      "autopauseReason": "backoffice",
      "title": "Third Party Sample"
}

or:

{
      "action":"none"
}

action is one of
- open: Will open the given url inside the integration pane
- popup: Will open the given url in a popup
- run: Will run the given url as an executable, only works in desktop assistant.
- none: No action will be performed
event is one of EventRinging, EventEstablished, EventReleased. The third party application will be opened when one the specified event occurs
url should be the url to open inside the application. This url should point to a valid web application that can be specific for each call.
executableArgs can contain an array of argument for the run action.
autopause if set to true, the agent will be put on pause when the application pane is opened and back to ready when the application is completed.
autopauseReason an optional field allowing to set the type of the pause used while setting the agent on pause (see the line above).
multitab if set to true and action is set to popup, then the integration will be opened a in new popup window (or tab) each time instead of reusing the same window (or tab).
title will set the title of the tabs that will be opened.

Warning, when the XucMgt application and the integrated application are on different server, domain, url,… (which should be common case), You may get CORS errors. To workaround this issue, you should implement the OPTIONS request on your web service. This method will be called by the browser before issuing the POST request to ensure the target web server allows calls from the original application. You application must set at least the following headers in order to overcome the CORS errors:

Access-Control-Allow-Origin: * or the domain hosting the XucMgt application
Access-Control-Allow-Methods: POST, OPTIONS (at least)
Access-Control-Allow-Headers: Origin, X-Requested-With, Content-Type, Accept (at least)

Completion

Once the work is complete inside the third party application, it should post a completion message (closeThirdParty) to the application using the Web Messaging API.

For example, here is how to define a close method in javascript to send the message to the hosting application and bind it to a simple button:

(function () {
      function close() {
          parent.window.postMessage("closeThirdParty", "*");
      }

      document.getElementById("close").addEventListener("click", close, false);
})();

Third Party Login URL Integration

To know on which XiVO a user is logged, you can configure a URL with some information about the user when they log in the application.

Configuration

You need to specify the third party application web service url to integrate this application inside the XucMgt Assistant and Agent interfaces. This can be done by giving a value to the THIRD_PARTY_LOGIN_URL environment variable in the /etc/docker/compose/custom.env file

...
THIRD_PARTY_LOGIN_URL=https://some.url.com/logininfo?login=%{login}&token=%{token}&xivoccHost=%{xivocchost}

The service will receive the url containing the username, token and XiVOCC host of the user who just logged in.