TwiML™ for Programmable Fax

What is TwiML?

TwiML is a set of instructions you can use to tell Twilio what to do when you receive an incoming fax, SMS, or phone call.

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 instructs Twilio how to proceed.

Twilio's request to your application

Twilio makes HTTP requests to your application just like a regular web browser, 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 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.

Twilio cannot cache POSTs. If you want Twilio to cache static TwiML pages, then have Twilio make requests to your application using GET.

The TwiML request for Programmable Fax will contain the following request parameters:

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

When a message comes into one of your Twilio numbers, Twilio makes an HTTP request to the message URL configured for that number.

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.

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 and Last-Modified headers) and when the HTTP method is GET, just like a normal web browser.


Twilio will keep cookie state across multiple SMS messages between 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:

  • <Receive>: receives an incoming fax, creating a new Fax instance resource
  • <Reject>: rejects the fax and list its status as canceled.

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.