TwiML™ for Programmable Fax
We have made the difficult decision to disable Programmable Fax for all accounts on December 17, 2021. For new and inactive accounts, access to Programmable Fax is disabled effective immediately. We recognize the challenges this decision might cause and have provided detailed migration plans to prevent disruptions.
For Japan customers, please refer to this migration plan. For all other customers, please refer to this migration plan. Learn more.
All Fax functionality with Twilio takes advantage of TwiML, the Twilio markup language. When Twilio reaches out to your application for instructions, you respond and instruct Twilio on how to proceed. You either do this directly by responding with TwiML, or you can use a Helper Library to manage your responses.
What is TwiML?
TwiML is a set of instructions you can use to tell Twilio what to do when you receive an incoming fax – or for that matter an SMS or phone call. For a full overview, feel free to read through the TwiML definition.
Twilio Programmable Fax and TwiML
When Twilio receives a call to an Incoming Phone Number that has been configured as a Fax number, you will receive an HTTP request to the FaxUrl
configured for that number. Your server should respond with TwiML that then instructs Twilio how to proceed.
Twilio's request to your application
Twilio makes HTTP requests to your application just like a web browser form submission, in the format application/x-www-form-urlencoded
. By including parameters and values in its requests, Twilio sends data to your application that you can parse and act upon before responding.
You can configure the URLs and HTTP Methods Twilio uses to make its requests via your account portal or using the REST API. By setting the 'Webhook' callback, you direct Twilio where to look when we receive an incoming fax. Merely set the 'A Fax Comes In' field on your desired phone number.
Twilio cannot cache POST
requests we make to your application.
If you want Twilio to cache static TwiML pages from your app, have Twilio make requests to your application using GET
.
The TwiML request for Programmable Fax will contain the following request parameters:
PARAMETER | DESCRIPTION |
---|---|
FaxSid | The 34-character unique identifier for the fax |
AccountSid | The account from which the fax was sent |
From | The caller ID or SIP From display name |
To | The phone number or SIP URI of the destination |
ApiVersion | The API version used to send the fax, which for this API will be "v1" |
Responding to Twilio after an incoming fax
When a message comes into one of your Twilio numbers, Twilio makes an HTTP request to the Webhook URL configured for that number, as shown above.
In your response to that request, you can tell Twilio what to do in response to the message. You can configure your number URLs here.
You will want to receive or reject the fax after receiving a request.
Twilio is a well-behaved HTTP client
Twilio behaves just like a web browser, so there's nothing new to learn.
- Cookies: Twilio accepts HTTP cookies and will include them in each request, just like a normal web browser.
- Redirects: Twilio follows HTTP Redirects (HTTP status codes
301
,307
, etc.), just like a normal web browser. - Caching: Twilio will cache files when HTTP headers allow it (via
ETag
andLast-Modified
headers) and when the HTTP method isGET
, just like a normal web browser.
Cookies
Twilio will keep cookie state across multiple requests involving the same two phone numbers. This allows you to treat the separate messages as a conversation, and store data about the conversation, such as a session identifier, in the cookies for future reference. Twilio will expire the cookies for that conversation after four hours of inactivity.
TwiML fax verbs
Most XML elements in a TwiML document are TwiML verbs. Verb names are case sensitive, as are their attribute names. There are only two TwiML fax verbs at this time:
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.