Structure

The module's interface is divided into three levels:

General settings: Registration Data, Handlers, and Advanced panels. The first level displays general integration status and reports critical errors that affect integration performance.
Routing: Inbound Destinations and Outbound Routes panels. The second level is responsible for creating routing elements intended for use in other FreePBX modules.
Additional settings: Lines, Tasks, Exceptions panels. The third level settings are not mandatory, but they add some more functionality to the routing elements.

The user notification system exists in two forms:

Graphic — colour highlights of the panels indicate the level of importance.

	Red — critical error, the integration does not work.
	Yellow — warning, this or that integration element does not work.
	Grey — element is not set up, it is not an error.
	Blue — errors or warnings are not detected.
	Green — module registration is complete.

Text — highlighting of incorrectly filled fields plus error description (in many cases it includes recommendations on how to correct it).

Hints and help:

In the top left corner there is a link to the general module documentation.

Most of the settings have hints with description.

All images in this manual are clickable (to enlarge the image, just click on the pic).

System requirements

From	Where	Port	Protocol
FreePBX	license.informunity.ru	443	https
FreePBX	“Bitrix24 address”:address	“Bitrix24 address”:port	http/https
FreePBX	oauth.bitrix.info	443	https
license.informunity.ru	FreePBX	“FreePBX address”:port	http/https
license.informunity.ru	“Bitrix24 address”:address	“Bitrix24 address”:port	http/https

FreePBX server must have continuous access to license.informunity.ru:443.
FreePBX server must have continuous access to Bitrix24 portal, which address is indicated in "Bitrix24 address" field.
license.informunity.ru must have recurring (once a day) access to 443 port via FQDN address of Bitrix24 portal.
FreePBX server must be permanently available via address, indicated in the "FreePBX address" field for license.informunity.ru (34.252.155.135; 195.201.40.10).

If FreePBX is behind NAT, it is required to do call forwarding.

Example for Linux-iptables boundary Firewall:

External address of boundary Firewall: 177.177.177.177

Internal address of FreePBX server: 10.0.4.2

In the module settings it is required to set the following:

In Firewall settings configure the following:

iptables -t nat -A PREROUTING -i eth0 -s 34.252.155.135/32 -p tcp -d 177.177.177.177/32 --dport 80 -j DNAT --to-destination 10.0.4.2:80

Note: while setting the ports redirection, do not give access to all your addresses.

General module settings

1. Module installation in FreePBX

To install the module, go to FreePBX control panel → Module Administration and choose Upload Modules:

Enter module’s URL https://license.informunity.ru/asterisk/iub24.tar.gz and click Download:

Click on the pic to enlarge the image

Follow the link Local module administration or Manage local modules. Select module Informunity Bitrix24 in the Admin section, choose Install and Process. After that select "confirm" and wait for the end of installation. Press Return.

Next, press Apply Config.

2. Registration Data

Before the registration, we recommend to set up a special user account (for example, PBX) with administrator rights and proceed the registration process on behalf of this account. As a result, you avoid two problems:

A priori the entities in Bitrix24 are created in the name of the user who registered the module. Using a separate account helps to avoid the mix up while creating and changing the entities.
The user whose account is used for module registration must have the administrator rights for CRM, Tasks, Open lines, Users, Telephony, Disk, Chat, and notifications. If the rights are changed, the module can stop working correctly. In order to avoid this, we recommend creating a separate user account with all listed rights.

Before registration make sure that the Integration with Asterisk app is installed in your Bitrix24.

To start the registration process go to Admin → Informunity Bitrix24. You will see the Registration data panel highlighted with red. Click on the panel.

In the pop-up window enter the address of your Bitrix24 and the external address of your FreePBX. To complete the process, click Register.

Bitrix24 address — it is the address of your Bitrix24 portal. To ensure that the module works correctly, give access for the license.informunity.ru server and use the domain name or the real IP address.

FreePBX address — it is the external address of the FreePBX server. This address will be used by license.informunity.ru to initialize the Click to Call function.

After clicking on the registration button, you will see a pop-up window in the left bottom corner. There you will see the app’s code. Enter the code to the Access Code field highlighted with red and click Register.

*If instead of the app's code you see the request to register your Bitrix24, first register the portal (and make sure to do it using the name of the user who you aspire to register the Integration to) and then proceed with the actions listed above.

If all the settings have been implemented correctly, the Registration Data panel will be highlighted with green.

As a result, you should see the following data at the registration panel:

The app's payment status — indicates the type of your license (paid or demo);
License active till — shows the date up till which the license is active;
Users with extensions — specifies the number of Bitrix24 users that are assigned with the internal number in Bitrix24 settings.

