General recommendations and rules

Owned by Ilya Titaev
Last updated: Feb 09, 2024
3 min read

 

 

This article provides general recommendations and rules to follow when writing an integration with a VOIP platform system.

The process of connecting an integration by a user is an automated process that should be understandable to the user without the need for additional assistance.

Typically, widgets (applications) are available in CRM through which a user can connect integration with a telephony platform.

When selecting the required widget (application), the CRM itself informs the user about the steps needed to perform the integration, or the integrator independently carries out the integration process without the user's participation, having obtained the user's authorization data.

Defining Basic Integration Parameters

Integration must understand which extension numbers belong to regular phone extensions and which to service extensions (IVR and Queue).

This information can be obtained by requesting it, for example, with the resource:

get /client/{client_id}/extension/ (type field link to documentation).

The PBX prefix and extension length can be learned using the resource:

get /client/{client_id}/client/ (extension_len and prefix fields link to documentation)

The user's extension number with the PBX prefix has the format of a regular expression (regex):

[0-9]{3,6}*[0-9]{2,4}

Events on Extensions

For all regular phone extensions (type = phone), it is recommended to add a full set of events:

  • dial-in - incoming call to the extension

  • dial-out - outgoing call from the extension

  • answer - picking up the handset on the extension (this event may be irrelevant in some integrations)

  • hangup - ending the call on the extension

In this recommendation, it is recommended to add only the hangup event for special extensions (type = IVR or queue).

Documentation of extension events.

Documentation of queue agent events (these events are necessary to display the readiness of the queue agent to take a call - can be used in real-time monitoring)

Adding/Removing Events on Extensions

To maintain an up-to-date list of events on extensions, it is recommended to send requests for adding/removing events when the integration settings administrator specifies/changes the correspondence of users to their extension numbers. It is not allowed to delete or update events not related to this integration, as the user may have several other active integrations.

The number of events on one extension according to standard allowances is 16. Therefore, if it is impossible to add an event, the user should be informed so that they can either delete unused events on the extension or send a request to the PBX administrator to extend the event limit on extensions.

API Request Rule:

No more than one request for one action should be made, if an error was received during the previous attempt to make a request, it means something went wrong and the request should only be repeated after some actions have been taken.

4xx errors mean that something needs to be changed or some actions need to be taken, more about 4xx errors can be read in the documentation.

API errors - 5xx series. These errors should be sent to the administrator for appropriate action.

Re-sending a request should be initiated only by the user (when the user initiates a request), or after a certain time (for automatic requests), but in no case in an infinite loop. The user should learn about the error in a corresponding notification.

The number of API requests per hour is also limited, so it is undesirable to unnecessarily update/synchronize anything. Documentation on limits.

 

Event Example (recommended URL)

The event URL can be as follows:

http://myintegration.com:8080/cid/807/queue/33334

where

  • 807 - the serial number of the Ucom4B application for this integration. This number can be used later to filter all events related to this user in the integration server log.

  • queue - the type of extension on which the event URL is set. Allows for easy separation of events of different types of extensions (phone or queue or IVR)

  • 33334 - the extension id, simplifies event analysis

However, from a security standpoint, it is better not to create such URLs in commonly used integrations. By guessing the client_id and ext_id, it is possible to spam other users with events. It is recommended to specify such a URL:

http://myintegration.com/ext-event/f2a8vdrfae0s1ku5d2rj3iximjf3twyz

Where:

  • ext-event - event type

  • f2a8vdrfae0s1ku5d2rj3iximjf3twyz - a unique identifier that unequivocally corresponds to the extension record in your integration's extension table

Filtering Events Received from the PBX

Familiarize yourself with the description, particularly the "EventData" section

If you only want to log external calls (to/from an external number), you need to exclude from processing:

Events related to calls from extension to extension:

  • In the CallerNum field: The extension number in the format [0-9]{3,6}*[0-9]{2,4}

  • In the CalledNum field: The extension number in the format [0-9]{3,6}*[0-9]{2,4}

Events related to internal call forwarding:

  • In the Transfered field: "yes"

  • The field CalledExtensionID with a numeric ID is present

  • The field CallerExtensionID with a numeric ID is present