Get Started

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 Name Allowed Values Default Value
address text string none
lat latitude coordinate none
lng longitude coordinate none
color hexadecimal color code #ff0000
action relative or absolute URL none
method GET, POST POST
feedBeforeDeploy true, false false
statusCallback relative or absolute URL none

address

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.

color

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.

feedBeforeDeploy

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.

action

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:

Parameter Description
PigeonSid The Sid Twilio has assigned for this pigeon.
PigeonStatus The 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'.

method

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.

statusCallback

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:

Parameter Description
PigeonSid The Sid Twilio assigned for the pigeon.
PigeonStatus The current status code of the pigeon and its message. See below for status code descriptions.

PigeonStatus code descriptions:

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

Nouns

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>:

Noun Description
plain text The 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

Examples

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 http://example.com/simple_sms.xml -->
<Response>
    <Pigeon lat="40.730833" lng="-73.9975">Rook to B6. Checkmate!</Sms>
</Response>

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"?>
<Response>
    <Pigeon address="196 Broadway, 2nd Floor Cambridge, MA 02139" action="/pigeonHandler.php" feedBeforeDeply='true'>
        Want to grab dinner in 5 - 7 days?
    </Pigeon>
</Response>

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"?>
<Response>
    <Pigeon address="109 Court St, Boston, MA 02109" statusCallback="/pigeonHandler.php">
        Watson, come here. I want to see you.
    </Pigeon>
</Response>