---
title: "Fax Devices Module Documentation"
description: "Documentation for Fax Devices"
---

## Table of Contents
1. [Navigation & Access](#navigation--access)
2. [Screenshots & Visual Interface](#screenshots--visual-interface)
3. [Module Overview (Technical)](#1-module-overview-technical)
4. [Module Overview (Commercial/Business)](#2-module-overview-commercialbusiness)
5. [Module Overview (End User/Administrator)](#3-module-overview-end-useradministrator)
6. [Configuration Fields Reference](#4-configuration-fields-reference)
7. [Device Types](#5-device-types)
8. [Common Scenarios & Examples](#6-common-scenarios--examples)
9. [Limitations & Important Notes](#7-limitations--important-notes)
10. [Model Context Protocol (MCP) AI Integration](#8-model-context-protocol-mcp-ai-integration)
11. [Troubleshooting Tips](#9-troubleshooting-tips)
12. [Glossary](#10-glossary)
---

## Navigation & Access

To access the Fax Devices management module:
1. Log in to the Ring2All Web Portal (`https://<domain-or-ip>/login`).
2. In the left navigation sidebar, expand **PBX Engine**.
3. Under **Virtual Faxes**, click **Fax Devices** (`/pbx/virtual-faxes/devices`).
4. To provision a new virtual or physical fax endpoint, click the **+ Add Fax Device** button (`/pbx/virtual-faxes/devices/new`).

---

## Screenshots & Visual Interface

### Fax Devices Management Directory
Overview table displaying all configured virtual faxes and ATA hardware bridges, showing extension numbers, endpoints, protocol modes (T.38 / ECM), target email routing, and operational status.
![Fax Devices List](/screenshots/pbx/virtual-faxes/fax-devices-list.png)

### Fax Device Configuration & Provisioning Form
Comprehensive endpoint configuration form covering SIP identification, transmission parameters, T.38 FoIP settings, automated PDF generation, retry thresholds, and notification routing.
![Fax Devices Form](/screenshots/pbx/virtual-faxes/fax-devices-form.png)

---

## 1. Module Overview (Technical)

### What Are Fax Devices?

Fax Devices are **virtual or physical fax endpoints** that handle inbound and outbound fax transmission using Telephony Server'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                        │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 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

1. **Email-to-Fax**
   - Receive faxes as email attachments
   - PDF format for easy viewing

2. **Inbound Fax Lines**
   - Dedicated fax DIDs
   - Multiple departments

3. **Outbound Faxing**
   - Send from web interface
   - Automatic retries

4. **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

### Basic Information

| 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** | Telephony Server 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

1. **Enable T.38**: More reliable than audio
2. **Enable ECM**: Corrects transmission errors
3. **Use Fine Resolution**: Good balance
4. **Enable PDF**: Easier viewing
5. **Monitor Storage**: Clean up old faxes

---

## 8. Model Context Protocol (MCP) AI Integration

The Ring2All Platform Copilot connects to the Virtual Fax engine via the Model Context Protocol (MCP), providing conversational provisioning, parameter updates, diagnostic status inspections, and number validation for Fax-to-Email endpoints.

### Exposed MCP Tools

| Tool Name | Operation | Primary Parameters | Description |
|:---|:---|:---|:---|
| `list_fax_devices` | Directory Query | `search` (string, optional) | Lists all Fax Devices in the active domain, including device type (`VIRTUAL`, `ATA`, `TRUNK`), fax number, direction, destination email, and T.38 status. |
| `get_fax_device_status` | Device Diagnostics | `identifier` (name or number) | Inspects configuration parameters, PDF conversion settings, and destination email for a specific fax device. |
| `create_fax_device` | Endpoint Provisioning | `name` (string), `number` (string), `emailTo` (string), `type` (string), `t38Enabled` (boolean) | Provisions a new virtual fax device. Enforces strict cross-telephony number uniqueness before creation. |
| `update_fax_device` | Settings Modification | `identifier` (string), `emailTo` (string), `t38Enabled` (boolean), `enabled` (boolean) | Updates email routing, protocol switches, and operational state of an existing fax device. |
| `delete_fax_device` | Device Deletion | `identifier` (string) | Safely deletes a fax device from the domain and synchronizes Telephony dialplan caches. |
| `query_fax_history` | Transmission Logs | `direction` (string), `search` (string), `limit` (number) | Retrieves recent inbound and outbound fax transmission records, status codes, and page counts. |

### Number Uniqueness & Telephony Collision Safeguards

- **Universal Dialplan Protection**: The fax device `number` is validated through the central `extensionValidator` utility against all active telephony resources (`dialplan_registry`, `sip_extensions`, `ring_groups`, `call_center_queues`, `call_flows`, `time_conditions`, `direct_routes`).
- **Zero Number Collisions**: If an administrator attempts to assign an internal extension number (e.g. `2099`) that is already bound to a SIP user, conference, or queue, the creation or update request is rejected immediately with a user-friendly error message identifying the conflicting module.

### Example MCP Payloads

#### 1. Creating a Virtual Fax-to-Email Endpoint (`create_fax_device`)
```json
{
  "name": "Legal Department Virtual Fax",
  "number": "2090",
  "type": "VIRTUAL",
  "direction": "both",
  "emailTo": "legal-faxes@company.com",
  "t38Enabled": true,
  "convertToPdf": true
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "message": "Fax device \"Legal Department Virtual Fax\" created successfully!",
    "id": 12,
    "number": "2090",
    "emailTo": "legal-faxes@company.com"
  }
}
```

#### 2. Checking Fax Device Status (`get_fax_device_status`)
```json
{
  "identifier": "2090"
}
```

### Copilot Natural Language Prompts

- *"List all virtual fax devices and their destination email addresses."*
- *"Create a new virtual fax device called 'Accounting Fax' on extension 2095 that sends PDFs to accounting@company.com."*
- *"Check if extension 2090 is available or if it conflicts with an existing phone extension."*
- *"Show me the last 5 faxes received on the Legal Virtual Fax."*

---

## 9. 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:**
```sql
SELECT id, name, number, type, direction, email_to, enabled
FROM public.fax_devices
WHERE domain_id = [domain_id];
```

**View fax logs:**
```sql
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;
```

### Telephony Server Logs

```bash
# Check fax operations
grep "INFO\] Fax" /var/log/freeswitch/freeswitch.log
grep "rxfax\|txfax" /var/log/freeswitch/freeswitch.log
```

---

## 10. Glossary

| Term | Definition |
|------|------------|
| **T.38** | Fax over IP protocol |
| **ECM** | Error Correction Mode |
| **FoIP** | Fax over IP |
| **TIFF** | Tagged Image File Format |
| **rxfax** | Telephony Server receive fax |
| **txfax** | Telephony Server transmit fax |
| **mod_spandsp** | Telephony Server fax module |

---

*Documentation last updated: January 2026*