This webpage explains how to customize the ringtones sounds for the new Electron-based 3CX Client. As of writing this page, many users have requested this feature back in the app but 3CX has not make that a feature yet. So this page explains how to do it. This is very technical, if compared to the older 3CX 3CXWin8Phone.exe app where the .wav files were directly available at C:\ProgramData\3CXPhone for Windows\PhoneApp\Sounds. Familiarity with nodejs and npm are helpful if not nessessary here.

For this Electron app, this is packed in a file located at, in my case, C:\Users\USERNAME\AppData\Local\Programs\3CXDesktopApp\app\resources\app.asar. ASAR files seems to be directly related to Electron apps as ASAR files act as an archiving utility for Electron.

Requirements

You need two things:

  • A working installation of npm (and indirectly nodejs), although installing npm is outside of the scope of this webpage (this might get complicated real fast!). You don’t need to absolutely do that on the same machine than 3CX, you could easily use another Linux box as a host to deal with the ASAR file extracting and repackaging;
  • Install the asar npm package; probably a command like npm install -g asar will do. The -g flag seems to be optional if you don’t mind typing the full location to the main asar.js Javascript app, for example /home/johndoe/3cx/node_modules/asar/bin/asar.js --help. If directly calling the .js file doesnt work (for Windows users), you may prepend the command with node, like node /home/johndoe/3cx/node_modules/asar/bin/asar.js --help, as long as node itself is in your PATH environment variable.

Exporting

You need to use asar on the file app.asar, but the accompanying folder app.asar.unpacked needs to be present next to app.asar as well when we extract: even though we don’t touch it, extraction WILL fail midway if the folder is missing. Run the extraction command by launching this command: path/to/asar.js extract app.asar extracted/, where /path/to/asar.js is the path to the asar NPM package you just downloaded.

johndoe@host:$ node_modules/asar/bin/asar.js extract app.asar extracted/
(node:3086472) ExperimentalWarning: The fs.promises API is experimental

Note that on a Intel i7 2nd-gen, this extract proccess took about a minute without anything displayed in the console.

Replacing audio files

The ringtones will be located in the extracted/dist/electron/notifications subfolder. The most noteworthy ringtones I had to change for my own need are:

  • Ringtone.xxx.mp3: Main inbound call ringtone that sounds like an iPhone ringtone;
  • Default.xxx.mp3: Integrated chat system message notification, the “one guitar chord strum” sound.

Note: The filenames ends with a series of hexadecimal characters that may or may not change over time or inbetween client installations or versions. I am not sure if they are static or not, so your filenames may vary.

Repackaging

Use this command in the same folder where you launched the command to unpack the file: path/to/asar.js pack extracted/ myapp.asar. This will recreate a new packaged ASAR file with your modifications, ready for use in your 3CX Application. Note that you have to quit any opened 3CX App instances so you can replance the original app.asar file.

If you want to make sure your new ASAR file has repackaged everything, look for the parameter path/to/asar.js list file.asar, which lists all the files contained in the ASAR file, and compare both original app.asar file listing with your own repackaged myapp.asar file, so there are no missing parts. For Linux (only), here is my humble suggestion:

$ path/to/asar.js list app.asar > original.txt
$ path/to/asar.js list myapp.asar > repackaged.txt
$ diff original.txt repackaged.txt

The diff command displays changes between files, in this case the file listing between both original and your repackaged file. Under normal circumstances, both files SHOULD be identical, and the diff command should then NOT be printing out any line. Otherwise, this means there are probably files missing.

Updates

This is yet to be seen, but I suspect that every software updates to this app will overwrite your app.asar file. I recommend restarting this whole process of extracting/repacking files everytime you have to apply ringtones. This will ensure you have the latest web interface in the app: the ASAR file contains most of the static web HTML/JavaScript/CSS/Images files that is used to show the UI in the app. Keeping an altered app.asar file and recopying that same file you created once everytime theres an update will prevent you to have the latest user interface in the app.