FreeSWITCH FAX (FSFax) is a new project of mine to develop a fax application on top of FreeSWITCH/SpanDSP using LUA scripts.

Right now, FSFax is in it's baby stages. It's somewhat functional (I'm using it!) but it needs a lot more work! You can check out the code at the git repo here.


  • LUA based script to Receive faxes
  • Store detailed fax log in database
  • Pull (via grep) FreeSWITCH log for each fax call and store with fax image.
  • Email recieved faxes based on fax routing table in database.
  • LUA based console interface (with auto-complete) to
    • Display/Set FSFax Settings
    • Display/Set Fax Routing
    • Display Stats


  • Clean up recieve/faxctl code.
  • Write script for sending faxes.
  • create basic PHP class to interface with sqlite3 database


GIT the Scripts

First you need to get a copy of the scripts. The easiest way would to just pull them in from the git repo then into your FreeSWITCH scripts folder. The below example is based on CentOS and your environment may vary some.

cd /usr/share/freeswitch/scripts/
git clone git:// fsfax


Now we need to tell FreeSWITCH to pass calls to the rxfax.lua script. You need to create a dialplan for this. Your dialplan needs will probably be specific to your environment but below is an example to get started with.

cd /etc/freeswitch/dialplan/public
vim rxfax.xml

This example will send all inbound calls to the FSFax script. This might be perfect for you if you're building a 100% fax only system. Otherwise you need to adjust the destination number condition to fit your environment.

        <extension name="rxfax">
                <condition field="destination_number" expression=".*">
                        <action application="lua" data="fsfax/rxfax.lua"/>

Basic Config

When you first install FSFax there's a couple commands you need to run from the console to create the database, add the alias and complete records, then create inbound fax to email routes.

So, from the fs_cli console.

This will create the alias and complete entries then build the fsfax.db database file.

lua fsfax/faxctl.lua init all

Now, to add your first fax to email route. The below will create a route for the DID 14561239876 to the EMAIL and all faxes that come into your system to that DID will get sent off to that email address.

fax route set 14561239876

QR Code
QR Code freeswitch:freeswitch_fax (generated for current page)