Asterisk IP telephony

The module is designed to configure integration with the Asterisk telephony provider. It allows you to receive and make calls in the BRIX interface. Users can identify clients by phone number, open the page of a related app (such as a deal or lead) during a call, and listen to call recordings.

Начало внимание

This module is available only for BRIX On-Premises. Integration can be configured with Asterisk telephony version 12 and higher.

Конец внимание

Step 1. Activate the BRIX Platform license

To get access to all telephony features provided in BRIX, activate the BRIX platform license before setting up the integration.

This allows you to apply advanced settings for call pages and call summary pages (forms with additional customer data that you can view during a call). In addition, users can use the Telephony workspace, which provides a dedicated page for logging and managing calls.

To learn more about the available features, see Telephony.

Step 2. Configure settings on the Asterisk side

Начало примечание

Note

This article outlines the main steps for configuring the Asterisk server. For questions related to telephony provider configuration, contact Asterisk technical support or use the official documentation.

Конец примечание

1. On the Asterisk side, enable the ARI and AMI interfaces. They are required for the module to function correctly.

Enable the ARI interface

Enable the AMI interface

2. Determine and configure one of the methods for employees to handle outbound calls:

• Third-party softphone. A special application for making calls, such as MicroSip, which is configured at employee workstations and connected to your Asterisk server.
• CTI Panel. A tool for making outgoing and internal calls in the BRIX interface. In this case, installing an additional softphone is not required.

Step 3. Connect the Asterisk module in BRIX

1. Go to Administration > Modules.
2. Click + Module and upload the module file provided by your BRIX rep.
3. Click Go to Module. On the page that opens, perform the following actions:

• Configure the connection to the Asterisk server.
• Configure the CTI panel.
• Map Asterisk users to BRIX users.
• Configure incoming call processing.
• Use diagnostic tools.

Configure the connection to the Asterisk server

To receive data from Asterisk, specify the connection parameters in the module. You can find them in the Asterisk server settings in the ari.conf and manager.conf files.

1. Open the module connection page and fill in the fields on the Settings tab:

• Cloud PBX Address*. Specify the full URL or API address of the server where Asterisk is located.
• User*. Enter the user login specified in the ari.conf file.
• ARI Port*. Enter the port specified in the ARI interface settings. It is indicated in the ari.conf file. Port 8088 is typically used.
• Password*. Enter the user password specified in the ari.conf file.
• Cloud PBX Application*. Add a custom application name, for example, brix. The application will be used as a context that combines all settings, channels, and events for operation within a single connection.
• Channel Type*. Specify the protocol used by the channel: SIP, PJSIP, DAHDI, or IAX2. The channel type is determined during Asterisk configuration.
• AMI User*. Enter the user login specified in the manager.conf file.
• AMI Password*. Enter the user password specified in the manager.conf file.
• AMI Port*. Enter the port specified in the manager.conf file. Port 5038 is typically used.
• Outbound call context. Specify the name of the context, i.e., the set of extensions that determine the rules for making outgoing calls. The context is configured on the Asterisk server.
• Call recording link. Enter the direct link template for retrieving conversation recording files from the Asterisk database. The URL is specified in the IP telephony provider server settings. To create the template, click Substitution variables below the Call recording link field and use the channel parameters generated during the call. The template may look as follows: https://record_{Id}_{Name}_{Creationtime}_{Creationtime.DayOfWeek}.wav;
• Call ID. When a call is received, a search is performed for an item in the app specified in the incoming call processing settings. By default, the phone number is used: if there is a match, the item page opens automatically, and call data is recorded in it.

You can configure the search by another parameter transmitted by Asterisk along with the call, such as the call ID or caller name. To do this, map an Asterisk variable to a string property from the related app.

Below the Call ID field, click Substitution variables and select an Asterisk variable, such as {Id} or {Caller.Name}. Then proceed to incoming call processing settings, specify the app, and fill in the Field for linkig by selecting a property of the String type.

After configuration, the required item will be identified by matching the variable values in Asterisk with the property of the related app item.

2. After filling in the fields, click Set Service Settings to display calls in the BRIX interface, and click Save above the Telephony Settings block.
3. Go to the Advanced Settings tab and specify the following parameters:

• Fill webhook link automatically. By default, the Webhook URL field value is specified in the Webhook link* field.

To enter a different address where Asterisk event data will be sent, select No in the Fill webhook link automatically field;

• Variable for storing the operator extension number. This field is populated if your Asterisk configuration cannot automatically determine the operator number during a call. For example, in the configuration settings within the call processing script, you specified a special variable where the operator number is recorded during the call:

same => n,Set(OPERATOR_EXT=${…}) 
// The variable records the extension number that received the call

To ensure correct transmission and storage of operator data in BRIX, specify this variable in the field.

• Connect to ARI via a secure connection. Select Yes if you need to encrypt data transmission between BRIX and Asterisk ARI using the HTTPS and WSS protocols. Then click Configure Asterisk to Support a Secure ARI Connection and follow the steps in the opened instructions.
• Connect to AMI via a secure connection. Select Yes if you need to encrypt data transmission between BRIX and Asterisk AMI using the TLS protocol. Then click Configure Asterisk to Support a Secure AMI Connection and follow the steps in the opened instructions.
• Ignore TLS certificate verification errors . Select Yes to connect services regardless of any errors that may occur during certificate verification.
• Root certificates. Specify certificates in .pem format for correct connection verification.

4. Click Set Service Settings and save the settings.
5. In the Telephony Settings block:

• The Token and Webhook URL fields are populated automatically. This is service data used for the correct operation of the module.
• Click Check Connection. If the connection between Asterisk and BRIX is established, you will see a notification about it.

6. Click Save.

Configure the CTI panel for telephony

