Twilio Exit API

If you already have an integration using the Twilio SMS API to send and receive SMS messages (basic send and receive only), you can use this guide to start sending your SMS messages through Bird without having to rewrite your API integration.

The Bird Twilio Exit API allows you to send SMS messages through Bird's Engagement Platform, using your existing Twilio Integration. It acts as an adapter that translates the requests and responses from the Twilio format to Bird format and vice versa.

How does it work?

Your Twilio integration will send the request using the Twilio API format to the Bird Twilio Exit API. Our API will accept the Twilio formatted request, translate it to Bird's format, process the message, and then translate our response to the Twilio API response format you're expecting, ta-da! You don't have to rewrite all of your integration to start sending messages via Bird.

Setup the integration

1. Setup your Bird Engagement Platform account

2. Install an SMS channel

3. Copy your main keys

4. Update your Twilio integration URL and keys

5. Setup your Webhook to receive events and incoming messages

Setup your Bird account

Login to your Bird Engagement Platform account or Sign up for a new account if you don't have one.

Install an SMS channel

You will need to install an SMS channel on a working phone number, follow this guide on how to install an SMS channel.

Copy your main keys

You will need:

• Your workspace ID (click Edit workspace to see your ID)
• Access key
• The phone number of the SMS channel you're sending messages from

Update your Twilio Integration

Now that you have all the keys you need, you will need to do minimal change to your existing Twilio integration.

1. Update the domain name from https://api.twilio.com to one of the following domains:

   • EU (for Europe region): https://eu-west-1.twilio.to.api.bird.com

   • US (for US region): https://us-west-1.twilio.to.api.bird.com

2. Update your AccountSid to use your Bird WorkspaceID

   • To change your WorkspaceID into a AccountSid, simply remove all the dashes and prefix it with AC

     eg: e5181997-2c83-4a0d-959a-612248ff5a19 → ACe51819972c834a0d959a612248ff5a19

3. Update your Token to use your Bird AccessKey

4. Update the “From” number to the phone number you used to setup the SMS channel on our end

That's it! You're ready to start sending SMS messages via Bird.

If you are using one of Twilio's SDKs we also advise you to go through the following guides for additional tips:

• I am using Twilio's PHP SDK
• I am using Twilio's Go SDK
• I am using Twilio's Ruby SDK

Setup a Webhook subscription

Setting up a webhook subscription can currently be done via the API using the following endpoint:

Set up a webhook subscription

post

Path parameters

organization_idstringRequired

The ID of the organization

workspace_idstringRequired

The ID of the workspace

Body

servicestringOptional

eventstringOptional

templatestringOptional

urlstringOptional

signingKeystringOptional

Responses

200

Successful response

400

Bad request

post

HTTPcURLJavaScriptPython

