- API & Docs
<Pigeon> verb uses the new Twilio Carrier Pigeon service to send a message to a location during a phone call.
<Pigeon> verb supports the following attributes that modify its behavior:
|Attribute Name||Allowed Values||Default Value|
|color||hexadecimal color code||#ff0000|
|action||relative or absolute URL||none|
|statusCallback||relative or absolute URL||none|
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.
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'.
The 'action' attribute takes a URL as an argument. After processing the
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
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
<Pigeon> does not
make a request to the current document's URL by default if no 'action' URL is provided.
Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'action' URL:
|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'.|
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.
Twilio will pass the following parameters in addition to the standard TwiML Voice request parameters with its request to the 'statusCallback' URL:
|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:
|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.|
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
|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.|
You can't nest any verbs within
<Pigeon> and you can't nest
<Pigeon> in any other verbs.
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>
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>
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>