# 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](https://app.messagebird.com/auth/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](https://docs.messagebird.com/applications/enable-channels/sms/install-sms). ### Copy your main keys #### You will need: * Your [workspace ID](https://docs.messagebird.com/applications/general/organization-settings/how-to-find-a-workspace-id) (click **Edit workspace** to see your ID) * [Access key](https://app.messagebird.com/settings/access-keys) * 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 **** 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. {% hint style="info" %} 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](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api/using-twilio-php-sdk) * [I am using Twilio's Go SDK](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api/using-twilio-go-sdk) * [I am using Twilio's Ruby SDK](https://docs.bird.com/api/channels-api/supported-channels/programmable-sms/twilio-exit-api/using-twilio-ruby-sdk) {% endhint %} ### Setup a Webhook subscription Setting up a webhook subscription can currently be done via the API using the following endpoint: {% openapi src="" path="/organizations/{organization\_id}/workspaces/{workspace\_id}/webhook-subscription" method="post" %} [SMS-Webhook-twilio-2.yml](https://3210271997-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FdnJZeZvhOMhDQA8SpjQM%2Fuploads%2FQ8gpihs9epXmbMZgHjmT%2FSMS-Webhook-twilio-2.yml?alt=media\&token=1bce1175-4759-4cb7-84c1-c2bed4f949b4) {% endopenapi %} 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. {% hint style="warning" %} Make sure you keep your SigningKey safe, as it's used to verify the authenticity of the webhook requests. {% endhint %} Full webhooks API documentation can be found [here](https://docs.messagebird.com/api/notifications-api/api-reference/webhooks). #### 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:
OperationEndpoint
Send messagePOST /2010-04-01/Accounts/{{workspaceID}}/Messages.json
Fetch messageGET /2010-04-01/Accounts/{{workspaceID}}/Messages/{{messageID}}.json
Delete messageDELETE /2010-04-01/Accounts/{{workspaceID}}/Messages/{{messageID}}.json
List messagesGET /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 fieldStatusBird fieldExample
body🟢 Supportedbody.text.text"body": "Hello World!"
direction🟢 Supporteddirection"direction": "outbound-api"
from🟢 Supportedsender.connector.identifierValue"from": "+1234567890"
date_updated🟢 SupportedupdatedAt"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":"+31623456789"

It is possible to send to more than 1 recipient in Bird. We will always return the first recipient.

date_created🟢 SupportedcreatedAt"date_created": "Fri, 18 Aug 2023 09:13:21 +0000"
status🟢 Supportedstatus

"status": "queued"

"status": "delivered"

sid🟢 Supportedid"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) | :green\_circle: Use your Bird `WorkspaceID` | | `From` (Required) | :green\_circle: Supported. Must be the number of an active SMS channel in Bird. | | `To` (Required) | :green\_circle: Supported | | `Body` (Optional) | :green\_circle: Supported | | `StatusCallback` (Optional) | :green\_circle: Supported | | `ProvideFeedback` (Optional) | :yellow\_circle: Ignored | | `Attempt` (Optional) | :yellow\_circle: Ignored | | `SmartEncoded` (Optional) | :orange\_circle: Always true, returns error if false | | `ShortenUrls` (Optional) | :orange\_circle: Always true, returns error if false | | `SendAsMms` (Optional) | :orange\_circle: Always true, returns error if false | | `ApplicationSid` (Optional) | :red\_circle: Returns error if used | | `MaxPrice` (Optional) | :red\_circle: Returns error if used | | `ValidityPeriod` (Optional) | :red\_circle: Returns error if used | | `ForceDelivery` (Optional) | :red\_circle: Returns error if used | | `ContentRetention` (Optional) | :red\_circle: Returns error if used | | `AddressRetention` (Optional) | :red\_circle: Returns error if used | | `PersistentAction` (Optional) | :red\_circle: Returns error if used | | `ScheduleType` (Optional) | :red\_circle: Returns error if used | | `SendAt` (Optional) | :red\_circle: Returns error if used | | `ContentVariables` (Optional) | :red\_circle: Returns error if used | | `RiskCheck` (Optional) | :red\_circle: Returns error if used | | `MessagingServiceSid` (Optional) | :red\_circle: Returns error if used | | `MediaUrl` (Optional) | :red\_circle: Returns error if used | | `ContentSid` (Optional) | :red\_circle: Returns error if used | #### Response See [message response](#message-responses). ### List messages #### Request Filtering messages can be done using the following query string parameters:
Query parameterStatus
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 responseChannels 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:
KeyDescription
AccountSid🟢 Supported
SmsSid🟢 Supported
MessageSid🟢 Supported
SmsStatus🟢 Supported
MessageStatus🟢 Supported
To🟢 Supported
From🟢 Supported
ApiVersion🟢 Supported
RawDlrDoneDate🔴 Not set
Request for incoming messages:
KeyDescription
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 ""