REST API: Deploying Carrier Pigeons

When you want to send someone a message, and don't particularly care if it gets there in a timely manner, or at all, sending via Twilio carrier pigeon is the solution for you.

HTTP POST to Pigeons/{PigeonSid}/Messages

To deploy one of your provisioned carrier pigeons with a message for delivery, make an HTTP POST to that pigeon's Messages list resource URI:


POST Parameters

Required Parameters

The following parameters are required in your POST to deploy the pigeon:

AddressThe address to which you want your message delivered. You must include either this parameter or the 'Lat' and 'Lng' parameters.
LatAlong with Lng, the geolocation coordinates of the location you want your message delivered.
LngAlong with Lat, the geolocation coordinates of the location you want your message delivered.
BodyThe text of the message you wish to deliver.
Optional Parameters

You may include the following parameters:

StatusCallbackA URL that Twilio will POST to when the pigeon either reaches its destination or comes under some sort of duress. Twilio will POST the PigeonSid as well as PigeonStatus.
FeedBeforeDeployIf true, Twilio will feed the pigeon before deploying it. This usually helps ensure a reliable delivery, although this isn't guaranteed. The default is false.
StatusCallback requests

In order to recieve notification when your message is delivered or (heaven forbid) your pigeon comes under duress you can specify a StatusCallback URL. Twilio will make a request to this URL when the Pigeon (and hence your message) reaches its terminal state. Twilio will include a status code in the body of this request that indicates the result of the pigeon's delivery attempt. The following are possible values for the status code:

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.


Send a pigeon to Jenny with a message begging her for a second chance:

  • POST /2010-04-01/Accounts/AC5ef87.../Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3/Messages


            <DateCreated>Fri, 1 Apr 2011 01:01:40 +0000</DateCreated>
            <DateUpdated>Fri, 1 Apr 2011 01:01:40 +0000</DateUpdated>
            <Body>Jenny, please accept this carrier pigeon as a token of my affection</Body>