TwiMLTM Voice: <Pigeon>

The <Pigeon> verb uses the new Twilio Carrier Pigeon service to send a message to a location during a phone call.

Verb Attributes

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

Attribute NameAllowed ValuesDefault Value
addresstext stringnone
latlatitude coordinatenone
lnglongitude coordinatenone
colorhexadecimal color code#ff0000
actionrelative or absolute URLnone
feedBeforeDeploytrue, falsefalse
statusCallbackrelative or absolute URLnone


The 'address' attribute takes a street address as a value. If specified, Twilio will deploy the carrier pigeon to this address to deliver your message.

lat and lng

The 'lat' and 'lng' attributes take geolocation coordinates as values. If specified, Twilio will deploy the carrier pigeon to this exact location to deliver your message.


The 'color' attribute takes a hexadecimal color code as a value. Twilio will paint the pigeon this color before sending the pigeon on its way.


The 'feedBeforeDeploy' attribute takes the values 'true' and 'false'. If you would like Twilio to feed the pigeon before deploying it to ensure the pigeon is happy and thus more likely to deliver your message, set this attribute's value to 'true'. The default is 'false'.

Note that pigeon feeding is a pay feature. We will debit your account 5 cents for each pigeon fed.


The 'action' attribute takes a URL as an argument. After processing the <Pigeon> verb, Twilio will make a GET or POST request to this URL with the form parameters 'PigeonStatus' and 'PigeonSid'. Using an 'action' URL, your application can receive synchronous notification that the pigeon was painted (if requested), fed (if requested), and deployed.

If you provide an 'action' URL, Twilio will use the TwiML received in your response to the 'action' URL request to continue the current call. Any TwiML verbs occuring after a <Pigeon> which specifies an 'action' attribute are unreachable.

If no 'action' is provided, <Pigeon> will finish and Twilio will move on to the next TwiML verb in the document. If there is no next verb, Twilio will end the phone call. Note that this is different from the behavior of <Record> and <Gather>. <Pigeon> does not make a request to the current document's URL by default if no 'action' URL is provided.

Request Parameters

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'action' URL:

PigeonSidThe Sid Twilio has assigned for this pigeon.
PigeonStatusThe current status of the pigeon. This is usually 'deployed'. But if you provide invalid latitude and longitude coordinates, or an invalid color, this is 'invalid'.


The 'method' attribute takes the value 'GET' or 'POST'. This tells Twilio whether to request the 'action' URL via HTTP GET or POST. This attribute is modeled after the HTML form 'method' attribute. 'POST' is the default value.


The 'statusCallback' attribute takes a URL as an argument. When the pigeon reaches its destination, or if something goes wrong in flight, Twilio will make an asynchronous POST request to this URL with the parameters 'PigeonStatus' and 'PigeonSid'. Note, 'statusCallback' always uses HTTP POST to request the given url.

Request Parameters

Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'statusCallback' URL:

PigeonSidThe Sid Twilio assigned for the pigeon.
PigeonStatusThe current status code of the pigeon and its message. See below for status code descriptions.

PigeonStatus code descriptions:

200The message was successfully delivered.
187Something terrible happened and the pigeon perished in-flight. Your message was not delivered.
502A bag lady in the park captured your pigeon and domesticated it. There is a very slim chance that your message will be delivered.


The "noun" of a TwiML verb is the stuff nested within the verb that's not a verb itself; it's the stuff the verb acts upon. These are the nouns for <Pigeon>:

plain textThe text of the message you want the pigeon to deliver. Don't make the message too long, since each pigeon can only carry 0.5kg of paper.

Nesting Rules

You can't nest any verbs within <Pigeon> and you can't nest <Pigeon> in any other verbs.

See Also

Twilio REST API Pigeons Resource


Example 1: Simple pigeon sending

This is the simplest case for <Pigeon>. When the caller calls, Twilio will deploy a red pigeon to the geolocation coordinates given without feeding it first.

<?xml version="1.0" encoding="UTF-8"?>
<!-- page located at -->
    <Pigeon lat="40.730833" lng="-73.9975">Rook to B6. Checkmate!</Sms>

Example 2: Sending messages over long flights

In this use case, we provide 'feedBeforeDeploy' and 'action' attributes. We want to feed the pigeon so that it can make it all the way to its final destination without dying. When the pigeon is fed and starts its flight, Twilio will make a request to the 'action' URL passing the parameter 'PigeonStatus'. If the pigeon is fed or has started its flight, 'PigeonStatus' will have the value 'fed' or 'in-flight'. If an invalid address was provided, 'PigeonStatus' will be 'invalid'.

Your web application can look at the 'PigeonStatus' parameter and decide what to do next.

<?xml version="1.0" encoding="UTF-8"?>
    <Pigeon address="196 Broadway, 2nd Floor Cambridge, MA 02139" action="/pigeonHandler.php" feedBeforeDeply='true'>
        Want to grab dinner in 5 - 7 days?

Example 3: Using statusCallback for outcome notification

In this example we provide a 'statusCallback' URL. When the pigeon either delivers the message, dies or is captured, Twilio will asynchronously request the 'statusCallback' URL with the parameter 'PigeonStatus'. If the message was successfully delivered, 'PigeonStatus' will be '200'. If the message failed to reach its destination, 'PigeonStatus' will contain the applicable status code.

<?xml version="1.0" encoding="UTF-8"?>
    <Pigeon address="109 Court St, Boston, MA 02109" statusCallback="/pigeonHandler.php">
        Watson, come here. I want to see you.