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

## 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. [Log Fields Reference](#4-log-fields-reference)
7. [Common Scenarios & Examples](#5-common-scenarios--examples)
8. [Limitations & Important Notes](#6-limitations--important-notes)
9. [Model Context Protocol (MCP) AI Integration](#7-model-context-protocol-mcp-ai-integration)
10. [Troubleshooting Tips](#8-troubleshooting-tips)
11. [Glossary](#9-glossary)
---

## Navigation & Access

To access the Fax Viewer log and document repository:
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 Viewer** (`/pbx/virtual-faxes/viewer`).
4. Browse transmitted faxes, inspect delivery status, or preview and download received PDF/TIFF documents.

---

## Screenshots & Visual Interface

### Fax History & Activity Log
Interactive data grid showing incoming and outgoing fax logs, remote station IDs, page counts, delivery outcome flags, transfer bitrates, and direct download links.
![Fax Viewer Activity Log](/screenshots/pbx/virtual-faxes/fax-viewer-list.png)

---

## 1. Module Overview (Technical)

### What Is Fax Viewer?

Fax Viewer is a **log viewing interface** that displays all inbound and outbound fax transmissions. It provides searchable access to fax history, status information, and the ability to view or download fax documents.

### Architecture

```
┌─────────────────────────────────────────────────────────────────┐
│                    Fax Viewer Architecture                      │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  Admin Panel                                                    │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        FaxViewerPage.tsx                                 │   │
│  │                                                          │   │
│  │  ┌─────────────────────────────────────────────────────┐ │   │
│  │  │ Date       │ Dir   │ Device │ Remote   │ Pages │ Status│ │   │
│  │  ├─────────────────────────────────────────────────────┤ │   │
│  │  │ 2026-01-16 │ ← IN  │ Main   │ +1555123 │  3    │ ✓    │ │   │
│  │  │ 2026-01-16 │ → OUT │ Sales  │ +1555456 │  2    │ ✓    │ │   │
│  │  │ 2026-01-15 │ ← IN  │ Main   │ +1555789 │  1    │ ✗    │ │   │
│  │  └─────────────────────────────────────────────────────┘ │   │
│  │                                                          │   │
│  │  [View] [Download] [Delete]                              │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│       │                                                         │
│       ▼ API Query                                               │
│  ┌──────────────────────────────────────────────────────────┐   │
│  │        Backend API                                       │   │
│  │                                                          │   │
│  │  SELECT * FROM public.fax_logs                           │   │
│  │  WHERE domain_id = ?                                     │   │
│  │  ORDER BY created_at DESC                                │   │
│  │                                                          │   │
│  └──────────────────────────────────────────────────────────┘   │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

---

## 2. Module Overview (Commercial/Business)

### Business Value

Fax Viewer provides **complete fax history**:

| Without Fax Viewer | With Fax Viewer |
|--------------------|-----------------|
| No transmission history | Full audit trail |
| Unknown status | Success/failure visible |
| No document access | View/download documents |
| Manual tracking | Searchable logs |

### Use Cases

1. **Audit Trail**
   - Track all fax activity
   - Compliance documentation

2. **Troubleshooting**
   - Identify failed transmissions
   - Review error messages

3. **Document Retrieval**
   - Find past faxes
   - Download for records

4. **Status Monitoring**
   - Check delivery status
   - Confirm receipt

### Feature Highlights

| Feature | Benefit |
|---------|---------|
| **Search** | Find faxes quickly |
| **Direction Filter** | Inbound/Outbound |
| **Status Display** | Success/Failed |
| **Document View** | Preview faxes |
| **Download** | Save to local |
| **Delete** | Clean up history |

---

## 3. Module Overview (End User/Administrator)

### What Can You Do?

- View all fax transmissions
- Search by number or caller ID
- Filter by direction
- View document content
- Download fax files
- Delete old logs

### Fax Viewer Interface

```
┌─────────────────────────────────────────────────────────────────┐
│              Fax Viewer                                         │
├─────────────────────────────────────────────────────────────────┤
│                                                                 │
│  🔍 [Search faxes by number or caller ID...        ]           │
│                                                                 │
│  ┌───────────────────────────────────────────────────────────┐  │
│  │ Date        │ Dir      │ Device   │ Remote     │Pgs│Status│  │
│  ├─────────────┼──────────┼──────────┼────────────┼───┼──────┤  │
│  │ 01/16 10:30 │ Received │ Main Fax │+15551234567│ 3 │  ✓   │  │
│  │ 01/16 09:15 │ Sent     │ Sales    │+15559876543│ 2 │  ✓   │  │
│  │ 01/15 16:45 │ Received │ Main Fax │+15555551234│ 1 │  ✗   │  │
│  │ 01/15 14:20 │ Sent     │ Support  │+15557771234│ 4 │  ✓   │  │
│  │ 01/15 11:00 │ Received │ Main Fax │+15558881234│ 2 │  ✓   │  │
│  └───────────────────────────────────────────────────────────┘  │
│                                                                 │
│  Row Actions: [👁️ View] [⬇️ Download] [🗑️ Delete]               │
│                                                                 │
│  Showing 1-10 of 156 faxes                                      │
│  [< Previous] [Next >]                                          │
│                                                                 │
└─────────────────────────────────────────────────────────────────┘
```

### Quick Tips

> [!TIP]
> **Search**: Search by phone number or remote caller ID.

> [!TIP]
> **Download PDF**: Successfully received faxes can be downloaded as PDF.

> [!CAUTION]
> **Delete**: Deleting a log removes the document permanently.

---

## 4. Log Fields Reference

### Display Columns

| Column | Description |
|--------|-------------|
| **Date** | Transmission date/time |
| **Direction** | Received (inbound) or Sent (outbound) |
| **Device** | Fax device used |
| **Remote** | Remote fax number |
| **Pages** | Number of pages |
| **Status** | Success or Failed |
| **Size** | File size |

### Direction Types

| Direction | Icon | Description |
|-----------|------|-------------|
| **Received** | ← | Inbound fax |
| **Sent** | → | Outbound fax |

### Status Types

| Status | Description |
|--------|-------------|
| **Success** | Transmission completed |
| **Failed** | Transmission failed |

### Available Actions

| Action | Description |
|--------|-------------|
| **View** | Open fax document |
| **Download** | Save file locally |
| **Delete** | Remove log and file |

---

## 5. Common Scenarios & Examples

### Scenario 1: Find Recent Fax

1. Open Fax Viewer
2. Look at recent entries
3. Click View to preview
4. Download if needed

### Scenario 2: Search for Specific Sender

1. Enter phone number in search
2. Results filter automatically
3. View matching faxes

### Scenario 3: Check Failed Transmissions

1. Look for failed status entries
2. Review error details
3. Retry if outbound

### Scenario 4: Archive Faxes

1. Download important faxes
2. Save to local storage
3. Delete from system

---

## 6. Limitations & Important Notes

### Technical Notes

> [!NOTE]
> **Read-Only Logs**: This module views logs only. Sending is done via Send Fax module.

> [!NOTE]
> **File Storage**: Documents stored on server filesystem.

> [!WARNING]
> **Delete Permanent**: Deleting removes both log and document file.

### Best Practices

1. **Regular Review**: Check for failed transmissions
2. **Archive Important**: Download critical faxes
3. **Clean Up**: Delete old unnecessary logs
4. **Search Smart**: Use full phone numbers

---

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

The Ring2All Platform Copilot integrates with the Fax Viewer archive via the Model Context Protocol (MCP) to audit incoming/outgoing fax transmissions, diagnose delivery errors, inspect transfer bitrates, and verify page delivery.

### Exposed MCP Tools

| Tool Name | Operation | Primary Parameters | Description |
|:---|:---|:---|:---|
| `query_fax_history` | History Search | `direction` ("all", "inbound", "outbound"), `search` (string, optional), `limit` (number) | Retrieves recent fax transmission logs, showing timestamp, remote phone number, caller ID, page count, and success status. |
| `get_fax_details` | Detailed Diagnostic Inspection | `faxLogId` (number) | Fetches complete transmission diagnostics for a specific fax record, including result codes, transfer rate, and rendered PDF path. |
| `list_fax_devices` | Device Inventory | `search` (string, optional) | Queries configured fax devices to correlate activity with specific endpoints. |

### Operational Safeguards & Storage Privacy

- **Domain Scope Isolation**: Users and Copilot sessions can only query fax logs belonging to their authenticated tenant domain (`WHERE domain_id = :domain_id`).
- **Read-Only Inspection**: Querying fax history and viewing transmission details does not delete or truncate files on disk.
- **Path Sanitization**: Direct disk paths are never exposed to untrusted external callers; file retrieval relies on secure authenticated download tokens.

### Example MCP Payloads

#### 1. Querying Recent Inbound Faxes (`query_fax_history`)
```json
{
  "direction": "inbound",
  "limit": 10
}
```
*Response:*
```json
{
  "success": true,
  "data": {
    "totalReturned": 2,
    "faxes": [
      {
        "id": 892,
        "direction": "inbound",
        "remoteNumber": "+13055550180",
        "callerId": "Medical Records <+13055550180>",
        "pages": 4,
        "success": true,
        "resultText": "OK",
        "transferRate": 14400,
        "timestamp": "2026-09-08T14:15:22.000Z"
      },
      {
        "id": 885,
        "direction": "inbound",
        "remoteNumber": "+17865550122",
        "callerId": "Apex Law <+17865550122>",
        "pages": 2,
        "success": true,
        "resultText": "OK",
        "transferRate": 14400,
        "timestamp": "2026-09-08T11:02:10.000Z"
      }
    ]
  }
}
```

#### 2. Inspecting a Failed Fax Transmission (`get_fax_details`)
```json
{
  "faxLogId": 890
}
```

### Copilot Natural Language Prompts

- *"Show me all faxes received today across our domain."*
- *"Why did the fax transmission to +13055550199 fail? Look up the error details in the log."*
- *"How many total pages of faxes were processed this week?"*
- *"Find the latest fax received from sender +13055550180."*

---

## 8. Troubleshooting Tips

### Common Issues

| Symptom | Possible Cause | Solution |
|---------|---------------|----------|
| No logs shown | No fax activity | Wait for fax transmissions |
| View fails | File deleted | File may have been cleaned up |
| Download fails | File missing | Check storage path |
| Search no results | Wrong format | Try full number with country code |

### Diagnostic SQL

**View recent fax logs:**
```sql
SELECT 
  fl.direction,
  fl.remote_number,
  fl.pages,
  fl.success,
  fl.result_text,
  fl.file_path,
  fd.name as device_name,
  fl.created_at
FROM public.fax_logs fl
JOIN public.fax_devices fd ON fl.fax_device_id = fd.id
WHERE fl.domain_id = [domain_id]
ORDER BY fl.created_at DESC
LIMIT 20;
```

**Count by status:**
```sql
SELECT 
  success,
  COUNT(*) as count
FROM public.fax_logs
WHERE domain_id = [domain_id]
GROUP BY success;
```

---

## 9. Glossary

| Term | Definition |
|------|------------|
| **Fax Log** | Record of fax transmission |
| **Inbound** | Received fax |
| **Outbound** | Sent fax |
| **Remote Number** | Other party's fax number |
| **Pages** | Document page count |
| **TIFF** | Fax document format |

---

*Documentation last updated: January 2026*