¶ Developing with EasyConnect
¶ Introduction
EasyConnect allows for a quick and seamless integration of the innovaphone PBX in your application using well known standards and protocols available in any low-code or development environment
Its main features are:
- the Administration REST API to get, update and delete objects from your own applications or automations;
- the Remote Call Control (RCC) REST API for controlling calls via the REST API from your own (web) application;
- the Contacts REST API to manage your contacts from your own middleware solution;
- the PBX REST API to gather information on the PBX;
- the Users REST API to manage users’ profile pictures;
- the configurable webhook to monitor calls.
Developers get to develop to a stateless REST interface instead of a stateful web socket, and are able to monitor users through a webhook using either the GET or POST HTTP method. This allows for easier integration with common low-code solutions like Salesforce Lightning or Microsoft Power Apps.
¶ REST APIs Documentation
Developers have access to the OpenAPI specification of our APIs via Swagger UI from inside the EasyConnect app.
Swagger UI allows developers to test the API without having to write a single line of code.
To access Swagger UI and test some API calls, follow these steps:
- Open the EasyConnect app
- Click on API Docs
- Click on Authorize
- Enter one of the configured API keys
- Click on Authorize
- Click on Close
- You are now authorized and can try out API calls
Open your browser and go to https://swagger.io/tools/swagger-ui/ to learn more about Swagger UI.
Alternatively, developers can download the OpenAPI specs of the EasyConnect API by appending swagger/api.yaml to the App URL.
The App URL can be found in the EasyConnect service settings.
Follow these steps to find out what your App URL is:
- Open the AP Manager app
- Open the EasyConnect app
- Click Instances > Edit
- You’ll find the App URL at the bottom
¶ Consuming the REST APIs
Consuming the REST APIs is easy.
All you need to do, is find the API call you need and pass one of the API keys configured in the EasyConnect settings along as the apikey query parameter.
As described in the previous section, the API documentation can be found in the EasyConnect app, or can be download as an OpenAPI spec file. All information required for to make a call is in that documentation.
¶ Monitor Users through a Webhook
To monitor a user, make sure it is a member of the group of which the EasyConnect app is an active member (see “EasyConnect Group" on page Configuration).
As soon as webhooks are enabled, the webhook URL is invoked when a monitored user makes or receives a call.
When the Webhook request type is set to POST, the event arrives as a JSON object and when it set to GET all event information is passed via query parameters.
There is a slight difference between the values passed in the JSON object and in the query parameters for Booleans. The JSON object makes use of true or false, while the query parameter uses the string ‘yes’ or ‘no’.
The following table gives more information on the WebHookEvent’s JSON object and can be used to understand the query parameters, with a slight difference for the Boolean values as described earlier.
Description of WebHookEvent JSON object properties:
| Property | Description | Example |
|---|---|---|
| CallId | A string that represents a unique call identifier. This ID is used when making requests to the RCC API. To disconnect a call for example. |
1ea84350-ef40-49c4-a3cd-b1d59c821b47
|
| conferenceEvents | An array containing conference events. There are different kinds of conference events. The events have different properties based on the type of event. This could be used in niche cases where the from field would is altered due to a redirect. The conference event would contain the original from number. |
See “Example WebHookEvent JSON object” above |
| conferenceId | A string that represents a conference identifier. The innovaphone conference ID is the ID used by innovaphone to link call legs to one another. |
577193ccf44465016826009033600110 |
| connected |
A Boolean that represents the connection status of the call. One of [true, false] This flag in combination with the status gives more context to the call. For example, when receiving a disconnected event (an event where the status is set to ‘disconnected’) with connected set to false, you can deduce this call is in fact a ‘missed call’. We know this to be true because a ringing event’s connected flag will always be false, and a connected event’s connected flag will always be true. |
false |
| conversationTime | A number that represents the duration of the conversation in seconds. This property is set to -1 when the call is ringing or when the call did not get connected. |
-1 |
| endTime | A string that represents the timestamp of the call disconnecting. The datetime format is: ‘YYYY-MM-DD hh:mm:ss (UTC)’. This property can be null. |
null |
| from | A string that represents the extension number or phone number of the source user. | ‘00472591687’ |
| fromName | A string that represents the name of the source user. Can be an empty string when the name is not known. |
‘’ |
| monitoredExtension | A string that represents the extension number of the monitored user. The monitored user can either be the source (from) or the destination (to) user. Events for a monitored source user (outgoing call) include: connected and disconnected. Events for a monitored destination user (incoming call) include: ringing, connected and disconnected. |
‘42’ |
| monitioredUser | A string that represents the name of the monitored user. Can be an empty string when the name is not known. |
‘Thomas De Wilde’ |
| outgoing |
A Boolean that represents whether the call is an outgoing call. One of [true, false] |
false |
| pickupTime | A string that represents the timestamp at which the destination user connected to the call. The datetime format is: ‘YYYY-MM-DD hh:mm:ss (UTC)’. This property can be null. |
null |
| startTime | A string that represents the timestamp of the start of the call. The datetime format is: ‘YYYY-MM-DD hh:mm:ss (UTC)’. |
‘2022-09-16 11:57:43 (UTC)’ |
| status | A string that represents the type of event. One of [‘ringing’, ‘connected’, ‘disconnected’] |
‘ringing’ |
| to | A string that represents the extension number or phone number of the destination user. | ‘42’ |
| toName | A string that represents the name of the destination user. Can be an empty string when the name is not known. |
‘Thomas De Wilde’ |
| totalTime | A number that represents the total time this call took in seconds. This property can be -1. |
-1 |
To illustrate the power of simplicity that comes with the webhook event, we’ll go over the events that are triggered for an ‘incoming missed call’.
As is clear from Figure 3 - Timings and Durations of a WebhookEvent, EasyConnect is elegantly simple by sending just three distinct webhook events: ringing, connected and disconnected.
The first event sent for an incoming call for a monitored user is the ringing event. This event indicates that someone initiated a call. The connected property of a ringing event will always be set to false, because there’s no connection yet between source (from) and destination (to).
The second and final event for a missed call is the disconnected event. To know if the call is a missed call, developers need to verify the connected flag of a disconnected event. When it is set to false, the call is a missed call. When it is set to true, the call went through. We know this to be true because the only time the connected property is set to true, is when the connected event is triggered.
Alternatively to identify a call as being a missed call, one could check the conversation time, but a Boolean flag usually is easier to implement and reads better.
If the monitored user would have picked up the call, a third Webhook event would have been sent. The ‘connected’ event indicates that a connection is established between source and destination.
See Figure 5 - Example Webhook JSON data for incoming call for an example of Webhook events of a picked up call.
¶ Connecting mobile numbers
This use case uses the RCC API (which requires the EasyConnect group to be setup) to connect two mobile numbers via a waiting queue.
First, you create a new waiting queue object. In this use case, it’s called the DialoutQueue and has number 77. Make sure you have an audio file, here we use the default music on hold of the PBX, and make sure to set the alert timeout to 0.
Setting the alert timeout to 0 is very important.
Make sure that your waiting queue object is monitored by the EasyConnect app just like any other user extension by adding it to the EasyConnect group (here EasyConnectMonitored).
With the waiting queue setup, we can now use EasyConnect’s RCC makecall functionality to call a number. This can be either an internal or external number.
The ‘from’ number must be the waiting queue’s number, here 77 and ‘to’ is set to the call extension 50. If this succeeds, the phone will start ringing and you can pickup and will hear the music on hold. We will need the call ID represented by a GUID this rest request later.
Repeat this for another number, here we make a call from 77 to a mobile number. Again, keep track of its call ID.
Next, we use the RCC API to transfer the call using the two GUIDs. With this call, the two numbers should now be connected.
Some side notes and disclaimers:
- During the testing of this use case an external extension and a mobile number was used. But, it should work with two mobile numbers as well.
- This is not a “complete” or “clean” implementation. It’s not certain that a transfer if the calls are not connected yet, but it is doubtful. Best to check whether the calls are connected both before calling the transfer function. You can monitor the status of these calls using EasyConnect’s webhook functionality. Since the waiting queue object is monitored, the webhook will give you updates with the same call IDs. You can check whether the outbound calls are connected, and, as soon as they are, the transfer function can be invoked.
- There might be other settings interfering with this process in innovaphone.
This use case was tested on a cloud PBX and worked fine with a properly configured waiting queue. - Number formatting will probably have to be adjusted to your own situation (leading zeroes, etc.).
¶ Previous chapter