TwiML™ Fax: <Receive>

The verb <Receive> instructs Twilio to receive an incoming fax. This 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.
storeMedia Whether or not to store received media in the fax media store (defaults to true). If setting to false please see below for more information.

 

Loading Code Samples...
Language
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive action="/fax/received"/>
</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 Samples...
Language
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive mediaType="image/tiff" storeMedia="true"></Receive>
</Response>
Specify file format with the mediaType attribute
Store Fax Image as TIFF

Specify file format with the mediaType attribute

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
ApiVersion The API version used to receive the fax, which for this API is "v1"
NumPages The number of pages received (only if successful)
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 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 that should not be stored on Twilio's servers after it is received, you can specify storeMedia="false" as an attribute on this verb. However, please note the following changes, limitations, and possible concerns:

An action callback must be specified, and the only supported method is POST. Instead of being provided a MediaUrl in the callback, the media file itself will be provided in a parameter called Media, and the callback will be sent using the multipart/form-data content-type (rather than the usual application/x-www-form-urlencoded).

The media will be permanently deleted on Twilio's side after the callback is successfully delivered. If we do not receive a 2xx HTTP response from your server, we will continue to try to deliver the callback (with media) for the next 2 hours (we will try every 2.5 minutes). 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?

We all do sometimes; code is hard. Get help now from our support team, or lean on the wisdom of the crowd browsing the Twilio tag on Stack Overflow.

1 / 1
Loading Code Samples...
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive action="/fax/received"/>
</Response>
<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <Receive mediaType="image/tiff" storeMedia="true"></Receive>
</Response>