API for computer-telephony integration services

In traditional telephony, a call is the connection between the SIP and/or PSTN handsets. To control such a call (e.g., to transfer it), a user must have the phone and remember the hotkeys for the action.

CTI (Computer-telephony integration) technology enables users to control calls programmatically, by using external applications (e.g., web-based switchboard, CRM, mobile dialing app, etc.). Thus, a user can:

• Make, answer or terminate calls both within your network and off-net ones;
• Transfer the call to another destination;
• Retrieve the list of active calls for an individual phone line or for the whole PBX environment;
• Receive notifications about call state changes.

To make this happen, CTI applications communicate with PortaSwitch via the call control API. This is an interface to a call, which allows users to manage it without a phone, from a web application. For example, a user can start a call from a CRM computer application and check the list of active calls for a certain group of users, etc.

Using call control API and other PortaBilling API methods (e.g., to retrieve customer information), CSPs can build their own applications (web based switchboard or mobile dialing app) and embed voice communications into existing ones (e.g., add click-to-dial service to the CRM system). Thus, they improve the user experience and optimize the call processing workflow for customers. For example, a call center operator who mainly uses a web-based switchboard and headset is fully engaged in a call with a customer.

The switchboard can notify the operator about new calls and provide options for how to control them (e.g., transfer or place in a queue). In this scenario, the operator does not have to use a phone or remember the hotkeys for call management.

Below are several usage examples of call control API.

You can provide the ability to operate with custom IVR applications via the call control API. This functionality is of special interest to call centers, since it permits them to develop their own IVR applications that include specific features (e.g., auto attendant to track the status of the parcel). In this manner they can introduce their own call processing flow, therefore improving customer interaction. The IVR application communicates with PortaSwitch via the API and can be implemented in any programming language.

Consider the following example.

Your customer, a visa processing center, wants to automate the process of providing their users with relevant information such as their visa application status. To make this happen, they implement an IVR application in Java and store it on their external server. The application can gather user inputs and retrieve the necessary information from the visa center’s database. To participate in call processing, the application connects to PortaSwitch via the API, requests the access number (e.g., 1733355700) and subscribes to call state notifications for that access number.

When Mary Smith calls 1733355700 to check her visa application status, the following occurs:

• PortaSwitch matches the access number (1733355700) and notifies the customer’s IVR application about the call.
• The IVR application sends an API request to PortaSwitch with the instruction to answer the call and provide the path to the prompts.
• PortaSwitch answers the call and plays a prompt for Mary to enter her registration number, etc.
• PortaSwitch collects Mary’s input and sends it to the IVR application via the API.
• The IVR application retrieves the data from the external database and sends the API request to PortaSwitch to inform Mary that her visa is approved.

This feature enables your customers to implement their own IVR applications in the programming language of their choice.

Thus, they can manage incoming calls and automate their workflow. Your benefit comes from being more competitive in the marketplace and extending your customer base.

To enable the use of a custom IVR application, a PortaSwitch administrator needs to do the following:

• Create an IVR application of the User Application type.

• Allocate access numbers to that application.
• Enable the User application option for the IVR owner account, either explicitly or within the product configuration.

The IVR application owner needs to:

• Develop an IVR application that communicates with PortaSwitch via the API.
• Add an access number to the application.
• Subscribe the application to call state notifications for the access number.

This emulates the endpoint redirection functionality for applications so that calls redirect to a predefined number – as if from an IP phone.

This functionality is useful to call centers that use external applications to monitor and control incoming calls to their agents. The external application can track an agent’s status (e.g., available, busy, etc.) and send the redirect command if necessary.

When PortaSwitch receives the application’s command, it redirects the agent’s incoming calls to another phone number (e.g., a call queue number).

You can program web/mobile applications to trigger callback calls to user phones and automatically connect them with the desired destination via the call control API. PortaSwitch establishes two outgoing calls (e.g., to PSTN numbers) and then bridges them together. The party to pay for this call is the account registered in the application for the API.

For example, for your customer "Quick & Tasty" bistro you can integrate their voice call service with their web application. So when customer Alice opens the application and decides to reserve a table, all she needs to do is enter her phone number and click the Call button. She immediately receives a call back on her phone. Once she answers, she is connected with the bistro. The "Quick & Tasty" account in PortaSwitch is predefined for the application and is the one that pays for the call.

The call control API includes methods that enable an operator to receive notifications regarding call events via an external application. Thus, the operator has a clear overview of all calls arriving to a call queue and can efficiently manage it.

When a new incoming call is placed in a queue, the system sends the queued event. Once the call is sent to an agent or the caller leaves the queue, the system sends a dequeued event. Based on these events, the operator has an overall statistic for calls connected with agents and those waiting in queue.

You can develop an app (e.g., a switchboard app) to provide intelligent conferencing services with PortaSIP as the IMS TAS and Call control API. Users can turn active calls into conferences on the fly. They can also leave the conference call and let the conversation continue among the remaining participants. Users manage conferences via the switchboard app that communicates with PortaSwitch via the call control API.

