Get Started

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:

/2010-04-01/Accounts/{AccountSid}/Pigeons/{PigeonSid}/Messages

POST Parameters

Required Parameters

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

Parameter Description
Address The address to which you want your message delivered. You must include either this parameter or the 'Lat' and 'Lng' parameters.
Lat Along with Lng, the geolocation coordinates of the location you want your message delivered.
Lng Along with Lat, the geolocation coordinates of the location you want your message delivered.
Body The text of the message you wish to deliver.
Optional Parameters

You may include the following parameters:

Parameter Description
StatusCallback A 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.
FeedBeforeDeploy If 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:

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.

Example

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

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

    Lat=37.777449&Lng=-122.432919&FeedBeforeDeploy=true&Body=Please+Jenny%2C+accept+this+carrier+pigeon+as+a+token+of+my+affection

    <TwilioResponse>
        <PigeonMessage>
            <Sid>PM90c6fc909d8504d45ecdb3a3d5b3556e</Sid>
            <DateCreated>Fri, 1 Apr 2011 01:01:40 +0000</DateCreated>
            <DateUpdated>Fri, 1 Apr 2011 01:01:40 +0000</DateUpdated>
            <AccountSid>AC5ef872f6da5a21de157d80997a64bd33</AccountSid>
            <Lat>37.777449</Lat>
            <Lng>-122.432919</Lng>
            <Body>Jenny, please accept this carrier pigeon as a token of my affection</Body>
            <Status>fed</Status>
            <Direction>pigeon-api</Direction>
            <ApiVersion>2010-04-01</ApiVersion>
            <Price>-0.15</Price>
            <Uri>/2010-04-01/Accounts/AC5ef872f6da5a21de157d80997a64bd33/Pigeons/PIe905d7e6b410746a0fb08c57e5a186f3/Messages/PM90c6fc909d8504d45ecdb3a3d5b3556e</Uri>
        </PigeonMessage>
    </TwilioResponse>