Introduction

The Autoprovisioning Plug & Play (PnP) technology is supported by many well-known phone manufacturers, such as Yealink and Snom. With the MikoPBX automatic phone setup module, you can quickly configure compatible phones, making them ready for use in the system. This greatly simplifies both the initial configuration and the ongoing support of phones in the office.

Key Benefits of Automatic Phone Setup

• Simplifies initial setup – no need to connect to each phone's web interface for configuration. Instead, simply enter the device’s MAC address and assign it an account on the auto-setup server.

• Eases support – centralized management of device settings makes it easy to adjust configurations for multiple phones from a single location.

• Convenience for end users – in some cases, phones can be set up by dialing a short code, like *911*<SIP_ACC>. This is especially helpful for non-technical users who can configure the device themselves with a simple number combination.

Network Requirements for the Auto-Setup Module

• The auto-setup module operates only within a local network.

• Multicast requests to IP 224.0.1.75 must be allowed on the network.

• Currently, only a single general registration address can be set for all devices.

• Ports for the MikoPBX web interface (HTTP) and SIP (80 and 5060) must be open.

• HTTPS is not supported in this version.

• No other PnP servers should be running on the network since devices will accept settings from the first responding server.

Supported Phone Models

Yealink Models

• Yealink T19(P)

• Yealink T28(P)

• Yealink W52

• Yealink WP530

Snom Models

• Snom D120

• Snom D785

• Snom D735

• Snom D715

• Snom D385

• Snom D335

Fanvil Models

• Fanvil X5U

• Fanvil X3SP

• Fanvil X1SP

We are working to expand the range of supported phone models.

Setting Up the Auto-Setup Module

Installing the Auto-Setup Module

1. Open the Modules -> Module Marketplace section.

2. Install the Automatic Phone Setup Module.

Note: Start the module only after completing all necessary settings.

Configuring Module Parameters

After installing the module, open the settings page.

• Extension Template – enter the extension number to use for quick phone setup via star code.

• Server Registration Address – enter the IP address or domain of your MikoPBX server. Phones will connect to MikoPBX using this address.

• Blacklist of MAC Addresses – enter MAC addresses of phones not to be set up. This allows you to exclude certain devices from auto-setup. The blacklist takes priority over the whitelist.

• Whitelist of MAC Addresses – enter MAC addresses of phones that are authorized for auto-setup. If neither the blacklist nor the whitelist is specified, the module will attempt to configure all connected phones.

Additional Configuration Parameters for Phones

In the Additional Parameters field, you can enter custom settings that will be added to phone configuration files. Here are examples for each supported model.

Configuration Example for Yealink Phones

By default, the server generates the following basic configuration file for Yealink phones:

#!version:1.0.0.1
account.1.enable = 1
account.1.label = Askozia (204)
account.1.display_name = 204
account.1.auth_name = 204
account.1.user_name = 204
account.1.password = 1c9709222690713dd
account.1.sip_server_host = 172.16.156.223
account.1.sip_server_port = 5060
account.1.transport = 0
account.1.codec.1.enable = 1
account.1.codec.1.payload_type = PCMU
account.1.codec.1.priority = 1
account.1.codec.1.rtpmap = 0
account.1.cid_source = 4
voice_mail.number.1 = *001
phone_setting.lcd_logo.mode=0
auto_provision.dhcp_option.enable = 0
features.intercom.allow = 1
features.intercom.mute = 0
features.intercom.tone = 1
features.intercom.barge = 1
features.dtmf.transfer = ##
features.dtmf.replace_tran = 1
features.headset_prior = 1
features.intercom.allow = 1

To add extra parameters, use the [yealink] section in the Additional Parameters field. For example:

[yealink]
features.headset_prior = 1
features.intercom.allow = 1

Each new parameter should be specified on a separate line.

Configuration Example for Snom Phones

The configuration file for Snom phones has a more complex XML structure. For example:

<?xml version="1.0" encoding="utf-8"?>
<settings>
    <time_24_format perm="R">off</time_24_format>
    <phone-settings>
        <user_pname idx="1" perm="RW">203</user_pname>
        <user_name idx="1" perm="RW">203</user_name>
        <user_realname idx="1" perm="RW">Irina Smirnova</user_realname>
        <user_pass idx="1" perm="RW">3256157a99f176eb959ef9c1fdd947f0</user_pass>
        <user_host idx="1" perm="RW">172.16.32.225</user_host>
        <user_srtp idx="1" perm="RW">off</user_srtp>
        <user_mailbox idx="1" perm="RW">*001</user_mailbox>
    </phone-settings>
