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:

../../_images/third_party_pane.png

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).

../../_images/third_party_workflow.png

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":4,
        "agentId":1,
        "firstName":"James",
        "lastName":"Bond",
        "fullName":"James Bond"
    },
    "callee":"1000",
    "caller":"1001",
    "queue":{
        "id":2,
        "name":"trucks",
        "displayName":"Trucks",
        "number":"3001"
    },
    "userData":{
        "XIVO_CONTEXT":"default",
        "XIVO_USERID":"2",
        "XIVO_SRCNUM":"1001",
        "XIVO_DSTNUM":"3001"
    }
}
  • user contains the connected user information
  • callee contains the number called
  • queue queue properties
  • 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,
    "title":"Third Party Sample"
}

or:

{
    "action":"none"
}
  • action is one of "open" or "none"
  • 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.
  • 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.
  • 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);
})();