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. |
Receive a fax and provide a url endpoint
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
actioncallback with a POSTmethod. - Instead of being provided a
MediaUrlin the callback, the media file itself will be provided in a parameter calledMedia - The callback is sent using the
multipart/form-datacontent-type (notapplication/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?
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.