3. Handlers

At the Handlers panel you can check the status of the Click to Call and Call Back handlers.

Click to Call allows making requests to the PBX for placing a call. With the Click to Call handler, the call will come first to the internal number, and then, when the phone pen is picked up, it will be sent to the destination user.

Call Back allows making requests for a callback from the site widget.

To register a handler, click Register (see the screenshot below, line "Click to Call"). The process is carried out automatically, the only thing you need to do is to wait for the pop-up message Complete.

If the handler is already registered and you want to check its status, follow the Registered link (see the screenshot above, line "Call Back"). In the pop-up window, you will see a list of handlers currently registered at the portal. The handlers might have been created while installing a previous module version or any other application that uses the same handlers.

A green check mark next to a handler means that the integration uses this particular handler. You may want to delete all other handlers — it will speed up the interaction between Bitrix24 and PBX. Ideally, you should keep only one handler marked with the green check.

Auto Answer Click to Call — if Yes, the call will be automatically picked up on the extension. (This setting works only with the hardware that supports auto-answer function when receiving a specific SIP-header.)

Call Back Destination — destination for the callback from the site widget. For example, the call can be directed to a queue or to an IVR. Initially, you can select only the default destination. After setting the lines, you will be able to assign each line with a particular destination.

4. Advanced

At the Advanced panel, you can find settings related to the overall module's functioning.

Softphone24 Settings — allows checking whether the PBX settings meet the requirements for the Softphone24 extension to work correctly. It also permits setting the external port for WSS (this parameter is obligatory for filling in). If after clicking the Check button you see an error message, please refer to your FreePBX general settings.

Clear Cache — allows clearing cache in Asterisk. Having changed the telephony settings on the side of the Bitrix24 portal, it is necessary to clear the cache in the integration module. Click the Clear Cache button and wait for the message Complete. The cache is cleared automatically once a day.

Download log — here you can choose and download a log file from the server. If you use the standard FreePBX distro, the full file contains the log for the current day, while files with dates in their names contain the logs for the day previous to the indicated date.

Request Timeout, sec. — lets you set the maximum time that the module takes to wait after sending a request to Bitrix24 and/or to the license server. If requests to the portal do not return results by timeout, the first thing to do is to check the response time of the DNS-server that it takes when converting the name to an IP. Or you can register your Bitrix24 address and license.informunity.ru to /etc/hosts. The maximum possible value of this field is set only in case of an extremely slow network connection.

Recordings — choose the format of the recordings sent to Bitrix24 portal. Bitrix24 supports only mp3 and wav, all other formats will be attached and available for download.

MP3 — convert wav to mp3 and transmit records to Bitrix24.
FreePBX Format — transmit records in the format that is set in the general FreePBX settings.
Don't Attach Records — don't transmit records.
Stereo — the record is not related to the FreePBX settings. The client's voice goes to channel #1, the operator's voice goes to channel #2.

Links to records — allows automatically adding links to call records from FreePBX to the entity description. If you do not see the Yes option, it means that it is not possible to add links given the chosen records format.

Identify the region for Russia — allows changing the Lead's or Contact's address by phone number. This option works only on the territory of the Russian Federation.

Routing

5. Inbound Destinations

This panel allows creating dial plan elements that later can be used as destinations in other modules and FreePBX routes. To register the incoming calls in Bitrix24, you need not only to configure the elements, but also to include them in the incoming routes.

To add a routing element, click Add in the upper left corner of the panel. Make all necessary settings in the pop-up window.

Description — set the destination name.

Use for IVR — this setting expands the capabilities of the Direct Dial function set for the standard IVR and allows registering calls to extensions. To set it up, select one or several IVRs that you want to enable this setting for. In this case, the Destination for Registered Callers and Destination settings do not apply. If a call is routed to an extension from the Exceptions list, it will not be registered.

Default User — set the manager who will be responsible for all calls at the moment of their coming. If the call is not taken, the Default User becomes responsible for it. If the call is taken, the responsible person for it is the last person to speak with the client.

Call Registration Priority — Set a successive priority that will guide choosing a CRM entity for registering the info about calls. If the field says Default, the entities are selected following the default scenario set by Bitrix24. By setting your sequence, you abandon the default scenario.

How it works. Say, you want to attach the info about calls to the Contact entity, provided the caller's number has already been registered in one or more CRM entities.

By setting the priority Contact → Company → Lead, you set the following scenario:

First, the integration module asks Bitrix24 for a list of entities to which the caller's number is attached.
Then, if the Contact is in the list, the information about the call is attached to the Contact.
If there is no Contact, the call is attached to the Company.
If there is no Company, the call is attached to the Lead.
If the Lead is absent as well, the system creates a new Lead following the standard scenario.