</settings>

To add data in the <settings> node, use the [snom] section, and for the <phone-settings> node, use [snom-phone-settings].

Configuration Example for Fanvil Phones

Fanvil configuration files consist of separate modules. Here is an example of a basic configuration:

<<VOIP CONFIG FILE>>Version:2.0002
PNP Enable         :0
<SIP CONFIG MODULE>
SIP1 Enable Reg    :1
SIP1 Phone Number  :203
SIP1 Display Name  :Irina Smirnova
SIP1 Register Addr :172.16.156.223
SIP1 Register Port :5060
SIP1 Register User :203
SIP1 Register Pswd :3256157a99f176eb959ef9c1fdd947f0

You can add extra parameters using the sections [fanvil], [fanvil-sip], [fanvil-tele], and [fanvil-autoupdate].

Troubleshooting

Troubleshooting Yealink Phones

The first thing to check is whether your firmware version is up-to-date. Update the firmware if necessary from the Yealink support site.

1. Access the device’s web interface and navigate to Settings → Configuration.

2. Set the log level to the maximum value of 6.

3. Reboot the device and export the log.

In the downloaded log file, pay attention to errors, for instance:

LIBD[528]: HTTP<5+notice> URL : 
LIBD[528]: HTTP<3+error > Connect Error
AUTP[528]: AUTP<3+error > http to file failed, code = -3, msg = Connect Failed, cout = 0

If you see Connect Error, it means the phone was unable to download the configuration file from the server.

Назначение

• Разграничение прав доступа к исходящим маршрутам

• Установка caller id для исходящего вызова

Настройка модуля

1. Выполните установку модуля в разделе Управление модулями.

2. Включите модуль и зайдите в его настройки.

3. На основной странице модуля отображается список существующих групп. Сейчас он пустой.

3. На вкладке Cотрудники отображается список всех сотрудников и то, к какой группе они принадлежат. Сейчас они сотрудники не принадлежат ни к какой группе, потому что самих групп еще не создано.

4. Для добавления новой группы нажмите Создать группу сотрудников.

5. На вкладке Настройки группы укажите ее имя и описание**.** Затем нажмите Сохранить.

6. Вы перейдете на вкладку Сотрудники группы. Добавьте в группу необходимых сотрудников.

7. Перейдите на вкладку Правила исходящей маршрутизации и активируйте разрешенные маршруты.

Возможные сценарии использования

Разрешить сотруднику только внутренние вызовы

1. Создайте новую группу Только внутренние (название группы может быть любым).

2. На вкладке Сотрудники группы заполните список сотрудников.

3. На вкладке Правила исходящей маршрутизации отключите все маршруты.

Запретить сотруднику международные направления

Настройка выполняется аналогично примеру Разрешить сотруднику только внутренние вызовы с тем лишь отличием, что следует запретить только международные маршруты.

Персональный маршрут для каждого сотрудника

Для каждого сотрудника создайте отдельную группу. Укажите разрешенный маршрут.

Свой caller id для каждого маршрута

На вкладке Правила исходящей маршрутизации укажите CallerID для каждого маршрута.

Group Isolation

This feature allows for the isolation of a group of employees on the PBX:

1. Employees within the group can only call numbers within their own group

2. Employees from other groups will not be able to call the isolated group

Number templates related to the group. A group member will be able to call only these numbers

1. The templates may include digits from 1 to 9 and the symbol X (any digit 1-9)

2. A group member will be able to dial all numbers that match the template

Examples of templates:

• 2XX - numbers from 200 to 299

• 200001 - a specific internal number, such as a queue number

• 7XXXXXXXXXX - 11-digit numbers for Russia

Additionally, the module allows for authentication in MikoPBX using external LDAP/AD services or simply assigning a login and password to each employee.

The module also adds a new tab to the employee settings page, allowing for quick assignment of access groups or password changes directly from their profile card.

Let's consider a few common scenarios for MikoPBX access control:

Scenario 1: Access for Multiple Administrators

1. Create an access group and enable the Group without access restrictions toggle.

2. Choose the home page that administrators will land on after authentication.

Next, navigate to the "Users" tab of the access group and select the employees who will be granted permission to administer the system.

Scenario 2: Access Limited to IVR Menu Administration

Create an access group with restricted privileges that grants access only to IVR menu administration.

Next, go to the Setting permissions tab and select only the necessary rights to view and modify existing IVR menus.

