Rate this page:

TwiML™ Voice: <Reject>

The <Reject> verb rejects an incoming call to your Twilio number without billing you. This is very useful for blocking unwanted calls.

If the first verb in a TwiML document is <Reject>, Twilio will not pick up the call. The call ends with a status of busy or no-answer, depending on the verb’s reason attribute. Any verbs after <Reject> are unreachable and ignored.

Using <Reject> as the first verb in your response is the only way to prevent Twilio from answering a call. Any other response will result in an answered call and your account will be billed.

If you are using Twilio's deprecated v2008 API, <Reject> will result in a billing event, because the call's state will transition from inbound to completed to reject the call. Using <Reject> with the v2010 API, as described in this document, will not result in a billing event. Learn how to upgrade from Twilio's v2008 API to the v2010 API here.

Verb Attributes

The <Reject> verb supports the following attributes that modify its behavior:

Attribute Name Allowed Values Default Value
reason rejected, busy rejected


The reason attribute takes the values rejected and busy. This tells Twilio what message to play when rejecting a call. Selecting busy will play a busy signal to the caller, while selecting rejected will play a standard not-in-service response. The default is rejected.

This is a preference and what is actually played back is determined by the caller’s service provider as they dictate what they want to playback to the caller.

Nesting Rules

You can’t nest any verbs within <Reject> and you can’t nest <Reject> in any other verbs.


Example 1: Reject a call playing a standard not-in-service message

Loading Code Sample...

        Reject a call playing a standard not-in-service message

        Loading Code Sample...

              Reject a call playing a busy signal

              Rate this page:

              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 by visiting Twilio's Stack Overflow Collective or browsing the Twilio tag on Stack Overflow.

              Loading Code Sample...

                    Thank you for your feedback!

                    Please select the reason(s) for your feedback. The additional information you provide helps us improve our documentation:

                    Sending your feedback...
                    🎉 Thank you for your feedback!
                    Something went wrong. Please try again.

                    Thanks for your feedback!