Inbound Fax

A Gravity Rail phone number set to fax mode receives T.30 faxes over the phone network and delivers each successful transmission as a Chat. The AI agent assigned to that Chat can read any page of the fax and act on it — routing, summarising, filling forms — without a human having to open the document first.

Fax and SMS are independent. Turning a number into a fax receiver does not disable SMS; callers can still text the same number and those messages follow the normal workflow.

Prerequisites

Three things must be in place before a number can receive faxes:

Requirement	Where to check
Voice enabled on the phone number	Phone Numbers → number → General tab → Enable Voice
Default Workflow set on the phone number	Phone Numbers → number → General tab → Default Workflow
USE access on the Default Workflow for the member role that will handle incoming faxes	Workflows → workflow → Permissions tab

If any of these is missing, a fax attempt still creates a PhoneCall record (so you can see what was tried), but no Chat or documents are created. Check the phone number's Activity tab for fax_failed entries and the failureDetail field to diagnose the specific issue.

Enabling Fax Mode

1. Go to Channels → Phone Numbers.
2. Open the phone number you want to use for fax, or add a new one.
3. On the General tab, set Inbound Call Handling to Fax.
4. Confirm that Enable Voice is on and a Default Workflow is selected.
5. Click Save.

The number now dedicates its voice leg to fax. Phone calls to this number are answered as a fax tone, not a voice greeting.

One number, one inbound mode. A number can receive voice calls, or faxes, but not both at the same time. If you need to support both fax and phone in the same workspace, provision a separate number for fax.

What Happens When a Fax Arrives

1. The sender dials your fax number from their fax machine or fax service.
2. Gravity Rail answers the call and negotiates a T.30 session (V.27ter/V.29 with ECM).
3. The fax transmits. If it completes successfully, Gravity Rail atomically creates:
   • A Chat with channel = fax linked to the Default Workflow.
   • An Assignment in that Workflow.
   • Two File records — a lossless multipage PDF and the original TIFF — stored privately and encrypted in S3.
   • A Message in the Chat attaching both files.
4. The Assignment is handed to the Workflow's AI agent, which can read pages and respond.

Failed transmissions (line drop, T.30 error) set terminationReason = fax_failed on the PhoneCall record. Because the Chat, Assignment, and files are created atomically after the full T.30 exchange, a partial or failed fax leaves no empty Chat.

How the AI Agent Reads a Fax

The AI agent uses the read_file tool with a page argument to inspect the received documents one page at a time. Page numbers are 1-based and work identically for both the PDF and the TIFF renditions. Each page is returned as a lossless PNG scaled to a 1600 px long edge, which is enough resolution to read printed text, signatures, and form fields without loading the entire document into context at once.

This design lets the agent handle multi-page faxes incrementally — a 20-page referral packet can be summarised page-by-page rather than all at once, staying within model context limits.

Caller Experience

Senders use any standard fax machine, multifunction printer, or fax service. From their side, the call looks like any other fax transmission:

1. Dial the number.
2. Hear the receiving tone.
3. Press Start (or the machine does so automatically).
4. Transmission completes; the machine confirms success.

The caller sees nothing unique about a Gravity Rail fax number. If transmission fails (line noise, T.30 timeout), their machine will show the same error it would for any failed fax.

Permissions

Fax Chats follow the same member-role permission model as other Chats. The role that sends faxes needs USE access on the Default Workflow. Workspace members who need to view the received documents or Chats need at least USE access to the relevant inbox or Chat view.

To grant USE access to a Workflow:

1. Open the Workflow.
2. Go to the Permissions tab.
3. Add the member role and set Use to enabled.
4. Save.

PHI Handling

Received fax documents are stored privately in S3, encrypted at rest, and are never accessible without authentication. The files are linked to the Chat and visible only to workspace members with appropriate access.

The telephone numbers that appear in incoming fax sessions, the document content, and the S3 keys are treated as PHI and are never logged. Audit records contain only record IDs, page counts, file sizes, and transmission outcomes.

Troubleshooting

Symptom	Likely cause	What to check
Fax attempt records in Activity but no Chat created	Missing prerequisite	Is Enable Voice on? Is a Default Workflow set? Does the sender's member role have USE access?
fax_failed with no detail	T.30 error or line drop mid-transmission	Ask the sender to retry; persistent failures may indicate a carrier audio-quality issue between their equipment and Twilio's media stream. Contact support with the PhoneCall ID.
AI can see the Chat but cannot read the file	File permission	Confirm the AI agent's role has USE access to the Workflow and can access Files in the workspace.
SMS stopped working after enabling fax	Voice and SMS are separate	Fax mode only changes inbound call handling. Check the phone number's Enable SMS toggle — it should still be on.
Caller's machine reports a send failure but no PhoneCall record appears	Call never connected	Twilio never answered the call; likely a phone number configuration issue or the number was still in voice mode when the call arrived. Check Twilio logs via your org's Sub-account page.

Common Setups

Referral intake line

• Inbound Call Handling: Fax
• Default Workflow: Referral intake workflow
• Agent abilities: Read files, create DataRecord entries from fax content
• Permissions: Intake team role has USE access

Administrative documents

• Inbound Call Handling: Fax
• Default Workflow: Document triage workflow
• Agent behavior: Route to the correct member based on document type (detected by reading the first page)

Related

• Phone & Voice — Phone number setup, SMS, and work modes
• Voice — Voice configuration (Voice must remain enabled for fax mode to work)
• Workflows — Building the workflow that processes inbound faxes
• Files — How Gravity Rail stores and retrieves file attachments