POST /organizations/{organization_id}/workspaces/{workspace_id}/webhook-subscription HTTP/1.1
Host: 
Content-Type: application/json
Accept: */*
Content-Length: 131

{
  "service": "text",
  "event": "text",
  "eventFilters": [
    {
      "key": "text",
      "value": "text"
    }
  ],
  "template": "text",
  "url": "text",
  "signingKey": "text"
}

No content

Here is an example of such a request

{
    "service": "channels",
    "event": "sms.inbound",
    "eventFilters": [{
        "key": "channelId",
        "value": "{{channel_id}}"
    }],
    "template": "twilio",
    "url": "https://your.site/webhook/url",
    "signingKey": "your-secret-signing-key"
}

Unlike Twilio, Bird does not sign webhooks with your AccessKey/ApiToken. Instead, webhooks are signed using the SigningKey specified during your webhook subscription.

Make sure you keep your SigningKey safe, as it's used to verify the authenticity of the webhook requests.

Full webhooks API documentation can be found here.

Setup a Webhook subscription to receive incoming messages

Setting up a webhook subscription is an optional step, and is only needed if you need to receive inbound messages (2-way messaging use case). Much like Twilio, Bird's webhooks are set up by channel instance. So, for SMS, webhooks are set up by number.

To receive webhooks for incoming SMS messages on your SMS channel, you need to set up a webhook subscription by using the above request. For incoming messages, set the event to sms.inbound. You can choose to receive this webhook in the twilio format by setting the template parameter to twilio.

Setup webhook subscription for status reports for outbound messages

You can also set up webhooks for status reports for outbound messages by using the sms.outbound event. This is required to make webhooks work for outbound messages, since we need a singing key to sign the request.

When you use StatusCallback to subscribe to webhooks for outgoing messages, this URL overwrites the default URL set in the above request and sets the template to use the twilio template, regardless of the subscription settings.

Bird also employs a more secure way of signing requests. When using the twilio template, we will sign our requests in two ways: the Twilio method, using the Twilio header, and the Bird method, with the Bird header.

Twilio Exit API Explained

Our Twilio Exit API translates requests using the Twilio format to the Bird format, before sending it to the Bird API. And on receiving a response form our API, it translates it back into the Twilio format. This section explains which endpoints are supported and how we translate and map fields between both APIs.

Endpoints

Currently, the Twilio Exit API is limited to sending SMS messages exclusively through your Twilio Integration. The supported endpoints are:

Operation	Endpoint
Send message	POST /2010-04-01/Accounts/{{workspaceID}}/Messages.json
Fetch message	GET /2010-04-01/Accounts/{{workspaceID}}/Messages/{{messageID}}.json
Delete message	DELETE /2010-04-01/Accounts/{{workspaceID}}/Messages/{{messageID}}.json
List messages	GET /2010-04-01/Accounts/{{workspaceID}}/Messages.json

Message response

The message object's response resembles Twilio's, though some fields may be empty. Below is an example of our responses:

JSON field	Status	Bird field	Example
body	🟢 Supported	body.text.text	"body": "Hello World!"
direction	🟢 Supported	direction	"direction": "outbound-api"
from	🟢 Supported	sender.connector.identifierValue	"from": "[phone]"
date_updated	🟢 Supported	updatedAt	"date_updated": "Fri, 18 Aug 2023 09:13:21 +0000"
uri	🟢 Supported	-	"uri": "/2010-04-01/Accounts/{account_sid}/Messages/{message_sid}.json"
account_sid	🟢 Supported	-	"account_sid":"ACe22001f4705b4f97b58b897891f60000"
to	🟢 Supported	receiver.contacts. identifierValue	"to":"[phone]" It is possible to send to more than 1 recipient in Bird. We will always return the first recipient.
date_created	🟢 Supported	createdAt	"date_created": "Fri, 18 Aug 2023 09:13:21 +0000"
status	🟢 Supported	status	"status": "queued" "status": "delivered"
sid	🟢 Supported	id	"sid": "SM2c315abb9c2f418ea6b0d5bedc530000"
api_version	🟢 Supported	-	"api_version": "2010-04-01"
subresource_uris	🟢 Supported	-	"subresource_uris": {"media": "....."}
subresource_uris.media	🟡 Returned but not supported	-	"media": "/2010-04- 01/Accounts/ACe22001f4705b4f97b58b897891f60000/Messages/S M2c315abb9c2f418ea6b0d5bedc530000/Media.json"
subresource_uris.feedback	🟡 Not returned	-	-
num_media	🟡 Always "0" for SMS	-	"num_media": "0" SMS has no media
messaging_service_sid	🟡 Always null	-	"messaging_ service_sid": null
price	🔴 Always null	-	"price": null
price_unit	🔴 Always ""	-	"price_unit": ""
error_code	🔴 Always null	-	"error_code": null
error_message	🔴 Always null	-	"error_message": null
num_segments	🔴 Always "1"	-	"num_segments": "1"
date_sent	🔴 Always null	-	"date_sent": null

Create message

Form field	Status
AccountSid (Path)	🟢 Use your Bird WorkspaceID
From (Required)	🟢 Supported. Must be the number of an active SMS channel in Bird.
To (Required)	🟢 Supported
Body (Optional)	🟢 Supported
StatusCallback (Optional)	🟢 Supported
ProvideFeedback (Optional)	🟡 Ignored
Attempt (Optional)	🟡 Ignored
SmartEncoded (Optional)	🟠 Always true, returns error if false
ShortenUrls (Optional)	🟠 Always true, returns error if false
SendAsMms (Optional)	🟠 Always true, returns error if false
ApplicationSid (Optional)	🔴 Returns error if used
MaxPrice (Optional)	🔴 Returns error if used
ValidityPeriod (Optional)	🔴 Returns error if used
ForceDelivery (Optional)	🔴 Returns error if used
ContentRetention (Optional)	🔴 Returns error if used
AddressRetention (Optional)	🔴 Returns error if used
PersistentAction (Optional)	🔴 Returns error if used
ScheduleType (Optional)	🔴 Returns error if used
SendAt (Optional)	🔴 Returns error if used
ContentVariables (Optional)	🔴 Returns error if used
RiskCheck (Optional)	🔴 Returns error if used
MessagingServiceSid (Optional)	🔴 Returns error if used
MediaUrl (Optional)	🔴 Returns error if used
ContentSid (Optional)	🔴 Returns error if used

Response

See message response.

List messages

Request

Filtering messages can be done using the following query string parameters:

Query parameter	Status
AccountSid (Path)	🟢 Use your Bird WorkspaceID
Page (Optional)	🟢 Supported
PageSize (Optional)	🟡 Supported, but with a maximum of 100
PageToken (Optional)	🟡 Supported, but not a UUID Twilio example: PASMd37199c9492c41d6aba793e6420f70df Adapter example: WyJ3b3Jrc3BhY2UjNjViNzU1ZTItNGRmNS00MTE0LTg3NWItNmZmY2Y5NzllNDk2I21lc3NhZ2VzI2VlOThhMTZlLTMyNDEtNDhkMy04Y2Q1LTg5OTBlMmM2OTkwMSIsIm1lc3NhZ2UiLCJjaGFubmVsIzVlNzg3ZGQxLWQzNjEtNDU3Ni1hY2MwLTNiOWUxMTRmMWY4OCNtZXNzYWdlcyIsIm1lc3NhZ2UjMTY5MjExODg4ODQ0NCNlZTk4YTE2ZS0zMjQxLTQ4ZDMtOGNkNS04OTkwZTJjNjk5MDEiXQ==
From (Optional)	🟠 Required parameter
To (Optional)	🔴 Returns error if used
DateSent (Optional )	🔴 Returns error if used

Response

JSON response	Channels field
page	🟢 Supported
page_size	🟢 Supported
start	🟢 Supported
end	🟢 Supported
first_page_url	🟢 Supported
previous_page_url	🟠 Always null
url	🟢 Supported
next_page_url	🟢 Supported
messages	🟢 Supported: See message response

Webhooks

Request for outgoing messages:

Key	Description
AccountSid	🟢 Supported
SmsSid	🟢 Supported
MessageSid	🟢 Supported
SmsStatus	🟢 Supported
MessageStatus	🟢 Supported
To	🟢 Supported
From	🟢 Supported
ApiVersion	🟢 Supported
RawDlrDoneDate	🔴 Not set

Request for incoming messages:

Key	Description
AccountSid	🟢 Supported
SmsSid	🟢 Supported
SmsMessageSid	🟢 Supported
MessageSid	🟢 Supported
SmsStatus	🟢 Supported
Body	🟢 Supported
From	🟢 Supported
To	🟢 Supported
ApiVersion	🟢 Supported
NumMedia	🟠 Always "0"
NumSegments	🟠 Always "1"
ToCountry	🟠 Always ""
ToState	🟠 Always ""
ToZip	🟠 Always ""
FromCountry	🟠 Always ""
FromState	🟠 Always ""
FromCity	🟠 Always ""
FromZip	🟠 Always ""