Twilio supports “Fallback” URLs on incoming phone numbers.
A Fallback URL is used when a fatal error occurs during a call. If Twilio cannot retrieve or execute TwiML from your server, it immediately sends a request to the number’s Fallback URL. This request includes ErrorCode and ErrorUrl parameters, which identify the error and the URL where it occurred. Your fallback endpoint can return additional TwiML, a custom error message, or logic to recover and continue the call or messaging session.
You can configure the Fallback URL in two ways:
Twilio Console – go to Active Numbers, select the number to configure, and locate the “Primary handler fails” field under Voice Configuration or Messaging Configuration. You can point this to a Studio Flow, TwiML Bin, Twilio Function, or Proxy Service.
REST API – When creating an incoming phone number via the Incoming Phone Numbers resource, set the FallbackUrl and FallbackMethod (GET or POST) for voice and SMS. Any valid URL is supported, including Twilio service endpoints such as Studio Flows, TwiML Bins, and Functions.
Problem: You need your Twilio application to keep accepting calls if your primary web server becomes unavailable.
Solution: Set your phone number’s Voice URL and its Voice Fallback URL.
If Twilio attempts the primary URL and encounters an HTTP error or connection failure, it will request the fallback URL instead. If the fallback responds with valid TwiML, Twilio will continue the call seamlessly.
Problem: You want callers to hear a custom error message instead of Twilio’s default application error message.
Solution: Create a TwiML document that uses or to deliver your custom message. Point your phone number’s Voice Fallback URL to this TwiML document. If Twilio encounters a fatal error, callers will hear your custom message instead of the default.
Example TwiML:
<?xml version="1.0" encoding="UTF-8" ?>
<Response>
<Say>
An application error has occurred.
Please call back later.
</Say>
</Response>
Problem: You need to be alerted when errors occur in your Twilio application.
Solution: Set your Fallback URL to an endpoint that reads the ErrorCode and ErrorUrl parameters from Twilio’s request. Your application can then log the details, send an email alert, or trigger other monitoring actions. You can respond with TwiML to play an error message for the caller or attempt to recover and continue the call.