How to set up Voice Authentication for x-hoppers

Created by
Last updated: 14 November 2025, 13:30

This guide explains how to configure voice authentication for assigning x-hoppers headsets to users. 

Created: June 2024

Updated: November 2025

Introduction

x-hoppers allows you to configure the logic of assigning headsets to users via simple user sign in (dial-by-name), so that staff can take the headset from the charger, pronounce their Employee ID (extension) and automatically get assigned to the headset.

Requirements 

Configuration

By default, the feature is disabled. To enable it:

  • Add the parameter --xhop_voice_login true to the /etc/systemd/system/pbx-data-engine.service.d/override.conf file. The parameter should be added to the line "ExecStart=/usr/sbin/pbx_data_engine.py --daemon: 

    nano-tiny /etc/systemd/system/pbx-data-engine.service.d/override.conf​[Service]ExecStart=ExecStart=/usr/sbin/pbx_data_engine.py --daemon --xhop_voice_login true

  • Optionally, you can enable simple user sign in for users of specific Departments only. For this, add “department” value after --xhop_voice_login and indicate the list of departments in the environment variable XHOP_VOICE_AUTH_DEPS_LIST separated by comma:

    nano-tiny /etc/systemd/system/pbx-data-engine.service.d/override.conf​[Service]ExecStart=ExecStart=/usr/sbin/pbx_data_engine.py --daemon --xhop_voice_login departmentEnvironment='XHOP_VOICE_AUTH_DEPS_LIST=Sales,Support'

  • Make sure to reload systemd and restart the service to apply the changes: 

    systemctl daemon-reloadsystemctl restart pbx-data-engine

Note: Reloading systemd is required each time you make any changes to the /etc/systemd/system/pbx-data-engine.service.d/override.conf file.

When enabled, each time the headset is placed into the charger, user gets unassigned and gets Service subscription plan type in the system.

Note: Users with SuperHopper subscription plan do not get Service subscription plan after placing x-hoppers headset into the charger, but stay with the SuperHopper subscription plan. 

When a user lifts the headset from the charger:

  1. The user is asked to say their Employee ID “Please say your ID to log in”

  2. The user should pronounce the Employee ID 

  3. The system looks for the user and assigns the headset to the user

Important: For the feature to start working on the headsets, follow one of the following procedures:

  • After enabling the feature, when using the headsets for the first time, users need to lift the headsets from the charger -> place into the charger -> lift from the charger again

  • Alternatively, before performing the upgrade and activating the feature, unassign headsets via x-hoppers admin (Devices -> choose device and click Assign to user -> in the Extension field, choose “unknown”). Then, when users lift the headsets from the charger, they need to press the Push-to-talk button first

Customization

It is possible to customize prompts pronounced during voice authentication. For this, add the following variable(s) to x-hoppers admin -> Dialplan -> General Settings -> Set dialplan variables field:

  1. To set a custom prompt instead of “Please say your Colleague ID to login“:

XHOPPERS_LOGIN_PROMPT=custom login message

  1. To skip the playback message “Please hold to use the device, or say cancel to search again“:

XHOPPERS_CONFIRMATION_PROMPT=no​

By default, the value is yes. 

  1. To set a custom x-hoppers message pronounced at the end of voice authentication, before assigning a headset to a user:

XHOPPERS_FINISH_PROMPT=your custom prompt

By default, the variable is empty.

  1. To set a custom x-hoppers message instead of the default "Authorization successful. Please hold.", pronounced upon successful voice authentication: 

XHOPPERS_VA_SUCCESS_PROMPT=your custom prompt

  1. By default, during voice authentication, a message with information about battery level of x-hoppers headsets is played to users. To customize the default message “Battery level is. Make sure the headset is charged”:

XHOPPERS_BATTERY_PROMPT=Battery level is %s. Make sure the headset is charged.

Where "%s" stands for battery level and can be used to pronounce the battery level information in the needed place.

  1. To disable battery level announcement:

XHOPPERS_ANNOUNCE_BATTERY_LEVEL=no

  1. To set a custom x-hoppers message instead of the default "Sorry, there is another headset assigned to you, two headsets cannot be used at the same time", pronounced when user tries to log in to multiple headsets at the same time:

XHOPPERS_MULTIASSIGN_BLOCK_PROMPT=your custom prompt

  1. To activate the logic to ask user to confirm the extension:

XHOPPERS_EXTEN_CONFIRMATION=yes

When enabled, after submitting the extension, user is asked to confirm it. By default, the option is disabled.

  1. To modify authorization failed prompt: 

XHOPPERS_VOICE_AUTH_FAILURE_PROMPT="Authorization failed. Please press the Call button to try again."