Since by canceling the default logic inherent in Bitrix24, we increase the number of requests made to look for the needed entity, the time the client spends waiting on the line may slightly increase.

Exceptions — select a list of users that do not get assigned with calls and do not receive pop-up call cards (to configure the list, please see the Exceptions panel).

Show Caller Name — select Yes if you want the name of the Lead or Contact to be displayed on the phone/softphone at the moment of the call.

Add to chat — here you can choose which calls are to be displayed in the chat list: no calls at all, only unanswered, or all calls.

Assign to Unanswered Call — select who will be made responsible for a missed call, if a lead, contact or deal with the number is already registered in CRM: Default User or Assigned Manager. If there is no lead, contact or deal with such a phone number in CRM, the call will be registered to the Default User.

Create Task On Unanswered Call — here you can select a template of the task to be set in case of a missed call. If you do not want to set a task, leave Disabled. (You can configure task templates at the Tasks panel.)

Show Card — select Yes to display the card in Bitrix24 at the moment of the call.

Create Lead — select Yes to create a lead or a deal at the moment of the call in case there is no registered lead, contact, or deal with this phone number in CRM.

Source — specify the source of the call from the Bitrix24 directory. The list of sources is configured in Bitrix24 itself. You can use this option to identify various ad campaigns in case you use different phone numbers. (The source is assigned once — when creating a lead or a deal.)

Destination for registered callers — here you can specify the destination for the clients already registered in CRM. This setting works only if there is a lead, contact, or deal with the indicated phone number in CRM. Otherwise, the setting is ignored.

* If you select Assigned Manager, you can specify either Extension or Extension & Mobile. If Extension, the incoming call will be directed to the manager who is responsible for the lead or contact with the current extension. If Extension & Mobile, after an attempt to dial the extension, the call will be redirected to the responsible manager's mobile phone.

Ring Time — the time period during which Asterisk will make attempts to reach the manager. If you select Extension & Mobile, the setting is triggered for each call: first, Asterisk will call the extension number for 15 seconds, then to the mobile phone number for the exact same time.

* If you select a queue, a group call, or an IVR, the call will not return to the destination indicated for this route, but it will go to the Failover Destination.

Assessment — if Yes, upon the end of the call, the client will be offered to assess the quality of service (from 0 to 5).

Initial message — voice greeting before assessment.

Final message — voice message after assessment.

Destination — destination for the call after its registration in Bitrix24.

When everything is set, click Submit.

Also, at the Inbound Destination panel you can:

go to the FreePBX settings by clicking on the corresponding element in the column Used as destination in;
go to the settings of the element specified in the column Destination.

Also, you can edit or delete the created item.

If none of the elements is connected to other modules or routes in FreePBX (the section Used as Destination is empty), the panel will be highlighted with yellow.

6. Outbound Routes

This panel displays existing outbound routes. To register outgoing calls in Bitrix24, you need to activate the integration on the desired route. On routes marked as Intra-Company, the integration is activated automatically, and calls coming to this route are considered internal.

To activate an outgoing route, click Edit in the Actions section (the Delete button is used to reset the integration settings on this route).

The settings window will pop up.

Description — unchangeable field.

Status (Enabled / Disabled / Assessment ) — allows you to enable the integration / disable the integration / enable the integration with the subsequent assessment on the current outgoing route.

How it works. Say, you want to attach the info about calls to the Contact entity, provided the caller's number has already been registered in one or more CRM entities.

By setting the priority Contact → Company → Lead, you set the following scenario:

First, the integration module asks Bitrix24 for a list of entities to which the caller's number is attached.
Then, if the Contact is in the list, the information about the call is attached to the Contact.
If there is no Contact, the call is attached to the Company.
If there is no Company, the call is attached to the Lead.
If the Lead is absent as well, the system creates a new Lead following the standard scenario.

Since by canceling the default logic inherent in Bitrix24, we increase the number of requests made to look for the needed entity, the time the client spends waiting on the line may slightly increase.

Exceptions — select a list of users that do not get assigned with calls and do not receive pop-up call cards (to configure the list, please see the Exceptions panel). Employees from the Exceptions list will not have rights to register the call.

Show Card — select Yes to display the card in Bitrix24 when making a call.

Create Lead — select Yes to create a lead or a deal when making a call in case there is no registered lead, contact, or deal with this phone number in CRM.

Advanced Settings:

For the integration to work properly with the portal, you should set inbound and outbound CallerID's in the same format, for example, 74995556677. Please note that Bitrix24 accept symbols such as "+", ")", "-".