For example, Alice can check the app to see if Bob and John are available before adding them to her active call with Peter. Then, when she leaves the conference call, the remaining participants continue the conversation. This allows you to facilitate business calling services and enable your PBX customers to manage calls efficiently.

The external application you develop must be able to receive call state notifications for your users to create and manage conferences.

Thus, users have the options to:

• turn an active call into a conference call;
• manage a conference by adding and removing participants, muting them and/or putting them on hold during the call;
• leave the conference while other participants continue the conversation;
• join another active conference in “listen only” mode, have a private talk with its moderator and/or drop in this conference call;
• browse the list of active conferences in a Mobile PBX environment as well as the list of participants for the conference, both those who are still active and those who left.

The user who converts an active call into a conference call automatically becomes its owner and is therefore the one who pays for the conferencing service.

To illustrate how it works in detail, consider this example: Alice, Bob and Carol are sales managers of your business customer EasyMobile. Peter is EasyMobile’s client and is subscribed to another mobile operator. The call takes place in the mobile network; therefore, all communication passes via the CSCF.

1. Peter calls Alice. PortaSIP successfully processes the terminating triggering call to Alice and routes it to the CSCF. The CSCF delivers the call to Alice and she and Peter begin the conversation (1).
2. Alice decides to involve her colleagues, Bob and Carol, to jointly discuss the matter. She opens the switchboard app and checks their availability.
3. Both Bob and Carol are available, so Alice adds them to her call with Peter and specifies the name of the call in the app.
4. The app sends the API request to the PortaBilling web server, which passes it on to PortaSIP (2).
5. PortaSIP authorizes Alice for the conferencing service in PortaBilling. PortaBilling verifies that Alice’s service configuration includes the conferencing service and instructs PortaSIP to create a conference room with the name she specified. Alice is the conference owner.
6. PortaSIP renegotiates the media session parameters between Alice and Peter. They both hear an invitation to the conference (3).
7. The app sends the API request to the PortaBilling web server to add Bob to the call (4).
8. PortaSIP sends the terminating triggering call to Bob via the CSCF (5). Bob answers and is now in the conference.
9. In the same way, Carol is also added to the conference (6).
10. Since Alice has another scheduled call,  she hangs up a few minutes later. However, the call among Bob, Carol, and Peter continues.
11. Eventually, all call participants hang up and PortaSIP removes the conference.
12. PortaBilling charges the call participants as follows:
    • As the conference owner, Alice is charged for the time spent by each participant, herself included, in the conference call. Thus, four xDRs for the conferencing service are created for Alice.
    • Alice is also charged for the incoming call from Peter plus the outgoing calls to Bob and Carol. Thus, three xDRs for voice calls service are created for Alice, too.
    • Bob and Carol are charged for the incoming calls.

1. You can provide conferencing services via the Call control API on any network, VoIP and /or mobile. Likewise, SIP, PSTN, and mobile users can participate in conference calls.
2. To provide conferencing services in IMS networks you must meet these criteria:
   • Your host MNO must have a 4G network core and support VoLTE;
   • You must integrate PortaSIP as a TAS (Telephone Application Server) in the IMS core;
   • You must develop or extend your application (a mobile dialing app, a CRM or a switchboard console) to communicate with PortaSwitch via the call control API.
3. When an API session is established under the account realm, the user who creates the conference automatically becomes its owner and is the one who manages this conference. When an API session is established under a customer realm, the user has access to all of the conferences in the Mobile PBX environment and can appoint another account as the conference owner. A conference owner is the one charged for the conferencing service.
4. You can use your custom prompts for a conference by specifying the path to them in the API request. Supported file formats are au and g729.

The call control API is accessible via WebSockets. WebSocket connections are processed by workers. Each worker can process up to 100 concurrent connections. The actual maximum number of connections possible, however, depends upon the capacity and general configuration of the Apache server.

By default, the WebSocket server sends a heartbeat ping message every 20 seconds to each worker to verify that it is alive. If the worker is overloaded (e.g., receives 500 requests per minute), it responds with a delay. Then the WebSocket server kills this worker. To increase the time interval for the heartbeat response, define a new value (in seconds) for the custom [WebSocket]HeartbeatTimeout option on the Configuration server.

Another feature of a WebSocket connection is its inactivity timeout – the period after which the connection automatically closes. To support a Websocket connection, define some value, e.g., 300 seconds, for the [API]WebSocketInactivityTimeout option on the Configuration server, and make sure that your application can call the ping method to renew the session.

The internal communication between the web server and PortaSIP is performed via the HTTP and Redis protocols, therefore, for real-time notifications of call state changes, the Redis instance must be configured on the Configuration server.

If your installation consists of several sites (e.g., the main and secondary site), the call control API requests are sent to the processing nodes of the site that the PortaAdmin node belongs to.

By default, only administrators and reseller users have access to the call control API. To access the API from retail customer and account realms, modify their access roles by setting the access permission for the Call control component as Modify.