Inbound Fax

A Gravity Rail phone number set to fax receives T.30 faxes over the phone network and files each successful transmission as private, encrypted documents in a folder you choose. What happens next — starting a Workflow Chat, notifying someone, calling a webhook — is up to the Fax Received actions you set up.

Fax and SMS are independent. Turning a number into a fax receiver does not disable SMS; callers can still text the same number, and the number's Messaging routing rules decide what happens to those texts.

Setting Up a Fax Number

Fax is a channel on the phone number's Settings tab.

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 number's Settings tab, in Channels, check Enable fax. Voice and fax are mutually exclusive: a number answers calls as a conversation or as a fax line, never both, so Enable voice is unavailable while Enable fax is checked (and the other way round).
4. Under Enable fax, choose:
   • Fax Owner — the Agent or Member who owns each received document. A fax sender is never authenticated, so ownership comes from your side. Leave it empty to use the number's owner.
   • Fax landing folder — the folder received faxes are filed in. Browse to one, or create a new folder while you are in there.
5. Click Save.

The panel under Enable fax says whether the line is ready. Faxes are not received until the number has both a fax owner and a landing folder, and the fax owner can open that folder. When the owner cannot open it, Fix this offers to give the owner's role access to the folder.

The number now dedicates its voice leg to fax. Calls to this number are answered with a fax tone, not a voice greeting, and the number's Voice routing rules are not consulted — fax is a mode of the line, not a destination. Every sender reaches the fax receiver, known or not, and no sender is added as a Member. The call is recorded under the sender when they are a workspace member, and under the fax owner otherwise. If the number has no fax owner, a fax from an unknown sender is recorded as fax_failed and the call ends.

One number, one inbound mode. A number receives voice calls or faxes, not both. To support both 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. When it completes, Gravity Rail stores a lossless multipage PDF and the original TIFF as private, encrypted files in the landing folder, owned by the fax owner.
4. Any Fax Received actions run — for example, starting a Workflow Chat whose AI agent reads the pages. With no actions set up, the fax is filed and nothing else happens.

Failed transmissions (line drop, T.30 error) set terminationReason = fax_failed on the PhoneCall record, with the reason in failureDetail. Check the phone number's Activity tab for these entries. A partial or failed fax files no documents.

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

Received documents belong to the fax owner and sit in the landing folder, so they follow that folder's sharing. Members who need to open received faxes need access to the landing folder. A Workflow started by a Fax Received action follows the Workflow's own permissions.

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
The fax panel says faxes are not being received	Missing fax owner or landing folder, or the owner cannot open the folder	Choose the missing field under Enable fax, or use Fix this to give the owner's role access to the folder.
Fax attempt records in Activity but no documents	The line was not ready, or the transmission failed	Check the failureDetail on the fax_failed entry.
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 our media stream. Contact support with the PhoneCall ID.
Documents are filed but nothing else happens	No Fax Received actions	Set up a Fax Received action to start a Workflow Chat or notify someone.
An unknown sender's fax ends with fax_failed straight away	The number has no fax owner	Choose a Fax Owner under Enable fax, or give the number an owner.
SMS stopped working after enabling fax	Voice and SMS are separate	Fax only changes how calls are answered. Check the phone number's Enable SMS checkbox — it should still be on.
Caller's machine reports a send failure but no PhoneCall record appears	Call never connected	The call was never answered; likely a phone number configuration issue or the number was still answering voice calls when the call arrived. Contact support with the number and the time of the call.

Common Setups

Referral intake line

• Channels: Enable fax
• Fax Owner: Intake Agent
• Fax landing folder: a Referrals folder the intake team can open
• Fax Received action: start the referral intake Workflow, whose AI agent reads the pages and creates records from them

Administrative documents

• Channels: Enable fax
• Fax landing folder: an Incoming documents folder
• Fax Received action: notify the office manager

Related

• Phone & Voice — Phone number setup, SMS, and routing rules
• Voice — Voice configuration
• Actions — Setting up what happens when a fax is received
• Workflows — Building the Workflow that processes inbound faxes
• Files — How Gravity Rail stores and retrieves file attachments