Assign the access group to employees who will administer the IVR menus and save the access group.

Scenario 3: Access to Call History with User Filtering

Create an access group, disable full privileges, and grant access only to the call history section with user filtering.

When selecting this section, an additional tab appears in the module settings, allowing you to configure permissions for viewing and listening to call recordings on a per-employee basis.

You can select various filtering options and employees whose call recordings can be listened to by users within this access group.

LDAP Authorization Configuration

The module allows users to be authenticated either with a simple login-password pair or by using an external LDAP authentication server. To configure the connection with the server, navigate to the "Domain Authorization Settings" tab.

Please provide the access parameters to your domain. If necessary, specify the parameters for the organizational unit and the filter for user accounts. Before saving, you can perform a connection data check and retrieve a list of users from the server.

At the end, you can enter user credentials to test the authorization and save the module settings.

Designed to simplify the process of obtaining an SSL certificate for HTTPS. System requirements:

1. The PBX must have a dedicated domain, for example, sip.test.ru.

2. The web interface of the PBX must be accessible on the internet (at the time of obtaining the SSL certificate).

3. The flag "This station is behind a NAT router" must be activated on the PBX.

4. The "External Host Name of Your Router" must be configured on the PBX. Refer to the

5. Disable the "Redirect to HTTPS" option in the general settings. The Lets Encrypt server verifies the resource by making an HTTP request to your PBX.

To obtain the certificate, follow these steps:

1. Go to the "Modules" -> "Extensions and plugins" tab.

Install and enable the "Lets Encrypt Get SSL" module.

1. Go to the module interface

1. Perform the "Get/update cert" action:

Auto Dialer Module

This module provides a REST API for creating campaigns to automatically dial external numbers:

• When an employee is available, the module dials a phone number from the campaign pool.

• When the client answers, the call is connected to the internal queue or the employee’s extension.

• If the internal number is busy, the call is automatically terminated.

REST API Authentication

For all requests, except local ones, authentication is required.

By default, you can use the web interface's administrative password for authentication.

To restrict access to specific PBX settings, the "System Access Management" module can be used.

Example request:

Where:

• login – admin, the web interface username.

• password – adminpassword, the web interface password.

• 172.16.156.223 – the MikoPBX server address.

Response example:

Example of executing requests:

Polls

Allows you to organize automatic client surveys. Using the API, you can define a set of questions, their connections, and answer options.

It is possible to use text-to-speech generation or pre-recorded mp3/wav files.

Adding a Poll

Example cURL request:

Fetching Poll List

Response example:

Creating a Task

Response example:

Media Files

Uploading Media Files

Response example:

This module is designed for bidirectional synchronization of employee account data with MikoPBX. The data source is either an Active Directory or LDAP server.

When a new employee is created in the domain, they will automatically be uploaded into MikoPBX, with an available internal number assigned to them. The information about the number will then be sent back to the domain and recorded in the employee's profile. The same will happen with their mobile phone number and photograph. As always, the setup is extremely straightforward.

Synchronization Parameters

For each AD/LDAP server, you can specify synchronization settings, departmental filters, or create a custom filter for complex filtering logic.

Account Attributes

Next, you need to correctly configure the attributes for synchronizing account data.

Initial Synchronization

During the initial synchronization, the system will match the existing MikoPBX account data with the data obtained from the domain. The following fields are used for matching:

• Email address

• Employee name

• Mobile phone

• Internal phone

Testing and Launch

Before enabling automatic synchronization, it is recommended to test the correctness of the specified attributes by clicking the Run request button.

If all parameters are correctly specified, you will see a list of employees with attributes from the domain. This is a safe request and will not result in changes to the system.

Next Steps

After testing, you can initiate manual or automatic data synchronization.

In the columns "status" and "updated", you can track the current synchronization process.

Employee Deletion or Deactivation in the Domain

When an employee is deleted or deactivated in the domain, they will remain active in MikoPBX but will be moved to a special table called “Disabled Employees in LDAP/AD.”

The account will be retained until it is manually deleted by the MikoPBX administrator.

This approach accommodates complex call routing scenarios where simply removing the employee from the route without a replacement is not feasible.

Synchronization Conflicts

During synchronization, conflicts may occur if the system fails to create or modify employee data in MikoPBX or on the LDAP/AD server. All synchronization issues are logged by the module and recorded in a special table titled “Synchronization Conflicts.”

The MikoPBX administrator can manually resolve these issues and clear the conflicts table in the module.

