TwiML™ Fax: <Receive>

The TwiML verb <Receive> instructs Twilio to receive an incoming fax. <Receive> accepts the fax and results in the creation of a new Fax instance resource.

Optional Element Attributes

ATTRIBUTE	DESCRIPTION
action	URL to consult when the fax has been received (or has failed)
method	HTTP method to use when requesting the action URL; `POST` or `GET`. Defaults to `POST`.
mediaType	The media type used to store media in the fax media store. Currently, supported values are: `application/pdf` (the default) and `image/tiff`.
pageSize	What size to interpret received pages as (defaults to `letter`, US Letter). Supported values: `letter`, `legal`, and `a4`.
storeMedia	Whether or not to store received media in the fax media store (defaults to `true`). If setting to `false` please see the below information.

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

Receive a fax and provide a url endpoint

Receive a Fax with Action URL

Receive a fax and provide a url endpoint

Loading Code Sample...

Next Sample

Show sample response

Example JSON API response

This code receives the incoming media and stores it on Twilio's servers in TIFF format. MediaUrl will point to the received media.

Store Fax Image as TIFF

This code receives the incoming media and stores it on Twilio's servers in TIFF format. MediaUrl will point to the received media.

Action Callback

If action is specified, the parameters sent in the action callback will include:

PARAMETER	DESCRIPTION
FaxSid	The 34-character unique identifier for the fax
AccountSid	The account on which the fax was received
From	The caller ID of the sending fax machine
To	The Twilio phone number receiving the fax
RemoteStationId	The transmitting subscriber identification (TSID) reported by the sending fax machine
FaxStatus	The status of the fax transmission (See the status property of the Fax resource)
ApiVersion	The API version used to receive the fax (for this API: `v1`)
NumPages	If successful, the number of pages received
MediaUrl	A media URL on Twilio's servers that can be used to fetch the received media. Note that this URL will expire after 2 hours, but a new URL can be fetched from the Fax instance resource
ErrorCode	A Twilio error code that gives more information about a failure, if any
ErrorMessage	A detailed message describing a failure, if any

Avoiding Media Storage

If you are expecting sensitive material, you can specify storeMedia="false" as an attribute on this verb. Twilio will not store the media on our servers at all if so. Please note the following changes, limitations, and possible concerns.
You must specify an action callback with a POST method.
Instead of being provided a MediaUrl in the callback, the media file itself will be provided in a parameter called Media
The callback is sent using the multipart/form-data content-type (not application/x-www-form-urlencoded).
The media will be permanently deleted on Twilio's side after the callback is successfully delivered.
If we receive any of 500, 502, 503 or 504 HTTP responses from your server, we will attempt to deliver the callback with the media every 2.5 minutes for up to 2 hours.
If we still have not received a 2xx response from your server after 2 hours, the media will be deleted.
Twilio still stores a metadata record of the received fax. If you wish to delete this record, you can do so using the REST API.

Need some help?