To allow users to make outgoing and internal calls in the BRIX interface without using an external softphone, configure the CTI panel. To do this:

1. First, configure WebRTC on the Asterisk side and obtain the URL for connecting to telephony from BRIX.
2. Return to BRIX. On the module settings page, go to the CTI panel tab and fill in the fields:

• SIP Over WebSocket URL. Enter the link obtained in the previous step.
• Logging level*. Select which browser telephony operation messages to display in the developer console: Off, Errors, Warnings, Information, or Debug.

To ensure a stable telephony connection under any network conditions, configure the settings on the STUN or TURN server side. After that, fill in the following fields in BRIX:

• ICE transport policy*. Select which type of network candidates will be used to establish the connection:
  • All candidates (all). Direct connections, STUN server candidates, and candidates relayed through the TURN server are allowed. You can select this option if there are no network restrictions blocking traffic.
  • Relay only (relay). Only TURN server candidates are allowed. Select this option if all traffic must pass through an intermediary server, such as under strict network restrictions.
• ICE servers. Add the server data that can be used by the ICE agent to establish a connection between VoIP devices to the table:
  • Server type*. Select the required value: STUN if you need to determine the client's external IP address to establish a direct connection, or TURN if a direct connection between devices is unavailable. In this case, voice traffic will pass through the TURN server.
  • Host*. Specify the domain name or IP address of the STUN or TURN server.
  • Port*. Enter the port specified in the STUN or TURN server settings.
  • Login, Password. These fields are populated if TURN is selected in the Server type* field. The data is used for authorization on the TURN server.
  • Add Google public STUN server to table. This button is located below the table. Click it to add Google's STUN server to the table. It will be used to determine the user's public IP address for sending voice traffic.

3. Click Set service settings to apply the changes.

After saving the CTI panel settings, you need to map employees who handle calls in the company to extension numbers.

Map users

Once the connection with the provider is established, specify the employees who will be able to handle calls. To do this, map internal telephony users to BRIX users:

1. In the Telephony settings block, click Configure.
2. The opened window displays the IP telephony provider's extension numbers loaded automatically. If this data is not displayed in the User settings window, make sure that users are created on the provider side.

To the right of the extension number, click the gear icon and fill in the fields in the appearing window:

• BRIX365 user*. Select an employee from the list who will handle calls.
• Connect CTI panel*. If you selected the CTI panel as the method for employees to handle telephony, select Yes.
• Login*, Password*. These appear if Yes is selected in the previous field. Specify the user's credentials in the telephony provider's system.

3. Save the settings.

Now information about employees and their assigned extension numbers is transmitted correctly. Such users can enable the CTI panel in their profile to make calls in the BRIX interface.

Configure incoming call processing

After connecting the telephony provider, configure incoming call processing:

1. in the Administration > Call Settings section, you can configure advanced settings for incoming, outgoing, and missed call cards, as well as call summary cards. These settings can be applied to all connected telephony modules. For details, see Customize the call page.
2. If you do not use advanced telephony settings and want to set individual call processing parameters in the Asterisk module, open its management page. On the Settings tab at the bottom of the page, go to the Incoming Call Processing Settings block and fill in the fields:
   

• Link to app*. Specify the app where items with customer and call information will be created and stored. Note that the selected app form must contain a Phone number type field.
• Contact phone number*. Select a Phone number type field from the specified app context where the client's phone number will be recorded. By default, the search for the item related to the call is performed using this field. If the incoming number matches the value in the field, the required page opens.
• Link field. If you need to search for an item not by phone number, but by another parameter transmitted by Asterisk along with the call, fill in this field. Specify a String type property from the context of the app selected above.

To ensure the search is performed correctly, the app's string property must be mapped to an Asterisk variable. To do this, specify an Asterisk variable (such as {Id} or {Caller.Name}) in the Call ID field when configuring the connection to the provider.

When a call arrives, the value from Asterisk will be compared with the value of the selected property in the Communication field, and if they match, the required item will open.

• Disable item creation. Select Yes to disable the automatic creation of a contact after a call ends. In this case, unnecessary records will not be added to the contact database app specified in the Link to app* field.

• Call page. Click the Configure button to change the appearance of the pop-up notification during a call. In the window that opens, you can edit the page title template and select the fields to display in it.

After configuring all integration parameters, click Save.

Use diagnostic tools

If errors occur while the Asterisk module is running, you can use the integration connection diagnostic tools.

To do this, open the module settings page and go to the Diagnostics tab:

1. Notification recipients. Specify the users who will receive notifications if errors occur during the operation of the Asterisk module.
2. Logging level. Configure receiving messages about the module's operational status:

• In the Category* column, list the microservice categories for which you want to track errors. Category names will appear in the error list in square brackets.
• In the Logging level* column, select the error message type for each microservice: Trace, Debug, Information, Warning, Error, Critical. For more details on the types, see the official Microsoft documentation.
   
  If the table is not filled in, you will receive error messages of the Warning, Critical, and Error types across all microservices.

3. View Logs. Click the button to open a window listing the last 200 records on the module's operation status. Each logging level in the list uses its own color designation:

• Trace and Debug. Gray color.
• Information. Blue color.
• Warning. Yellow color.
• Error and Critical. Red color.

4. Test Service Settings. Click the button to verify that the settings on the BRIX side have been applied to the Asterisk service. If errors are detected, a notification is displayed in the window below the button.
5. Check Asterisk Connection Status. Click the button to check the connection setup with the IP telephony provider. The test result is displayed in the window below the button.
    
   If a connection error is displayed, check:

• The correctness of the specified values for the ARI interface in the general module settings.
• The availability of the Asterisk server at the link specified in the Cloud PBX Address* field.

Troubleshooting

The table below lists errors that may occur during the configuration and operation of the module.