SIP Password Synchronization

The module includes an option for synchronizing SIP passwords with the domain controller. This can be useful for automatically configuring IP phones within the company based on domain data. To enable synchronization, a special attribute must be created on the domain controller side, and this attribute should be specified in the “SIP Password” field in the attribute mapping settings for synchronization.

Note that the password will be stored in plain text. With bidirectional synchronization enabled, the password value from MikoPBX will be sent to the domain and vice versa, based on the date of the last modification.

Please note: The SIP password is not the same as the domain account password; it is a separate value.

This module is designed to handle missed calls automatically. Whenever a missed call is detected, a callback task is created. As soon as an employee becomes available, they receive a call; once they answer, an attempt is made to connect with the client.

Let's walk through the module's functionality with a few examples:

Missed Call

A client attempted to contact the company but was unable to reach anyone. This might happen for various reasons, such as:

• The call was disconnected.

• The client hung up before anyone answered.

In response, the module generates a callback task. Once an employee becomes available, they receive the task call.

An alert sound file can be played for the employee. You can specify this file in the module settings under Alert "A connection with the client will be made." After the notification, the system will initiate the client call.

Employees handling missed calls should be added to a shared Call Queue. Set the queue number or employee number for handling missed calls in the module settings.

Not every answered call can be considered successful. The module allows you to define a criterion, The duration of the answered call, which we consider successful.

If the call is unsuccessful, you can set retry parameters:

• Delay – interval between retry attempts

• Number of call attempts

Older calls may no longer be relevant, so there is a configurable “expiry time” for missed calls. Calls and tasks older than the set The number of seconds to analyze missed in the history will not be processed.

Callback Request from Client

In cases where a client is tired of waiting and requests a callback, the module can handle it as well. Specify the sound file in Alert "The request for a callback has been accepted"

Once the client presses 1, a callback task is created, and the client hears the confirmation notification. The Press 1 to request a callback feature is available in queues listed under Queues for callback.

You can also configure additional notifications in the Advanced settings for individual queues.

This feature can, for instance, prompt the client to press "1" to initiate a callback request.

Creating a Backup

1. Go to the "Modules" -> "Marketplace of modules section" tab.

Make sure that the Backup Module is installed and enabled.

1. Go to the module settings.

1. Click on "Create backup copy".

1. Select the data that should be included in the backup:

• PBX Settings - all configuration settings of MikoPBX made in the web interface.

• Call History - saves the cdr.db database (location: /storage/usbdisk1/mikopbx/astlogs/asterisk/cdr.db). This setting does not save actual call recordings, only the information on the Telephony → Call History (Documentation) tab without playback/download functionality.

• Call Recording Files - saves all call recordings in *.mp3 format.

• Sound Files - saves sound files uploaded to the PBX in the Telephony → Sound Files (Documentation) section.

1. Click on "Create a backup".

Once the process is complete, the backup will appear in the list of backups:

Managing Backup Files

In the backup list, you can perform the following actions:

• Restore from a backup.

• Download the backup archive.

• Delete the backup.

Restore from Backup

1. In the list of backups, select the desired one and click "Restore from backup".

1. Select the categories of data to restore.

1. Click on "Restore from a backup".

The restoration process will start, and once completed, the PBX will be rebooted.

The progress of data restoration will be displayed on the current page.

Scheduled Backups

1. Click the "Backup schedule" button to configure automatic backups.

1. To enable scheduled backups, activate the switch "Scheduled Backup."

1. Fill in the required information:

• Server Address - IP address of MikoPBX or the address of the SFTP \ FTP server.

• Port - for SFTP mode, the port is 22. Disabling the "SFTP Mode" switch activates FTP mode with port 21.

• Username - the username for server authentication.

• Password - the password for server authentication.

• Server Path - the directory where the backups will be saved. Recommended directory on MikoPBX: /storage/usbdisk1/mikopbx/backup/.

• Schedule - specify the day and time for the backup operation.

• Keep Last X Versions - specify how many backup versions should be retained.

• PBX Settings - all configuration settings of MikoPBX made in the web interface.

• Call History - saves the cdr.db database (location: /storage/usbdisk1/mikopbx/astlogs/asterisk/cdr.db). This does not save actual call recordings, only the information on the Telephony → Call History tab without playback/download functionality.

• Call Recording Files - saves all call recordings in *.mp3 format.

• Sound Files - saves sound files uploaded to the PBX in the Telephony → Sound Files section.

1. Click "Save."