For inbound calls, you can use a third party module, for example, "Set CallerID".

Number Modification for Bitrix24 — modifications of the number that is transferred to Bitrix24. It does not affect the call routing. Modifications are made in the same way as with Asterisk variables.

Add number: 4955555555 -> 8${DAIL_NUMBER} -> 74955555555

Delete number: 0984955555555 -> ${DAIL_NUMBER:2} -> 74955555555

https://wiki.asterisk.org/wiki/display/AST/Selecting+Characters+from+Variables

Upon configuration click Submit.

If you click on the name of the route at the Outbound Routes panel, you will go to the settings section of the corresponding route in FreePBX.

7. Registration Upon The Call

Registration upon the call allows you to configure transferring data to Bitrix24 right during the conversation by pressing the key combination "*3". The combination can be edited in the control menu, Feature Codes.

Status (Enabled / Disabled / Assessment ) — allows you to enable the integration / disable the integration / enable the integration with the subsequent assessment on the current outgoing route.

How it works. Say, you want to attach the info about calls to the Contact entity, provided the caller's number has already been registered in one or more CRM entities.

By setting the priority Contact → Company → Lead, you set the following scenario:

First, the integration module asks Bitrix24 for a list of entities to which the caller's number is attached.
Then, if the Contact is in the list, the information about the call is attached to the Contact.
If there is no Contact, the call is attached to the Company.
If there is no Company, the call is attached to the Lead.
If the Lead is absent as well, the system creates a new Lead following the standard scenario.

Since by canceling the default logic inherent in Bitrix24, we increase the number of requests made to look for the needed entity, the time the client spends waiting on the line may slightly increase.

Show Card — select Yes to display the card in Bitrix24 when making a call.

Create Lead — select Yes to create a lead or a deal when making a call in case there is no registered lead, contact, or deal with this phone number in CRM.

Additional settings

8. Lines

Line is a phone number displayed in Bitrix24. It is used to determine destinations for outgoing calls. Also, it is used in end-to-end analytics for call tracking set up.

To add a line, click Add at the Lines panel.

DID — enter the DID that receives a call. This parameter can be identified in the incoming call log (variable FROM_DID).

Number — enter the line number that will be displayed in Bitrix24 telephony and end-to-end analytics.

Outbound Prefix — in order to make a call from Bitrix24 through a certain line, you need to specify the prefix in dial patterns of the corresponding route in the outgoing routing and specify the same prefix in the Outbound Prefix field.

The Used in section at the Lines panel displays which outgoing route uses this line’s prefix.

9. Tasks

The templates are used to assign a task to a person responsible for a lead or a contact in case they missed a call.

You can customize templates for each incoming route.

To add a task template click Add at the Tasks panel.

Task Name — name of the task that will be displayed at the task card.

Observers — people you wish to observe the task.

Deadline — time limit for the task execution set in hours/days.

Task templates are selected in the Inbound Destinations settings.

The column Used in on the Tasks panel indicates which elements of the Inbound Destinations use the current template.

10. Exceptions

At this panel, you can create groups of employees that later can be chosen as exceptions so that their members do not participate in the module's work. It means that they will not get assigned with calls and will not receive pop-up call cards.

To add a group of exceptions click Add. It will open the pop-up settings window.

Description — enter the name of the group. Only you will see it.

Members — select group members from the drop-down list.

The Used in column indicates which integration module uses this list.

11. Bitrix24 settings

Make sure to specify the extension numbers for the telephony users. To do it, go to the telephony settings:

Telephony → Telephony users

Click on the three lines to the left of the user name, select Settings and enter the extension corresponding to the PBX number. For Click to Call to work correctly, the default number for outgoing calls should be Application: Integration with Asterisk

Also, you can set the default number in the general telephony settings:

As a default number can be tied with a particular line. Make sure to create it beforehand at the Lines panel.

In the screencast below, you can find the whole process of module installation and configuration, as well as some basic demonstration of the app's work. To see the detailed lineup, click on the title of the video and go to the first comment underneath.

12. Softphone configuration

To execute calls a softphone or a deskphone is required. Here are some options of the free softphones: Zoiper, MicroSIP, Bria.

A softphone is a software program for making telephone calls over the Internet using a general purpose computer rather than dedicated hardware.

To set up a softphone/deskphone the following data is required: FreePBX domain, your extension number, password. These credentials can be found on FreePBX. Go to Applications – Extensions – Press Edit icon and get the password from the Secret field.

Download an application and follow the setup proposed by the chosen softphone. Here is an example for Zoiper:

Then press NEXT-SKIP. Your SIP UDP should be marked as found. The configuration is finished.

Here is an example for MicroSIP: