Fax Devices Module Documentation
Table of Contents
- Module Overview (Technical)
- Module Overview (Commercial/Business)
- Module Overview (End User/Administrator)
- Configuration Fields Reference
- Device Types
- Common Scenarios & Examples
- Limitations & Important Notes
- Troubleshooting Tips
- Glossary
---
1. Module Overview (Technical)
What Are Fax Devices?
Fax Devices are virtual or physical fax endpoints that handle inbound and outbound fax transmission using FreeSWITCH's fax engine (mod_spandsp). Received faxes are stored, optionally converted to PDF, and can be emailed to recipients.
Architecture
┌─────────────────────────────────────────────────────────────────┐
│ Fax System Architecture │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Inbound Fax Call │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ routing/fax.lua │ │
│ │ │ │
│ │ 1. Detect call context (inbound/internal) │ │
│ │ 2. Get fax device number │ │
│ │ 3. Route to fax_receive.lua │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ fax/fax_receive.lua │ │
│ │ │ │
│ │ 1. Load fax device config from public.fax_devices │ │
│ │ 2. Configure T.38 / ECM settings │ │
│ │ 3. Answer call, receive fax (rxfax) │ │
│ │ 4. Store TIFF file │ │
│ │ 5. Convert to PDF (if enabled) │ │
│ │ 6. Send email notification │ │
│ │ 7. Log to public.fax_logs │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
│ Outbound Fax │
│ ┌──────────────────────────────────────────────────────────┐ │
│ │ fax/fax_send.lua │ │
│ │ │ │
│ │ 1. Load document to send │ │
│ │ 2. Configure T.38 / retry settings │ │
│ │ 3. Originate call, send fax (txfax) │ │
│ │ 4. Log result, send notification │ │
│ │ │ │
│ └──────────────────────────────────────────────────────────┘ │
│ │
└─────────────────────────────────────────────────────────────────┘
Key Tables
| Table | Purpose |
|---|
public.fax_devices | Fax device configurations | |
public.fax_logs | Fax transmission logs |
Key Files
| File | Description |
|---|
modules/faxDevices/FaxDevicesPage.tsx | Frontend device management | |
modules/faxSending/FaxSendingPage.tsx | Outbound fax UI | |
modules/faxViewer/FaxViewerPage.tsx | Fax log viewer | |
lua/main/xml_handlers/routing/fax.lua | Fax routing handler | |
lua/main/xml_handlers/fax/fax_receive.lua | Inbound fax handler | |
lua/main/xml_handlers/fax/fax_send.lua | Outbound fax handler |
2. Module Overview (Commercial/Business)
Business Value
Fax Devices provides virtual fax capability:
| Without Fax Module | With Fax Module |
|---|
| Physical fax machines | Virtual software fax | |
| Paper documents | PDF delivery | |
| No email integration | Email to recipient | |
| Manual monitoring | Automatic logging |
Use Cases
- Email-to-Fax
- Receive faxes as email attachments
- PDF format for easy viewing
- Inbound Fax Lines
- Dedicated fax DIDs
- Multiple departments
- Outbound Faxing
- Send from web interface
- Automatic retries
- Fax Archive
- Storage and logging
- Compliance records
Feature Highlights
| Feature | Benefit |
|---|
| T.38 Support | Reliable FoIP | |
| ECM | Error correction | |
| PDF Conversion | Easy viewing | |
| Email Delivery | Paperless fax | |
| Auto Retry | Reliable sending | |
| Resolution Options | Quality control |
3. Module Overview (End User/Administrator)
What Can You Do?
- Configure virtual fax devices
- Set up email delivery
- Enable T.38 and ECM
- Configure auto-retry
- View fax logs
- Send outbound faxes
Fax Device Configuration
┌─────────────────────────────────────────────────────────────────┐
│ Create Fax Device │
├─────────────────────────────────────────────────────────────────┤
│ │
│ Tab: Basic │
│ ├─ Device Name: Main Office Fax │
│ ├─ Fax Number / DID: 4000 │
│ ├─ Device Type: [Virtual Fax (Software) ▼] │
│ ├─ Direction: [Both (Bidirectional) ▼] │
│ └─ Enabled: ✓ │
│ │
│ Section: Email Configuration │
│ ├─ Destination Email: fax@company.com │
│ └─ From Email: noreply@company.com │
│ │
│ Tab: Technical Settings │
│ ├─ T.38 Protocol: ✓ │
│ ├─ Error Correction Mode: ✓ │
│ ├─ Resolution: Fine (204×196 dpi) │
│ ├─ Paper Size: Letter │
│ ├─ Convert to PDF: ✓ │
│ └─ Storage Path: /var/lib/ring2all/fax/ │
│ │
│ Section: Retry Configuration │
│ ├─ Max Retries: 3 │
│ └─ Retry Interval: 300 seconds │
│ │
│ Section: Notifications │
│ ├─ Notify on Receive: ✓ │
│ ├─ Notify on Send: ✓ │
│ └─ Notify on Failure: ✓ │
│ │
│ [Save] [Cancel] │
│ │
└─────────────────────────────────────────────────────────────────┘
Quick Tips
TIP
Enable T.38: T.38 provides more reliable fax over IP.
TIP
Convert to PDF: PDF is easier to view than TIFF.
CAUTION
Storage: Ensure adequate disk space for fax storage.
---
4. Configuration Fields Reference
| Field | Description | Example |
|---|
| Device Name | Identifier | Main Office Fax | |
| Fax Number / DID | Fax line number | 4000 | |
| Device Type | Endpoint type | Virtual, ATA, Trunk | |
| Direction | Inbound/Outbound/Both | Both | |
| Enabled | Active status | On/Off |
Email Configuration
| Field | Description | Example |
|---|
| Destination Email | Where to send faxes | fax@company.com | |
| From Email | Sender address | noreply@company.com |
Technical Settings
| Field | Description |
|---|
| T.38 Protocol | Enable T.38 FoIP | |
| ECM | Error Correction Mode | |
| Resolution | Standard/Fine/SuperFine | |
| Paper Size | Letter/A4/Legal | |
| Convert to PDF | Auto-convert TIFF to PDF | |
| Storage Path | Fax file directory | |
| Auto-delete After | Days to keep files |
Retry Configuration
| Field | Description | Default |
|---|
| Max Retries | Retry attempts | 3 | |
| Retry Interval | Seconds between retries | 300 |
Notifications
| Field | Description |
|---|
| Notify on Receive | Email when fax received | |
| Notify on Send | Email on successful send | |
| Notify on Failure | Email on failure |
5. Device Types
Virtual Fax (Software)
| Property | Description |
|---|
| Engine | FreeSWITCH mod_spandsp | |
| Protocol | T.38 or G.711 passthrough | |
| Use Case | Pure software fax |
ATA Device
| Property | Description |
|---|
| Engine | External ATA adapter | |
| Connection | SIP to ATA | |
| Use Case | Physical fax machine |
SIP Trunk
| Property | Description |
|---|
| Engine | External fax service | |
| Connection | SIP trunk | |
| Use Case | Cloud fax service |
Resolutions
| Resolution | DPI | Quality |
|---|
| Standard | 204×98 | Fast, lower quality | |
| Fine | 204×196 | Recommended | |
| SuperFine | 300 | Highest quality |
6. Common Scenarios & Examples
Scenario 1: Department Fax Line
Device:
| Setting | Value |
|---|
| Name | Sales Fax | |
| Number | 4001 | |
| Type | Virtual | |
| Direction | Both | |
| Email To | sales@company.com | |
| T.38 | ✓ | |
| PDF | ✓ |
Scenario 2: Receive-Only Fax
Device:
| Setting | Value |
|---|
| Name | Reception Fax | |
| Number | 4000 | |
| Direction | Inbound Only | |
| Email To | reception@company.com | |
| Notify Receive | ✓ |
Scenario 3: High-Volume Fax
Device:
| Setting | Value |
|---|
| Name | High Volume | |
| Resolution | Standard (faster) | |
| Max Retries | 5 | |
| Auto-delete | 30 days |
7. Limitations & Important Notes
Technical Notes
NOTE
T.38 Support: Both endpoints must support T.38 for FoIP mode.
NOTE
G.711 Fallback: Falls back to audio mode if T.38 fails.
WARNING
Network Quality: Fax is sensitive to packet loss and jitter.
Best Practices
- Enable T.38: More reliable than audio
- Enable ECM: Corrects transmission errors
- Use Fine Resolution: Good balance
- Enable PDF: Easier viewing
- Monitor Storage: Clean up old faxes
---
8. Troubleshooting Tips
Common Issues
| Symptom | Possible Cause | Solution |
|---|
| Fax fails | T.38 not supported | Disable T.38 | |
| Garbled pages | No ECM | Enable ECM | |
| No email | Email not configured | Set email_to | |
| Slow transfer | High resolution | Use Standard | |
| Storage full | No cleanup | Set auto-delete |
Diagnostic SQL
List fax devices:
SELECT id, name, number, type, direction, email_to, enabled
FROM public.fax_devices
WHERE domain_id = [domain_id];
SELECT direction, remote_number, pages, success, result_text, created_at
FROM public.fax_logs
WHERE fax_device_id = [device_id]
ORDER BY created_at DESC
LIMIT 20;
FreeSWITCH Logs
# Check fax operations
grep "INFO\] Fax" /var/log/freeswitch/freeswitch.log
grep "rxfax\|txfax" /var/log/freeswitch/freeswitch.log
---
9. Glossary
| Term | Definition |
|---|
| T.38 | Fax over IP protocol | |
| ECM | Error Correction Mode | |
| FoIP | Fax over IP | |
| TIFF | Tagged Image File Format | |
| rxfax | FreeSWITCH receive fax | |
| txfax | FreeSWITCH transmit fax | |
| mod_spandsp | FreeSWITCH fax module |
Lua Script Status ✅
Already Correct
| Script | Status |
|---|
routing/fax.lua | ✅ Routing handler (no DB queries) | |
fax/fax_receive.lua | ✅ Uses public.fax_devices, public.fax_logs | |
fax/fax_send.lua | ✅ Outbound fax handler |
---
Documentation last updated: January 2026
